> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Getting started

![Conversations API](/_fern-img/4aca378bc42e5f36e6035879c362ee1552f3bfb5c2fd30c4e9f5a0c8160c3ea6.webp)

## Who is this for?

The **Conversations API** is designed for developers and technical teams who want to extend Ada beyond its native channels. Typical users include teams that need to:

* Build and manage their own messaging frontends
* Integrate Ada with an existing email provider
* Connect Ada to third-party platforms or proprietary systems not supported out of the box

### Implementation example

To see a working implementation of a frontend that interacts with an Ada AI Agent via the Conversations API, visit our public repository for complete details: [ada-conversations-api-demo](https://github.com/AdaSupport/ada-conversations-api-demo).

## Core concepts

Now that you know [what the Conversations API does](/reference/conversations/overview#capabilities) and [who it serves](#who-is-this-for), let's explore its key principles. At a high level, the API is organized around a few main concepts:

* **Channel:** A communication pathway through which customers interact with your business. For custom channels, you create a new channel with a `messaging`, `email`, `voice`, or `sms` modality. An `sms` channel carries the text messages your Voice AI Agent sends during a call through your own SMS provider.

  > **Note**
  >
  > The `email` modality for custom channels **is not** the same as Ada's **native Email channel**, which is accessed through the [Email Conversations API](#want-to-work-with-the-native-email-channel).

* **Conversation:** A sequence of messages exchanged between participants on a specific channel. Participants can include the end user, the AI Agent, and human agents.

* **Message:** A unit of communication authored by a participant. With custom channels, the Conversations API supports text messages.

## Want to work with the native Email channel?

The **Email Conversations API** is an implementation of the Conversations API, designed specifically for Ada's native [Email](/docs/channels/email) channel. In this context, the same [concepts](#core-concepts) apply, with a few differences for the native Email channel:

* **Channel:** You don't create a new channel. Ada provides the native Email channel, and you interact with it via the Email Conversations API.
* **Message:** Messages are email-based (subject, body, optional cc/reply-as) and sent through the [dedicated endpoint](./create-email-conversation).
* **Webhook support:** Core lifecycle events (conversation started, message sent, conversation closed) are supported, but webhook coverage is more limited than for custom channels.

## Talk to your AI Agent

Setup begins with a common step, then branches based on your use case.

1. [Generate an API key](/reference/introduction/authentication#generate-an-ada-api-key), if you don't already have one.
2. For **custom channels**, [create a webhook](/reference/webhooks/overview#adding-an-endpoint-via-dashboard) and [subscribe to conversation events](/reference/webhooks/overview#supported-events). Then continue with the [custom channel instructions](#conversations-on-custom-channels).
3. For conversations over Ada's **native Email channel**, continue with the see [Email channel instructions](#conversations-on-the-native-email-channel).

### Conversations on custom channels

Use the Conversations API to create and run conversations over your own custom channels. The steps below show how to create a channel, start a conversation, exchange messages, and end the conversation programmatically.

#### 1. Create a custom channel

Make sure you declare a `modality` so that the AI Agent responds to users in the corresponding style.

#### Request example

**`Shell`**

```shell title="Shell"
    POST https://{bot-handle}.ada.support/api/v2/channels
    Authorization: Bearer <your-api-token>

        {
          "name": "My Custom Channel",
          "description": "A custom messaging channel for my AI Agent",
          "modality": "messaging",
          "metadata": {
            "webpage_host": "https://lovelace-chat.com"
          }
        }
```

#### 2. Create a conversation over your channel

If you have an existing end user, include their End User ID in the payload.

Otherwise, the Conversations API will make a new end user automatically. Make sure you save the End User ID from the response so you can send messages from this End User in the next step.

> **Note**
>
> **Important — Metadata ≠ Metavariables**
>
> The metadata object you send to create conversation does not create or set Ada [metavariables](https://docs.ada.cx/docs/automation/processes/process-management#variables).
> To create or update metavariables, use the [End Users API](https://docs.ada.cx/reference/end-users/overview).

When a conversation is successfully created, you'll receive a `v1.conversation.created` webhook event if subscribed.

#### Request example

**`Shell`**

```shell title="Shell"
    POST https://{bot-handle}.ada.support/api/v2/conversations
    Authorization: Bearer <your-api-token>

        {
        "channel_id": "5df263b7db5a7e6ea03fae9b",
        "metadata": {
            "started_from_help_center": true
            }
        }
```

#### 3. Send a message on behalf of the End User

#### Request example

**`Shell`**

```shell title="Shell"
    POST https://{bot-handle}.ada.support/api/v2/conversations/{conversation_id}/messages
    Authorization: Bearer <your-api-token>

        {
        "author": {
            "id": "5f7e0e2c1e7c7e000f0f9c3a",
            "role": "end_user",
            "avatar": "https://www.gravatar.com",
            "display_name": "Ada Lovelace"
            }
        },
        "content": {
            "body": "I need help with my order",
            "type": "text"
            }
        }
```

When a message is successfully sent, you'll receive a `v1.conversation.message` webhook event if subscribed. Note that the `author.role` will be `end_user`.

#### 4. Listen for AI Agent response

When the AI Agent responds to your end user's inquiry, you'll receive a `v1.conversation.message` webhook event if subscribed. Note that the `author.role` will be `ai_agent`.

#### 5. End a conversation on behalf of an end user

To end a conversation on behalf of the end user, call

```
POST /v2/conversations/{conversation_id}/end/
```

### Conversations on the native Email channel

How do you run conversations once you know the basics of the Email Conversations API for [Ada's native Email channel](#want-to-work-with-the-native-email-channel)? Building on that foundation, you'll configure a sender address, send conversations to Ada through the dedicated endpoint, and route replies for continuity.

For complete setup and implementation details, see [this help topic](/docs/channels/email/email-configuration/implementation-method#getting-started-with-the-email-api).