Developer guide

Ada’s APIs include rate limits to ensure consistent performance and reliability. You’re unlikely to hit these during normal development, but it’s good practice to handle HTTP 429 Too Many Requests responses and implement retry logic. For more details, see:

• Conversations API rate limits
• Global rate limits

You only need to create a custom channel once per integration, not every time your service runs. Typically, this happens during initial setup or deployment, when you’re wiring up Ada to a new platform or system.

If you’re connecting Ada to multiple external systems (for example, Slack, SMS, or a web chat widget), you’ll create a separate channel for each integration.

Once a channel is created, you’ll reuse its unique channel ID in all future API calls that reference this integration. For example, when starting conversations or sending messages.

To create a channel, call the Create a new channel endpoint and include the applicable fields in the request. At a minimum, you’ll need to provide a name, description, and modality for your new channel.

1
  POST https://<handle>.ada.support/api/v2/channels
2
  Authorization: Bearer <your-api-key>
3
  Content-Type: application/json
4
5
  {
6
    "name": "My Custom Channel",
7
    "description": "A custom messaging channel for my AI Agent",
8
    "modality": "messaging",
9
    "metadata":{
10
      "webpage_host": "https://lovelace-chat.com"
11
    }
12
  }

If the call is successful, Ada returns a JSON response with the details of your new channel. Here’s the field that matters most for this step:

1
  {
2
    ...
3
    "id": "68f25a35072ad87710c1d96b",
4
    ...
5
  }

Now that you’ve created your custom channel and received its ID, you can complete your .env configuration.

Open the file and update the ADA_CHANNEL_ID value using the id returned in Ada’s response. For example: ADA_CHANNEL_ID=68f25a35072ad87710c1d96b.

Once saved, your app will automatically use this channel for all conversations and messages it creates.

$
  ADA_BASE_URL=https://example.ada.support
>
  ADA_API_KEY=abcd1234efgh5678ijkl
>
  ADA_CHANNEL_ID=68f25a35072ad87710c1d96b
>
  WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx

Start a new conversation when:

• You receive the first message from a user on your custom channel and no active conversation exists yet.
• You want to proactively start a thread or outreach message on behalf of a user.

Each new conversation in Ada establishes the context for all messages that follow. After a conversation starts, all messages from the user, Ada, or a human agent are linked to that conversation ID.

For this step, you’ll only need to include the following fields when creating a conversation:

• channel_id (required): The custom channel where this conversation will live (from Step 1).
• end_user_id (optional): The ID of a user that already exists in Ada.
  • If you don’t pass it, Ada will create a new end user and return the newly created end_user_id in the response.
  • If you do pass it, Ada will associate the conversation with that user.

For details on all supported parameters, see the endpoint request fields.

1
  POST https://<handle>.ada.support/api/v2/conversations
2
  Authorization: Bearer <your-api-key>
3
  Content-Type: application/json
4
5
  {
6
    "channel_id": "<your-channel-id>",
7
    "end_user_id": "<optional-user-id>"
8
  }

1
import requests
2
3
request_body = {"channel_id": ADA_CHANNEL_ID}
4
if user_id:
5
    request_body["end_user_id"] = user_id
6
7
response = requests.post(
8
    f"{ADA_BASE_URL}/api/v2/conversations",
9
    headers={"Authorization": f"Bearer {ADA_API_KEY}"},
10
    json=request_body,
11
)

If your request succeeds, Ada responds with a JSON payload that includes details about the new conversation.

Here are the key fields you’ll need to keep track of:

1
  {
2
    "id": "5df263b7db5a7e6ea03fae9b",
3
    "end_user_id": "5df263b7db5a7e6ea03fae9c",
4
    ...
5
  }

Send a message whenever your integration receives input from the user. For example, a chat message, a Slack thread reply, or a mobile text.

Each message you send must belong to an active conversation.

You’ll reference the conversation_id from Step 2 and the end_user_id associated with that conversation.

If the conversation has already ended, start a new one before sending more messages.

Each message must tell Ada who sent it and what was said. At minimum, include the following fields in your request body:

• conversation_id: The ID of the conversation.
• author: The person sending the message, with their role set to end_user.
• content: The message body.

Optional fields such as display_name, avatar, or additional metadata are described in the endpoint request fields.

1
  POST https://<handle>.ada.support/api/v2/conversations/<conversation_id>/messages
2
  Authorization: Bearer <your-api-key>
3
  Content-Type: application/json
4
5
  {
6
    "author": {
7
      "role": "end_user",
8
      "id": "<end_user_id>"
9
    },
10
    "content": {
11
      "type": "text",
12
      "body": "I need help with my order."
13
    }
14
  }

1
  import requests
2
3
  response = requests.post(
4
      f"{ADA_BASE_URL}/api/v2/conversations/{conversation_id}/messages",
5
      headers={"Authorization": f"Bearer {ADA_API_KEY}"},
6
      json={
7
          "author": {
8
              "role": "end_user",
9
              "display_name": display_name,
10
              "id": user_id,
11
              "avatar": avatar,
12
          },
13
          "content": {"type": "text", "body": text},
14
      },
15
  )
16
17
  response.raise_for_status()

When your request succeeds, Ada returns a JSON response with details about the new message. Here are the fields that matter most for this step:

1
  {
2
    "id": "6789abcd1234ef567890",
3
    "conversation_id": "5df263b7db5a7e6ea03fae9b",
4
    ...
5
  }

Ada triggers webhooks whenever events occur in a conversation, such as:

• When the AI Agent sends a message (v1.conversation.message)
• When a conversation starts (v1.conversation.created)
• When a conversation ends (v1.conversation.ended)

Your app can subscribe to these events in the Webhooks > Endpoints section of the Ada Dashboard. Once subscribed, Ada will POST event payloads to your configured webhook URL.

Each webhook event includes a JSON payload that represents the event type and associated data.

1
  {
2
    "type": "v1.conversation.message",
3
    "timestamp": "2025-10-21T12:15:00+00:00",
4
    "data": {
5
      "conversation_id": "5df263b7db5a7e6ea03fae9b",
6
      "author": {
7
        "role": "ai_agent",
8
        "display_name": "Ada"
9
      },
10
      "content": {
11
        "type": "text",
12
        "body": "Sure! You can check your order by clicking the link below."
13
      }
14
    }
15
  }

When your app receives this webhook, it can take the message text (content.body) and display it to the user, send it to a connected channel (like Slack), or log it for analytics.

To receive and process webhooks, your app must define an endpoint that matches the URL configured in the Ada Dashboard. This route handles incoming POST requests, verifies that they’re from Ada, and parses the message data.

• If you want to use a language-specific package, you can use the package provided by Svix as documented here.

• Alternatively, webhooks can be verified without their library using this manual verification guide.

For more information about how Ada uses webhooks, see this topic.

1
  from fastapi import Request, HTTPException
2
  from svix import Webhook, WebhookVerificationError
3
4
  @app.post("/webhooks/message")
5
  async def handle_message(request: Request):
6
      headers = request.headers
7
      payload = await request.body()
8
9
      try:
10
          # Verify that the request really came from Ada using your webhook signing secret
11
          webhook = Webhook(WEBHOOK_SECRET)
12
          webhook.verify(payload, dict(headers))
13
      except WebhookVerificationError:
14
          raise HTTPException(status_code=400, detail="Invalid signature")
15
16
      msg = json.loads(payload)
17
      process_message(msg)
18
      return {"status": "ok"}

In our demo repository, incoming webhook messages are received, sorted, and rendered in order to keep the chat experience real-time and conversational.

1. Webhooks are received one by one.
2. Each message is stored in a short-lived, in-memory queue per conversation.
3. A brief delay (e.g., 1–2 seconds) allows messages to accumulate into a micro-batch.
4. The batch is then sorted by timestamp.
5. Messages are displayed in the UI in the correct order.

This pattern preserves the conversational flow while still feeling real-time.

1
  # app/webhooks.py (excerpt)
2
3
  _global_msg_queue = []
4
  _global_batch_task = None
5
  _global_batch_lock = asyncio.Lock()
6
7
  async def push_message_to_queue(msg):
8
      """Batch messages in a queue to be processed after a delay to account for unordered messages"""
9
      global _global_batch_lock
10
11
      async with _global_batch_lock:
12
          global _global_msg_queue, _global_batch_task
13
          _global_msg_queue.append(msg)
14
15
          if _global_batch_task is not None:
16
              _global_batch_task.cancel()
17
18
          _global_batch_task = asyncio.create_task(batch_process_messages())
19
20
  async def batch_process_messages():
21
      """Process all messages in the queue after a delay"""
22
      global _global_batch_lock
23
24
      await asyncio.sleep(2)
25
26
      async with _global_batch_lock:
27
          global _global_msg_queue, _global_batch_task
28
          messages = _global_msg_queue
29
          _global_msg_queue = []
30
          _global_batch_task = None
31
32
      messages.sort(key=lambda m: m.timestamp)
33
      for msg in messages:
34
          push_message_to_chat(
35
              msg.data.conversation_id,
36
              msg.data.author.id,
37
              msg.data.author.role,
38
              msg.data.content,
39
              msg.data.author.display_name,
40
              msg.data.author.avatar,
41
          )    

When flushing a batch to Slack:

• Use the channel and thread identifier (thread_ts) associated with the Ada conversation id.
• Post in order after sorting.
• For user/bot rendering, map Ada’s author.role to Slack’s display (e.g., different user name/icon for ai_agent vs. end_user).

In our demo repository, incoming webhook messages are processed and displayed in the local chat UI:

1. The webhook payload is received and verified.
2. Message details (author, content, role, and so on) are passed to the UI handler.
3. The handler identifies the correct chat instance, converts the message to a UI element, and renders it in real time.

This flow keeps the chat interface responsive and aligned with incoming webhook events.

1
  def push_message_to_chat(
2
      conversation_id: str,
3
      user_id: str | None,
4
      role: str,
5
      content: MessageContent,
6
      display_name: str | None = None,
7
      avatar: str | None = None,
8
  ):
9
      """Convert a message from Ada's webhook into one displayed in the chat UI."""
10
11
      chat_ui = get_chat_ui(conversation_id)
12
      if not chat_ui or user_id == chat_ui.active_end_user_id:
13
          return
14
15
      chat_ui.add_message(user_id, role, content, display_name, avatar)      

• Differentiate roles visually:
  • Show the user’s messages aligned right (e.g., blue bubble).
  • Show Ada’s messages aligned left (e.g., gray bubble, Ada avatar).
  • If you support handoffs, render human agent messages in a distinct color or include the agent’s name.
• Show metadata when useful:
  • Timestamp each message.
  • Optionally show Delivered or Seen indicators.
  • Use display_name and avatar fields from the payload for personalization.
• Handle link messages:
  • Some messages (for example, CSAT surveys or links) use content.type: "link".
  • Render these as clickable links or buttons rather than plain text.
• Graceful endings:
  • When you receive a v1.conversation.ended event, disable inputs and show a Conversation closed notice.

If you’re not using a browser UI (for example, you’re integrating with Slack, Teams, or SMS), the same webhook data can be sent to those platforms instead of your UI:

• Slack: Use the chat.postMessage API to post Ada’s responses in the correct thread (matching the stored conversation_id to thread_ts mapping).
• SMS: Send Ada’s content.body to your messaging provider’s API.

When Ada sends a webhook containing the AI Agent’s response, your app needs to post that message back to Slack in the correct channel or thread.

1
  response = slack_client.chat_postMessage(
2
      channel=slack_channel_id,
3
      text=ada_message_text,
4
      thread_ts=slack_thread_ts
5
  )

Use your stored mapping between Ada’s conversation id and Slack’s channel/thread_ts to ensure replies appear in the right thread. This keeps the full conversation—both user messages and Ada’s responses—neatly organized within the same Slack thread.

Not every channel will have an explicit End chat control, but many include one (for example, a Close or End conversation button). In your custom channel, you can call the End a conversation endpoint when:

• The end user clicks an End Chat or equivalent UI action.
• The system detects inactivity or a timeout.
• Your integration’s workflow determines the chat should close automatically (for example, after a successful resolution).

After a conversation ends:

• No further messages can be sent to that conversation ID.
• Ada may send a follow-up webhook, such as a CSAT (customer satisfaction) survey link, depending on the AI Agent’s configuration.

A Customer Satisfaction (CSAT) survey lets end users rate their experience or leave comments after interacting with your AI Agent. The feedback helps you measure satisfaction, spot improvement opportunities, and track your AI Agent’s performance.

To end a conversation, all you need is the conversation ID of the active session. No request body is required: simply make a POST call to the endpoint that includes the conversation_id in the URL. This tells Ada that the conversation is complete and prevents any further messages from being added to it.

1
  POST https://<handle>.ada.support/api/v2/conversations/<conversation_id>/end
2
  Authorization: Bearer <your-api-key>

1
  import requests
2
3
  response = requests.post(
4
      f"{ADA_BASE_URL}/api/v2/conversations/{conversation_id}/end",
5
      headers={"Authorization": f"Bearer {ADA_API_KEY}"},
6
  )
7
  response.raise_for_status()

Once a conversation is ended:

• Ada stops processing new messages for that session.
• If configured, a CSAT survey link or closing message is sent as a v1.conversation.message webhook event.

• A conversation cannot be reactivated after it’s ended.
• The conversation ID remains valid for querying past messages or logs.
• Always ensure your front end reflects the closed state: disable input fields or prompt users to start a new conversation.

The Conversations API uses standard HTTP conventions for reporting errors. Here are a few best practices for production:

• Add retries with backoff: Retry failed requests after a short delay, increasing the delay each time.
• Handle rate limits: When you receive 429 Too Many Requests, check the Retry-After header and wait before retrying.
• Validate before sending: Double-check request fields and types before making an API call.
• Log and monitor errors: Capture response codes and request details to help diagnose issues later.
• Be user-friendly: If something goes wrong, surface a helpful message instead of letting the app fail silently.

At this point, your integration should be ready for production use — it can create conversations, send and receive messages, and handle webhooks reliably. From here, you can:

• Experiment with additional automation, logging, or analytics for your custom channel.
• Explore Channels, Conversations, and Webhooks in the sidebar for complete endpoint details.