# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Twilio - Conversations Roles API
  version: 1.0.0
extends: openapi/twilio-roles-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/v1/Roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List user roles
      effect: read
      questions:
      - Which user roles are defined in my default conversations service?
      - Can I see every role and the permissions it grants?
      instructions:
      - text: List the user roles in my default service.
      - text: Show my roles, {page_size} per page.
        slots:
          page_size: query.PageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user role with permissions
      effect: write
      questions:
      - How do I define a new role that limits what users can do in conversations?
      - Can a role be scoped to a conversation or to the whole service?
      instructions:
      - text: Create a {type} role named {friendly_name} with permission {permission}.
        slots:
          type: requestBody.Type
          friendly_name: requestBody.FriendlyName
          permission: requestBody.Permission
      - text: Add role {friendly_name} of type {type} granting {permission}.
        slots:
          friendly_name: requestBody.FriendlyName
          type: requestBody.Type
          permission: requestBody.Permission
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Roles/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a user role
      effect: read
      questions:
      - What permissions does a particular role grant?
      - Can I look up one role by its SID?
      instructions:
      - text: Fetch role {role_sid}.
        slots:
          role_sid: path.Sid
      - text: Show the permissions of role {role_sid}.
        slots:
          role_sid: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Roles/{Sid}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a role's permissions
      effect: write
      questions:
      - Can I change the permissions on a role that already exists?
      - Does updating a role replace its whole permission list?
      instructions:
      - text: Set the permissions of role {role_sid} to {permission}.
        slots:
          role_sid: path.Sid
          permission: requestBody.Permission
      - text: Update existing role {role_sid} so it grants {permission}.
        slots:
          role_sid: path.Sid
          permission: requestBody.Permission
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Roles/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user role
      effect: destructive
      questions:
      - Can I remove a role I no longer use from my service?
      - What deletes a user role permanently?
      instructions:
      - text: Delete role {role_sid}.
        slots:
          role_sid: path.Sid
      - text: Remove user role {role_sid} from my default service.
        slots:
          role_sid: path.Sid
      method: generated
      generated: '2026-09-26'