Creating a Custom Handoff

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

1. On the Ada Dashboard, go to Config > AI AGENT > Handoffs, then open the Handoffs tab.
2. Click New Handoff.
3. Give the handoff a descriptive name and description. The AI Agent uses the name and description to reason about when this handoff should be triggered (for example, “Live Agent Support” with a description like “Transfer the end user to a live agent for complex account issues”).

In the handoff content editor, add an HTTP Request block. This block makes an API call to your integration’s endpoint when the handoff is triggered, notifying your system that a conversation needs a human agent.

Configure the block with the following settings:

• URL: The endpoint on your integration that receives handoff notifications. For example: https://your-server.com/webhooks/start-handoff (or your ngrok URL during local testing).
• Method: POST
• Headers: Include any authentication headers your integration requires (not required for the demo repo, but recommended for production—see Authenticating the handoff trigger for details).
• Body Content: Include the conversation context your human agents need. The demo repo requires a key ada_conversation_id with the conversation_id variable given as a value. We recommend passing on at least the conversation_id so your handoff can identify which conversation was handed off.
• Pausing the conversation: Ensure the checkbox for pausing the conversation is enabled. This will pause the execution of the AI Agent until the handoff is complete.
• Handoff Integration Identifier: The value for this field will be the identifier used for your handoff integration. This identifier will help you distinguish the messages intended for your handoff through the event payload. For the demo repo, the expected value to set is “custom-handoff”.

When the AI Agent determines a conversation should be handed off:

1. Ada executes the handoff flow, including any blocks you’ve configured (such as text messages or capture blocks that run before the HTTP Request block).
2. The HTTP Request block sends a POST request to your integration’s endpoint with the conversation details.
3. Your integration receives the request and can begin managing the handoff, such as routing the conversation to an available human agent.
4. The conversation enters a handoff state in Ada. While in this state, the AI Agent stops responding to end user messages, and your integration is responsible for relaying messages between the end user and the human agent.

Your endpoint receives the POST request from Ada’s HTTP Request block. The request body contains the data you configured in Step 1, including the conversation_id.

1
from fastapi import Request, HTTPException
2
3
@app.post("/handoffs/start")
4
async def handle_handoff_start(request: Request):
5
    payload = await request.json()
6
7
    conversation_id = payload.get("conversation_id")
8
    if not conversation_id:
9
        raise HTTPException(status_code=400, detail="Missing conversation_id")
10
11
    # Store the conversation as an active handoff
12
    active_handoffs[conversation_id] = {
13
        "conversation_id": conversation_id,
14
        "status": "active",
15
    }
16
17
    # Notify a human agent that a new handoff is waiting
18
    notify_agent(conversation_id)
19
20
    return {"status": "ok"}

Your integration should maintain a mapping of active handoffs so it can route messages correctly. At a minimum, track:

• conversation_id: The Ada conversation that was handed off.
• The assigned human agent (once one picks up the handoff).
• The handoff status (waiting, active, ended).

This mapping allows your integration to route incoming webhook events to the correct human agent and ignore events for conversations not managed by your integration.

Fetch the transcript when a human agent accepts the handoff, so they have the full conversation context before responding to the end user.

Call the Get conversation messages endpoint with the conversation_id from the handoff. The endpoint supports pagination using cursor and limit parameters.

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

1
import requests
2
3
def get_transcript(conversation_id):
4
    messages = []
5
    page_url = f"{ADA_BASE_URL}/v2/conversations/{conversation_id}/messages?limit=100"
6
7
    while page_url:
8
        response = requests.get(
9
            page_url,
10
            headers={"Authorization": f"Bearer {ADA_API_KEY}"},
11
            page_url,
12
            headers={"Authorization": f"Bearer {ADA_API_KEY}"},
13
        )
14
        )
15
        response.raise_for_status()
16
        data = response.json()
17
18
        messages.extend(data["data"])
19
20
        page_url = data.get("meta", {}).get("next_page_url")
21
22
    return messages

The response contains a list of messages of "type": "message_logs", each with an author (including role and display_name) and content (text, file, or link). Use the author.role field to distinguish between messages from the end user (end_user), the AI Agent (ai_agent), and any human agents (human_agent).

1
{
2
  "data": [
3
    {
4
      "type": "message_logs",
5
      "message_id": "6900e297d458517e4b15787d",
6
      "author": {
7
        "role": "end_user",
8
        "id": "6900e28ff6f931ca8672f6dd"
9
      },
10
      "content": {
11
        "type": "text",
12
        "body": "I need help with my subscription."
13
      },
14
      "created_at": "2025-10-28T15:34:41+00:00"
15
    },
16
    {
17
      "type": "message_logs",
18
      "message_id": "6900e299d458517e4b157881",
19
      "author": {
20
        "role": "ai_agent"
21
      },
22
      "content": {
23
        "type": "text",
24
        "body": "I'd be happy to help! Let me connect you with a specialist."
25
      },
26
      "created_at": "2025-10-28T15:35:05+00:00"
27
    }
28
  ],
29
  "meta": {
30
    "next_page_url": "https://example.ada.support/api/v2/conversations/:conversation_id/messages?cursor=6658f91ea88ff7e389eff34d"
31
  }
32
}

If the response includes a value for meta.next_page_url, it indicates there are still additional messages to pull for the conversation. Ensure you continue calling this API and appending the results until it is null to build a complete transcript. After pulling the raw message data, format them into a human-readable transcript to be presented to the human agent so they have full context before engaging with the end user.

Send a message whenever the human agent types a reply in your support platform. Each message is sent to the active conversation identified by conversation_id.

Each message must specify the author as a human_agent and include a display_name so the end user knows who they’re talking to.

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": "human_agent",
8
      "display_name": "Alex from Support"
9
    },
10
    "content": {
11
      "type": "text",
12
      "body": "Hi Jane! I can see your subscription details. Let me look into this for you."
13
    }
14
  }

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

A successful response confirms the message was created and returns the message details.

1
{
2
  "id": "6789abcd1234ef567890",
3
  "conversation_id": "5df263b7db5a7e6ea03fae9b",
4
  "author": {
5
    "role": "human_agent",
6
    "display_name": "Alex from Support"
7
  },
8
  "content": {
9
    "type": "text",
10
    "body": "Hi Jane! I can see your subscription details. Let me look into this for you."
11
  },
12
  "created_at": "2025-10-21T12:10:00+00:00"
13
}

Ada triggers a v1.conversation.message webhook whenever the end user sends a message during the handoff. Your integration should listen for these events and forward the message content to the assigned human agent.

Each webhook event includes a JSON payload with the message details. During a handoff, the handoff_integration field identifies which handoff integration the message is associated with.

1
{
2
  "type": "v1.conversation.message",
3
  "timestamp": "2025-10-21T12:15:00+00:00",
4
  "data": {
5
    "message_id": "msg_789",
6
    "conversation_id": "5df263b7db5a7e6ea03fae9b",
7
    "end_user_id": "5df263b7db5a7e6ea03fae9c",
8
    "handoff_integration": "custom-handoff",
9
    "author": {
10
      "role": "end_user",
11
      "display_name": "Jane"
12
    },
13
    "content": {
14
      "type": "text",
15
      "body": "Yes, I upgraded my plan last week but I'm still being charged the old rate."
16
    },
17
    "ai_agent_domain": "example.ada.support"
18
  }
19
}

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 routes the message to the correct human agent.

• 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
        webhook = Webhook(WEBHOOK_SECRET)
11
        webhook.verify(payload, dict(headers))
12
    except WebhookVerificationError:
13
        raise HTTPException(status_code=400, detail="Invalid signature")
14
15
    msg = json.loads(payload)
16
    event_type = msg.get("type")
17
18
    if event_type == "v1.conversation.message":
19
      handle_webhook_message(msg["data"])
20
21
    return {"status": "ok"}

The v1.conversation.message webhook payload includes a handoff_integration field that identifies which integration the message is associated with:

• null: The message is for the AI Agent (no active handoff). Your custom handoff integration should ignore these.
• "custom-handoff": The message is for your custom handoff integration. Process these messages.
• Other values (e.g., "zendesk_chat", "salesforce"): The message is for a different handoff integration. Your custom handoff integration should ignore these.

1
HANDOFF_INTEGRATION_NAME = "custom-handoff"
2
3
def should_process_message(webhook_data):
4
    """Check if this webhook event is for our custom handoff integration."""
5
    handoff_integration = webhook_data.get("handoff_integration")
6
    return handoff_integration == HANDOFF_INTEGRATION_NAME

To ensure your agent only receives messages they should respond to, combine the handoff_integration check with others, like checking the author.role:

1
def handle_webhook_message(data):
2
    conversation_id = data["conversation_id"]
3
    handoff_integration = data.get("handoff_integration")
4
    author_role = data["author"]["role"]
5
6
    # Only process end user messages designated for our integration
7
    if (
8
        author_role == "end_user"
9
        and handoff_integration == HANDOFF_INTEGRATION_NAME
10
        and conversation_id in active_handoffs
11
    ):
12
        forward_to_human_agent(conversation_id, data)

This ensures your integration only responds to end user messages during handoffs that it is actively managing.

In our demo repository, incoming webhook messages are received, sorted, and forwarded to the agent in order to keep the ticket 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 forwarded to the agent in the correct order.

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

1
  # app/server/webhooks.py (excerpt)
2
3
  _global_event_queue = []
4
  _global_batch_task = None
5
  _global_batch_lock = asyncio.Lock()
6
7
  async def push_event_to_queue(event):
8
      """Batch events 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_event_queue, _global_batch_task
13
          _global_event_queue.append(event)
14
15
          if _global_batch_task is not None:
16
              _global_batch_task.cancel()
17
18
          _global_batch_task = asyncio.create_task(batch_process_events())
19
20
  async def batch_process_events():
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_event_queue, _global_batch_task
28
          events = _global_event_queue
29
          _global_event_queue = []
30
          _global_batch_task = None
31
32
      events.sort(key=lambda e: e.timestamp)
33
      for event in events:
34
          if event["type"] == "v1.conversation.message":
35
            await process_message_event(event)
36
          elif event["type"] == "v1.conversation.handoff.ended":
37
            await process_end_handoff_event(event)

When an end user sends a file, the webhook payload includes the file details in the content field.

1
{
2
  "type": "v1.conversation.message",
3
  "timestamp": "2025-10-21T12:20:00+00:00",
4
  "data": {
5
    "message_id": "msg_file_001",
6
    "conversation_id": "5df263b7db5a7e6ea03fae9b",
7
    "end_user_id": "5df263b7db5a7e6ea03fae9c",
8
    "handoff_integration": "custom-handoff",
9
    "author": {
10
      "role": "end_user",
11
      "display_name": "Jane"
12
    },
13
    "content": {
14
      "type": "file",
15
      "url": "https://s3.amazonaws.com/bucket/conversations/5df263b7db5a7e6ea03fae9b/5df263b7db5a7e6ea03fae9b/a1b2c3d4-e5f6-7890-abcd-ef1234567890/screenshot.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
16
      "mime_type": "image/png",
17
      "filename": "screenshot.png"
18
    },
19
    "ai_agent_domain": "example.ada.support"
20
  }
21
}

When your integration receives a file message:

1. Download the file from the content.url (this is a presigned URL valid for 7 days).
2. Forward the file to the human agent in your support platform.
3. Store the file reference if your platform needs it for later retrieval.

1
def handle_file_message(data):
2
    content = data["content"]
3
    file_url = content["url"]
4
    filename = content["filename"]
5
    mime_type = content["mime_type"]
6
7
    # Download the file
8
    file_response = requests.get(file_url)
9
    file_response.raise_for_status()
10
11
    # Forward to the human agent's platform
12
    forward_file_to_agent(
13
        conversation_id=data["conversation_id"],
14
        file_data=file_response.content,
15
        filename=filename,
16
        mime_type=mime_type,
17
    )

Use the Upload an attachment endpoint to upload the file. Attachments can only be uploaded when the conversation is in a handoff state. This endpoint documentation also highlights other restrictions like file size and type.

1
  POST https://<handle>.ada.support/api/v2/conversations/<conversation_id>/attachments
2
  Authorization: Bearer <your-api-key>
3
  Content-Type: multipart/form-data
4
5
  file=@/path/to/instructions.pdf

1
{
2
  "url": "https://s3.amazonaws.com/bucket/conversations/5df263b7db5a7e6ea03fae9b/5df263b7db5a7e6ea03fae9b/a1b2c3d4-e5f6-7890-abcd-ef1234567890/instructions.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
3
  "mime_type": "application/pdf",
4
  "filename": "instructions.pdf"
5
}

Use the Create a new message endpoint with the presigned URL from the upload response.

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": "human_agent",
8
      "display_name": "Alex from Support"
9
    },
10
    "content": {
11
      "type": "file",
12
      "url": "https://s3.amazonaws.com/bucket/conversations/5df263b7db5a7e6ea03fae9b/5df263b7db5a7e6ea03fae9b/a1b2c3d4-e5f6-7890-abcd-ef1234567890/instructions.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
13
      "mime_type": "application/pdf",
14
      "filename": "instructions.pdf"
15
    }
16
  }

1
import requests
2
3
def send_agent_file(conversation_id, agent_name, file_path):
4
    # Step 1: Upload the attachment
5
    with open(file_path, "rb") as f:
6
        upload_response = requests.post(
7
            f"{ADA_BASE_URL}/v2/conversations/{conversation_id}/attachments",
8
            headers={"Authorization": f"Bearer {ADA_API_KEY}"},
9
            files={"file": f},
10
        )
11
    upload_response.raise_for_status()
12
    attachment = upload_response.json()
13
14
    # Step 2: Send as a message
15
    message_response = requests.post(
16
        f"{ADA_BASE_URL}/v2/conversations/{conversation_id}/messages",
17
        headers={"Authorization": f"Bearer {ADA_API_KEY}"},
18
        json={
19
            "author": {
20
                "role": "human_agent",
21
                "display_name": agent_name,
22
            },
23
            "content": {
24
                "type": "file",
25
                "url": attachment["url"],
26
                "mime_type": attachment["mime_type"],
27
                "filename": attachment["filename"],
28
            },
29
        },
30
    )
31
    message_response.raise_for_status()
32
    return message_response.json()

The v1.conversation.handoff.ended event includes the conversation_id, end_user_id, handoff_integration, and ai_agent_domain.

1
{
2
  "type": "v1.conversation.handoff.ended",
3
  "timestamp": "2025-10-21T12:30:00+00:00",
4
  "data": {
5
    "conversation_id": "5df263b7db5a7e6ea03fae9b",
6
    "end_user_id": "5df263b7db5a7e6ea03fae9c",
7
    "handoff_integration": "custom-handoff",
8
    "ai_agent_domain": "example.ada.support"
9
  }
10
}

When you receive this event, verify that the handoff_integration matches your integration, then clean up the handoff:

1. Notify the human agent that the end user has ended the handoff.
2. Remove the conversation from your active handoffs tracking.
3. Clean up any resources associated with the handoff (for example, close the ticket in your support platform).

1
HANDOFF_INTEGRATION_NAME = "custom-handoff"
2
3
def handle_handoff_ended(data):
4
    conversation_id = data["conversation_id"]
5
    handoff_integration = data.get("handoff_integration")
6
7
    # Only process events for our integration
8
    if handoff_integration != HANDOFF_INTEGRATION_NAME:
9
        return
10
11
    if conversation_id in active_handoffs:
12
        # Notify the human agent
13
        notify_agent_handoff_ended(conversation_id)
14
15
        # Clean up the handoff
16
        del active_handoffs[conversation_id]

The v1.conversation.handoff.ended event signals that the handoff has ended and control has returned to the AI Agent. The conversation itself may still be active — the end user can continue chatting with the AI Agent after the handoff ends.

If the entire conversation ends (for example, the end user closes the chat), you’ll receive a separate v1.conversation.ended event. Your integration can optionally listen for this event as well, but the v1.conversation.handoff.ended event is the primary signal for managing handoff lifecycle.

End the handoff when:

• The human agent resolves the end user’s issue and explicitly closes the handoff.
• Your integration determines the handoff should end (for example, based on a timeout or routing rule).

After the handoff ends, the AI Agent resumes control of the conversation and responds to any subsequent end user messages.

To end a handoff, make a POST call to the endpoint with the conversation_id in the URL. No request body is required.

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

1
import requests
2
3
def end_handoff(conversation_id):
4
    response = requests.post(
5
        f"{ADA_BASE_URL}/v2/conversations/{conversation_id}/end-handoff",
6
        headers={"Authorization": f"Bearer {ADA_API_KEY}"},
7
    )
8
    response.raise_for_status()
9
10
    # Clean up the handoff from tracking
11
    if conversation_id in active_handoffs:
12
        del active_handoffs[conversation_id]
13
14
    return response.json()

Once the handoff ends:

• Ada sends a v1.conversation.handoff.ended webhook event to confirm the handoff has ended.
• The AI Agent resumes responding to end user messages.
• If configured, Ada may send a CSAT survey to the end user.

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.
• Handle handoff state errors: If you attempt to send a message or upload an attachment to a conversation that is not in a handoff state, you’ll receive a 422 Unprocessable Entity error. Make sure your integration handles this gracefully.

In a production environment, you should verify that incoming handoff requests actually originate from Ada’s HTTP Request block and not from an unauthorized source.

To do this, configure a shared secret as an authorization header in the HTTP Request block:

1. In the Ada Dashboard, first securely store your pre-shared key by going to Config > AI Agent > Actions > Manage Tokens
2. Next, go to Config > AI Agent > Handoffs to open the handoff and edit the HTTP Request block.
3. Add a header of your choice (Authorization is typical) with the secured variable in the value. For example: Authorization: Bearer @your_secret_key_variable.
4. In your integration, validate this header on every incoming handoff request.

1
HANDOFF_AUTH_KEY = os.getenv("HANDOFF_AUTH_KEY")
2
3
@app.post("/handoffs/start")
4
async def handle_handoff_start(request: Request):
5
    # Verify the authorization header
6
    auth_header = request.headers.get("Authorization")
7
    if auth_header != f"Bearer {HANDOFF_AUTH_KEY}":
8
        raise HTTPException(status_code=401, detail="Unauthorized")
9
10
    payload = await request.json()
11
    conversation_id = payload.get("conversation_id")
12
13
    # Process the event...
14
    return {"status": "ok"}

The HTTP Request block in the handoff flow can include Ada variables in the request body. This allows you to pass additional context about the end user or conversation to your integration.

For example, you can capture the end user’s email address, account number, or issue category using blocks earlier in the handoff flow, and then include those values in the HTTP Request body:

1
{
2
  "conversation_id": "{conversation_id}",
3
  "end_user_email": "{email}",
4
  "account_number": "{account_number}",
5
  "issue_category": "{issue_category}"
6
}

Your integration can use this data to pre-populate fields in your support platform, route the handoff to the right team, or provide the human agent with additional context.

If your organization uses multiple AI Agents (for example, separate Agents for different brands or regions), a single integration can handle handoffs for all of them by using the ai_agent_domain field in webhook events.

The ai_agent_domain field appears in every conversation webhook event and identifies which AI Agent environment the event originated from (for example, acme.ada.support or acme.eu.ada.support).

1
def handle_webhook_message(data):
2
    ai_agent_domain = data.get("ai_agent_domain")
3
    conversation_id = data["conversation_id"]
4
5
    # Route to the correct support team based on the AI Agent
6
    if ai_agent_domain == "acme-us.ada.support":
7
        route_to_team("us-support", conversation_id, data)
8
    elif ai_agent_domain == "acme-eu.ada.support":
9
        route_to_team("eu-support", conversation_id, data)
10
    else:
11
        route_to_team("default-support", conversation_id, data)

This pattern allows you to:

• Use a single webhook endpoint for all your AI Agents.
• Route handoffs to different teams or queues based on which Agent initiated the handoff.
• Apply different handling logic per Agent (for example, different SLAs or escalation rules).
• Dynamically determine the correct ADA_BASE_URL when making API calls back to Ada, by constructing it from the ai_agent_domain value.

Ensure your message ordering strategy is suitable for your production environment, where you may have multiple web servers responding to these events. Typically this will come in the shape of a shared buffer store.

At this point, your integration should be ready for production use — it can detect handoffs, relay messages between end users and human agents, handle file attachments, and transfer end users back to the AI Agent. From here, you can:

• Experiment with additional routing logic, agent assignment, or analytics for your custom handoff.
• Explore Conversations and Webhooks in the sidebar for complete endpoint details.