# 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 API
  version: 1.0.0
extends: openapi/twilio-conversations-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: 22
- target: $.paths['/v1/Conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: List conversations
      effect: read
      questions:
      - Which conversations in my default service are still active?
      - Can I filter conversations to ones started within a date range?
      instructions:
      - text: List my conversations in state {state}.
        slots:
          state: query.State
      - text: List conversations from {start_date} to {end_date}.
        slots:
          start_date: query.StartDate
          end_date: query.EndDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new conversation
      effect: write
      questions:
      - How do I open a new multi-channel conversation thread?
      - Can a new conversation switch itself to inactive or closed after a set idle time?
      instructions:
      - text: Create a conversation called {friendly_name}.
        slots:
          friendly_name: requestBody.FriendlyName
      - text: Start a conversation with unique name {unique_name} that closes after {closed_timer}.
        slots:
          unique_name: requestBody.UniqueName
          closed_timer: requestBody.Timers.Closed
      - text: Create a conversation {friendly_name} that sends email from {email}.
        slots:
          friendly_name: requestBody.FriendlyName
          email: requestBody.Bindings.Email.Address
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a conversation
      effect: read
      questions:
      - Can I look up a conversation by its unique name rather than its SID?
      - What state is a particular conversation in right now?
      instructions:
      - text: Fetch conversation {conversation}.
        slots:
          conversation: path.Sid
      - text: Show me the settings and state of conversation {conversation}.
        slots:
          conversation: path.Sid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{Sid}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a conversation's name, state or timers
      effect: write
      questions:
      - Can I rename an existing conversation or change its state to closed?
      - Is it possible to change the inactivity timer on a conversation that already exists?
      instructions:
      - text: Rename conversation {conversation} to {friendly_name}.
        slots:
          conversation: path.Sid
          friendly_name: requestBody.FriendlyName
      - text: Set existing conversation {conversation} to state {state}.
        slots:
          conversation: path.Sid
          state: requestBody.State
      - text: Change the attributes stored on conversation {conversation} to {attributes}.
        slots:
          conversation: path.Sid
          attributes: requestBody.Attributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a conversation
      effect: destructive
      questions:
      - Can I remove an entire conversation thread from my service?
      - Will deleting a conversation fire webhooks unless I turn them off?
      instructions:
      - text: Delete conversation {conversation}.
        slots:
          conversation: path.Sid
      - text: Remove conversation {conversation} without triggering webhooks, setting the webhook header to {webhook_enabled}.
        slots:
          conversation: path.Sid
          webhook_enabled: header.X-Twilio-Webhook-Enabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List messages in a conversation
      effect: read
      questions:
      - Can I read a conversation's message history newest first?
      - What messages have been posted in a given conversation?
      instructions:
      - text: List the messages in conversation {conversation}.
        slots:
          conversation: path.ConversationSid
      - text: List messages in conversation {conversation} in {order} order.
        slots:
          conversation: path.ConversationSid
          order: query.Order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a message to a conversation
      effect: write
      questions:
      - How do I send a message into a conversation on behalf of a participant?
      - Can I attach media or a rich content template to a conversation message?
      - What's the maximum length of a conversation message body?
      instructions:
      - text: Post {body} to conversation {conversation}.
        slots:
          body: requestBody.Body
          conversation: path.ConversationSid
      - text: Send {body} to conversation {conversation} as author {author}.
        slots:
          body: requestBody.Body
          conversation: path.ConversationSid
          author: requestBody.Author
      - text: Send content template {content_sid} into conversation {conversation}.
        slots:
          content_sid: requestBody.ContentSid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Messages/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch one message from a conversation
      effect: read
      questions:
      - Can I pull up a single message by its SID inside a conversation?
      - Who authored a particular conversation message and when?
      instructions:
      - text: Fetch message {message_sid} from conversation {conversation}.
        slots:
          message_sid: path.Sid
          conversation: path.ConversationSid
      - text: Show the author and body of message {message_sid} in conversation {conversation}.
        slots:
          message_sid: path.Sid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Messages/{Sid}'].post
  update:
    x-apievangelist-phrasing:
      intent: Edit a message already in a conversation
      effect: write
      questions:
      - Can I edit the text of a message after it was posted to a conversation?
      - Is changing the subject of an existing conversation message supported?
      instructions:
      - text: Change the body of message {message_sid} in conversation {conversation} to {body}.
        slots:
          message_sid: path.Sid
          conversation: path.ConversationSid
          body: requestBody.Body
      - text: Update the attributes on existing message {message_sid} in conversation {conversation} to {attributes}.
        slots:
          message_sid: path.Sid
          conversation: path.ConversationSid
          attributes: requestBody.Attributes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Messages/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a message from a conversation
      effect: destructive
      questions:
      - Can I remove a single message someone posted in a conversation?
      - Is there a way to take back a message sent into a conversation thread?
      instructions:
      - text: Delete message {message_sid} from conversation {conversation}.
        slots:
          message_sid: path.Sid
          conversation: path.ConversationSid
      - text: Remove message {message_sid} in conversation {conversation} from the thread.
        slots:
          message_sid: path.Sid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Messages/{MessageSid}/Receipts/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch one delivery receipt for a message
      effect: read
      questions:
      - Can I look up a single delivery or read receipt by its SID?
      - What does one receipt on a conversation message tell me?
      instructions:
      - text: Fetch receipt {receipt_sid} for message {message_sid} in conversation {conversation}.
        slots:
          receipt_sid: path.Sid
          message_sid: path.MessageSid
          conversation: path.ConversationSid
      - text: Show delivery receipt {receipt_sid} on message {message_sid} of conversation {conversation}.
        slots:
          receipt_sid: path.Sid
          message_sid: path.MessageSid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Messages/{MessageSid}/Receipts'].get
  update:
    x-apievangelist-phrasing:
      intent: List delivery and read receipts for a message
      effect: read
      questions:
      - Was my conversation message delivered and read by everyone?
      - Which delivery and read receipts exist for a given message?
      instructions:
      - text: List all receipts for message {message_sid} in conversation {conversation}.
        slots:
          message_sid: path.MessageSid
          conversation: path.ConversationSid
      - text: Check who has read message {message_sid} in conversation {conversation}.
        slots:
          message_sid: path.MessageSid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Participants'].get
  update:
    x-apievangelist-phrasing:
      intent: List participants in a conversation
      effect: read
      questions:
      - Who is taking part in a given conversation?
      - Can I see every participant and their bindings for a conversation?
      instructions:
      - text: List the participants in conversation {conversation}.
        slots:
          conversation: path.ConversationSid
      - text: Show everyone who belongs to conversation {conversation}.
        slots:
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Participants'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a participant to a conversation
      effect: write
      questions:
      - How do I add an SMS or WhatsApp user to a conversation?
      - Can I add a chat user to a conversation by identity and give them a role?
      instructions:
      - text: Add chat user {identity} to conversation {conversation}.
        slots:
          identity: requestBody.Identity
          conversation: path.ConversationSid
      - text: Add phone number {address} to conversation {conversation} via our number {proxy_address}.
        slots:
          address: requestBody.MessagingBinding.Address
          conversation: path.ConversationSid
          proxy_address: requestBody.MessagingBinding.ProxyAddress
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Participants/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch one participant in a conversation
      effect: read
      questions:
      - Can I look up a conversation participant by their phone number instead of a SID?
      - What role and last-read position does a particular participant have?
      instructions:
      - text: Fetch participant {participant} in conversation {conversation}.
        slots:
          participant: path.Sid
          conversation: path.ConversationSid
      - text: Show the details of participant {participant} in conversation {conversation}.
        slots:
          participant: path.Sid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Participants/{Sid}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a participant in a conversation
      effect: write
      questions:
      - Can I change a participant's role in a conversation they already belong to?
      - Is it possible to mark which message a participant last read?
      instructions:
      - text: Give participant {participant} in conversation {conversation} role {role_sid}.
        slots:
          participant: path.Sid
          conversation: path.ConversationSid
          role_sid: requestBody.RoleSid
      - text: Mark message index {index} as last read for participant {participant} in conversation {conversation}.
        slots:
          index: requestBody.LastReadMessageIndex
          participant: path.Sid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Participants/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a participant from a conversation
      effect: destructive
      questions:
      - Can I take someone out of a conversation thread?
      - What happens when a participant is removed from a conversation?
      instructions:
      - text: Remove participant {participant} from conversation {conversation}.
        slots:
          participant: path.Sid
          conversation: path.ConversationSid
      - text: Kick participant {participant} out of conversation {conversation}.
        slots:
          participant: path.Sid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Webhooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List webhooks on a conversation
      effect: read
      questions:
      - Which webhooks are attached to one specific conversation?
      - Can I see the conversation-scoped webhooks without the service-wide ones?
      instructions:
      - text: List the webhooks scoped to conversation {conversation}.
        slots:
          conversation: path.ConversationSid
      - text: Show all webhook targets set up on conversation {conversation}.
        slots:
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Webhooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a webhook to one conversation
      effect: write
      questions:
      - How do I get a callback for events happening in one conversation only?
      - Can a conversation webhook fire on certain keywords or route into a Studio flow?
      instructions:
      - text: Add a {target} webhook to conversation {conversation} that posts to {url}.
        slots:
          target: requestBody.Target
          conversation: path.ConversationSid
          url: requestBody.Configuration.Url
      - text: Send conversation {conversation} into Studio flow {flow_sid} with a {target} webhook.
        slots:
          conversation: path.ConversationSid
          flow_sid: requestBody.Configuration.FlowSid
          target: requestBody.Target
      - text: Create a {target} webhook on conversation {conversation} triggered by keywords {triggers}.
        slots:
          target: requestBody.Target
          conversation: path.ConversationSid
          triggers: requestBody.Configuration.Triggers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Webhooks/{Sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch a conversation webhook's configuration
      effect: read
      questions:
      - Where does a particular conversation webhook send its events?
      - Can I check which event filters a conversation webhook uses?
      instructions:
      - text: Fetch webhook {webhook_sid} on conversation {conversation}.
        slots:
          webhook_sid: path.Sid
          conversation: path.ConversationSid
      - text: Show the URL and filters of webhook {webhook_sid} in conversation {conversation}.
        slots:
          webhook_sid: path.Sid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Webhooks/{Sid}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a conversation webhook
      effect: write
      questions:
      - Can I point an existing conversation webhook at a new URL?
      - Is it possible to change which events an existing conversation webhook listens for?
      instructions:
      - text: Point webhook {webhook_sid} on conversation {conversation} at {url}.
        slots:
          webhook_sid: path.Sid
          conversation: path.ConversationSid
          url: requestBody.Configuration.Url
      - text: Change existing webhook {webhook_sid} on conversation {conversation} to fire on {filters}.
        slots:
          webhook_sid: path.Sid
          conversation: path.ConversationSid
          filters: requestBody.Configuration.Filters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/Conversations/{ConversationSid}/Webhooks/{Sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a webhook from a conversation
      effect: destructive
      questions:
      - Can I stop a conversation from sending events to a webhook?
      - What removes a webhook I scoped to one conversation?
      instructions:
      - text: Delete webhook {webhook_sid} from conversation {conversation}.
        slots:
          webhook_sid: path.Sid
          conversation: path.ConversationSid
      - text: Stop webhook {webhook_sid} on conversation {conversation} by removing it.
        slots:
          webhook_sid: path.Sid
          conversation: path.ConversationSid
      method: generated
      generated: '2026-09-26'