API Evangelist conversational phrasing for Ada Conversations API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Ada Conversations API
  version: 1.0.0
extends: openapi/ada-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: 11
- target: $.paths['/v2/export/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: Export conversations in bulk (v2 export)
      effect: read
      questions:
      - How do I export conversations created in a date range from the v2 export endpoint?
      - Can I bulk export conversations that were updated since a certain date?
      - What page size limits apply when exporting conversations through the v2 export?
      instructions:
      - text: Export conversations created between {created_since} and {created_to} using the v2 export.
        slots:
          created_since: query.created_since
          created_to: query.created_to
      - text: Pull every conversation updated since {updated_since} from the v2 export, {page_size} per page.
        slots:
          updated_since: query.updated_since
          page_size: query.page_size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data_api/v1.4/conversations'].get
  update:
    x-apievangelist-phrasing:
      intent: Export conversations via the legacy Data API v1.4
      effect: read
      questions:
      - How do I pull conversations from the older Data API v1.4?
      - Does the legacy v1.4 conversations export return a status message with results?
      instructions:
      - text: Use the legacy Data API v1.4 to fetch conversations created since {created_since}.
        slots:
          created_since: query.created_since
      - text: Fetch conversations updated between {updated_since} and {updated_to} from Data API v1.4.
        slots:
          updated_since: query.updated_since
          updated_to: query.updated_to
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/email/'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an email conversation with a customer
      effect: write
      questions:
      - Can my AI Agent email a customer first to start a conversation?
      - Which reply-from address can I use when the agent starts an email thread?
      - How do I open a conversation over Ada's native email channel?
      instructions:
      - text: Email {name} at {reply_to} to start a conversation about {subject}.
        slots:
          name: requestBody.name
          reply_to: requestBody.reply_to
          subject: requestBody.subject
      - text: Start an email conversation with {name} at {reply_to}, subject {subject}, saying {text}, and CC {cc}.
        slots:
          name: requestBody.name
          reply_to: requestBody.reply_to
          subject: requestBody.subject
          text: requestBody.text
          cc: requestBody.cc
      - text: Open an email thread with {reply_to} named {name} on {subject}, replying as {reply_as}.
        slots:
          reply_to: requestBody.reply_to
          name: requestBody.name
          subject: requestBody.subject
          reply_as: requestBody.reply_as
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a conversation on a custom channel
      effect: write
      questions:
      - How do I start a new conversation on my custom channel?
      - What happens if I start a conversation without an end user id?
      instructions:
      - text: Start a new conversation in channel {channel_id}.
        slots:
          channel_id: requestBody.channel_id
      - text: Open a conversation in channel {channel_id} for end user {end_user_id}.
        slots:
          channel_id: requestBody.channel_id
          end_user_id: requestBody.end_user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/{conversation_id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one conversation
      effect: read
      questions:
      - How do I look up the details of a single conversation by its id?
      - Can I check the current metadata and state of one specific conversation?
      instructions:
      - text: Get conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Show me the details of conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/{conversation_id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add metadata to a conversation
      effect: write
      questions:
      - How do I attach extra metadata to a conversation that's already running?
      - Does updating a conversation's metadata replace it or add to it?
      instructions:
      - text: Add metadata {metadata} to conversation {conversation_id}.
        slots:
          metadata: requestBody.metadata
          conversation_id: path.conversation_id
      - text: Tag existing conversation {conversation_id} with metadata {metadata}.
        slots:
          conversation_id: path.conversation_id
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/{conversation_id}/messages/'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the messages in one conversation
      effect: read
      questions:
      - How can I read the full message history of one conversation?
      - What's the most messages I can fetch per page for a single conversation?
      instructions:
      - text: Show me the messages in conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Get the next {limit} messages of conversation {conversation_id} after cursor {cursor}.
        slots:
          limit: query.limit
          conversation_id: path.conversation_id
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/{conversation_id}/messages/'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a message into a conversation
      effect: write
      questions:
      - How do I post an end user's message into an ongoing conversation?
      - Can I send a file message after uploading an attachment?
      instructions:
      - text: Send message {content} from {author} in conversation {conversation_id}.
        slots:
          content: requestBody.content
          author: requestBody.author
          conversation_id: path.conversation_id
      - text: Post {content} as {author} to conversation {conversation_id}.
        slots:
          content: requestBody.content
          author: requestBody.author
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/{conversation_id}/end/'].post
  update:
    x-apievangelist-phrasing:
      intent: End a conversation
      effect: destructive
      questions:
      - How do I close out a conversation once the customer is done?
      - Can I programmatically end a conversation from my custom channel?
      instructions:
      - text: End conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Close conversation {conversation_id} for good.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/{conversation_id}/end-handoff/'].post
  update:
    x-apievangelist-phrasing:
      intent: Hand a conversation back to the AI Agent
      effect: write
      questions:
      - How do I return a conversation from a human agent back to the AI Agent?
      - Does ending a handoff also end the whole conversation?
      - Will ending a handoff trigger the CSAT survey for the human agent?
      instructions:
      - text: End the human handoff in conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Give control of conversation {conversation_id} back to the AI Agent without closing it.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/conversations/{conversation_id}/attachments/'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file to a conversation
      effect: write
      questions:
      - How do I share a file with a customer in a conversation?
      - How large can a conversation attachment be, and how long does its link last?
      instructions:
      - text: Upload {file} to conversation {conversation_id}.
        slots:
          file: requestBody.file
          conversation_id: path.conversation_id
      - text: Attach file {file} to conversation {conversation_id} and give me the temporary URL.
        slots:
          file: requestBody.file
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'