> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/reference/conversations/overview/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Conversations API For browser or mobile SDK sessions, use the [Messaging integration chooser](/messaging/introduction/choosing-an-integration). The custom-channel APIs below serve integrations that run on your server. The **Conversations API** turns Ada into a conversation engine you can extend anywhere. It provides a consistent, programmatic way to create and manage conversations and messages between end users, AI Agents, and human agents. Ada supports several **native channels** out of the box: [Chat](/docs/channels/chat), [Voice](/docs/channels/voice), [Email](/docs/channels/email), and [Social](/docs/channels/social). The Conversations API makes it possible to build **custom channels**, so you can extend Ada into proprietary apps, third-party platforms, or internal tools with developer-focused control. Download full OpenAPI spec ## Capabilities The Conversations API lets developers build and control the following: * **Create custom channels**: Define new entry points for Ada—power your own messaging frontend, connect to your email provider, or embed your AI Agent into channels Ada doesn't support out of the box. * **Create custom handoffs**: Connect new agent platforms—allow Ada to connect your end users with agents on the platform that fits your business. * **Start and manage conversations**: Programmatically begin conversations and track their progress. * **Close conversations**: End interactions cleanly so sessions are tracked and reported accurately. * **Subscribe to webhook events**: Receive real-time updates when conversations start, messages are sent, or conversations end. > **Note** > > Webhook support varies by channel. Not all event types are available across every channel. ## Native channel support Ada's native channels don't require the Conversations API, but you can still use it for programmatic visibility and control. This applies to [Chat](/docs/channels/chat), [Email](/docs/channels/email), and [Voice](/docs/channels/voice) via the standard Conversations API endpoints. With the Conversations API, you can: * Retrieve channel details * Listen to webhook events (conversation started, message sent, conversation closed) * End a conversation programmatically > **Info** > > * You **cannot** use the standard Conversations API endpoints to create new conversations or send end-user messages on the native Chat or Voice channels. > * For Email, use the [Email Conversations API](#email-conversations-api) for starting conversations over Ada's native Email channel. > * The Conversations API **does not** currently provide channel details or webhook events for **native [Social](/docs/channels/social)** channels. > * **Voice webhook support** requires the Unified Reasoning Engine. See the [Unified Reasoning Engine release note](/release-notes/2026/2/3) for rollout details. ### Email Conversations API The **Email Conversations API** provides a [dedicated endpoint](./create-email-conversation) for starting conversations over Ada's native [Email](/docs/channels/email) channel. It enables automation for customer inquiries that should be resolved via email, helping businesses streamline support and drive resolution. Common use cases include: * **Automating inquiries from website forms**: Process submissions from existing forms, such as Zendesk tickets or Salesforce contact forms. * **Handling support ticket backlogs**: Automatically process and resolve past support tickets. * **Integrating with other systems**: Connect platforms that allow customers to start email conversations. When an AI Agent is configured with [multiple email channels](/docs/channels/email/email-configuration/byo-domain), each address is represented as a distinct channel. Use `GET /v2/channels/?modality=email` to list every email channel on the AI Agent, and use the `reply_as` field on `POST /v2/conversations/email/` to specify which configured address the AI Agent should reply from. ## Webhook support It's important to understand how the Conversations API keeps your systems in sync. It does this through webhook events that let your systems track and react to key moments across conversations and messages: * `v1.conversation.created`: Triggered when a new conversation is created. * `v1.conversation.ended`: Triggered when `POST /v2/conversations/{conversation_id}/end/` is called. * `v1.conversation.message`: Triggered when a new message is added. For implementation details, see the [webhook documentation](/reference/webhooks/overview). > **Info** > > **If you use IP allowlisting:** Ada delivers webhooks through Svix. If your firewall only accepts traffic from approved source IPs, review [this section](/reference/webhooks/overview#ip-allowlist) for full details. ## Rate limits
Endpoint Rate Limits
`GET /v2/channels/` \- 100 requests per day \ \- 50 requests per minute \ \- 1 request per second
`POST /v2/channels/`
`POST /v2/conversations/` \- No daily limit \ \- 300 requests per minute \ \- 30 requests per second
`GET /v2/conversations//`
`PATCH /v2/conversations//`
`POST /v2/conversations//end/`
`POST /v2/conversations//attachments/`
`POST /v2/conversations//end-handoff/`
`POST /v2/conversations/email/` \- 60,000 requests per day \ \- 300 requests per minute \ \- 30 requests per second
`POST /v2/conversations/proactive/`
`GET /v2/conversations//messages/` \- No daily limit \ \- 500 requests per minute \ \- 150 requests per second
`POST /v2/conversations//messages/`
`POST /v2/conversations//sms/`
All other Conversations API endpoints adhere to our [global rate limits](/reference/introduction/limits). ## Limitations * Only text messages are supported at launch. Images and structured messages are not yet available. List Option Block, Sign In Block, and Apps with Widgets (including Widget Blocks) are not supported. * Conversation metadata is storage-only and does not create or update Ada metavariables. To set metavariables before a conversation starts, create the end user first with `POST /v2/end-users/` and then pass the `end_user_id` to `POST /v2/conversations/`. See the [End Users API developer guide](/reference/end-users/developer-guide) for step-by-step examples. ## Known issues * When working with custom channels, the channel name must be unique. > Overview