Attach an AI Assistant to a Call

Overview

The ai_assistant_start command lets you attach a pre-configured AI assistant to an active call. The assistant takes over the conversation, handles speech recognition, and responds using a voice of your choice — no additional infrastructure required. This is different from Gather using AI, which is purpose-built for collecting structured data. ai_assistant_start is for open-ended, conversational AI experiences.

Prerequisites

A Telnyx account with an active call in progress. Follow the Voice API getting started guide if you haven’t set that up.
An AI assistant. You can create one:
- No-code via the Portal: AI Assistants guide
- Via the API: Create an assistant

Once you have an assistant, note its id (format: assistant-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Start an AI Assistant on a Call

Send a POST request to ai_assistant_start with the call_control_id of the active call:

curl -X POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant": {
      "id": "assistant-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }'

That’s it. The assistant is now live on the call.

Webhooks

Once started, the assistant emits the following webhooks:

Event	Description
`call.conversation.ended`	The AI conversation has ended
`call.conversation_insights.generated`	Conversation summary and insights are available

Stream Message History Updates

By default you only learn what was said once the conversation ends. Set send_message_history_updates to true on ai_assistant_start to receive a call.ai_gather.message_history_updated webhook every time the conversation history changes — useful for live transcripts, agent-assist screens, or supervisor dashboards.

curl -X POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant": {
      "id": "assistant-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "send_message_history_updates": true
  }'

Each webhook carries the full message history so far, not just the new message:

{
  "data": {
    "record_type": "event",
    "event_type": "call.ai_gather.message_history_updated",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "message_history": [
        { "role": "assistant", "content": "Hi, how can I help you today?" },
        { "role": "user", "content": "I'd like to check my order status." }
      ]
    }
  }
}

Control It From the Assistant Instead

The same setting exists on the assistant itself, as telephony_settings.send_message_history_updates. When it is set, it overrides whatever the start command asked for, so an assistant can turn the webhooks on for every call it takes — or opt out of them entirely:

curl -L 'https://api.telnyx.com/v2/ai/assistants/{assistant_id}' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
    "telephony_settings": {
      "send_message_history_updates": true
    }
  }'

`telephony_settings.send_message_history_updates`	Result
unset	The `send_message_history_updates` value on `ai_assistant_start` decides.
`true`	Webhooks are sent, even if the start command did not ask for them.
`false`	Webhooks are never sent, even if the start command asked for them.

Messages exchanged privately with a transfer destination during warm transfer acceptance are never included in these webhooks unless the transfer tool is configured with end_user_target_context_mode: "shared".

Stop the Assistant

To stop the assistant and return control to your application:

curl -X POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_stop \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Add a Participant to an Existing Conversation

Once an AI assistant conversation is running, you can bring additional call legs into it using ai_assistant_join. For example, you can dial out to a new destination, wait for the person to answer, then add them to the ongoing conversation.

Prerequisites

An active AI assistant conversation with a known conversation_id. The conversation_id is returned in the 200 response of ai_assistant_start.

Example: Dial a new participant and add them to the conversation

Step 1 — Dial the new destination:

curl -X POST https://api.telnyx.com/v2/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "your-connection-id",
    "to": "+15555550100",
    "from": "+15555550199"
  }'

This returns a new call_control_id for the outbound leg. Step 2 — Wait for the call.answered webhook: When Telnyx sends a call.answered event for the new call leg, extract its call_control_id. Step 3 — Add the participant to the conversation:

Join the Conversation

Once you have the new call_control_id:

curl -X POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/ai_assistant_join \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "participant": {
      "id": "{call_control_id}",
      "role": "user"
    }
  }'

The participant’s id must be the call_control_id of the call being added. The only supported role is "user".

Optional Participant Fields

Field	Type	Description
`name`	string	Display name for the participant
`on_hangup`	string	What happens when this participant hangs up: `"continue_conversation"` (default) or `"end_conversation"`

Next Steps

Explore the full AI Assistant API reference
Configure your assistant in the Portal
Collect structured data mid-call with Gather using AI

Voice API Fundamentals

Voice Features

AI Capabilities

Tutorials

Regional & Restrictions

API Reference

For AI Agents

Attach an AI Assistant to a Call

Overview

Prerequisites

Start an AI Assistant on a Call

Webhooks

Stream Message History Updates

Control It From the Assistant Instead

Stop the Assistant

Add a Participant to an Existing Conversation

Prerequisites

Example: Dial a new participant and add them to the conversation

Join the Conversation

Optional Participant Fields

Next Steps

​Overview

​Prerequisites

​Start an AI Assistant on a Call

​Webhooks

​Stream Message History Updates

​Control It From the Assistant Instead

​Stop the Assistant

​Add a Participant to an Existing Conversation

​Prerequisites

​Example: Dial a new participant and add them to the conversation

​Join the Conversation

​Optional Participant Fields

​Next Steps

Overview

Prerequisites

Start an AI Assistant on a Call

Webhooks

Stream Message History Updates

Control It From the Assistant Instead

Stop the Assistant

Add a Participant to an Existing Conversation

Prerequisites

Example: Dial a new participant and add them to the conversation

Join the Conversation

Optional Participant Fields

Next Steps