# 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'