Attach an AI Assistant to a Call

Overview

Use answer with assistant.id when an AI assistant should handle an inbound call from pickup. Telnyx attempts to prepare the assistant before answering, reducing the work left to do after pickup. Use ai_assistant_start to attach an assistant to a call that is already answered, such as after an IVR or human interaction. 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 and a Call Control application receiving calls. 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).

Answer an inbound call with an assistant

For an inbound call that is still unanswered, send POST /v2/calls/{call_control_id}/actions/answer with the assistant configuration in the request body:

{
  "assistant": {
    "id": "assistant-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "instructions": "You are the receptionist for Acme Dental. Help callers schedule appointments.",
    "greeting": "Thank you for calling Acme Dental. How can I help?",
    "voice_settings": {
      "voice": "Telnyx.KokoroTTS.af_heart"
    },
    "transcription": {
      "model": "deepgram/flux",
      "language": "en"
    }
  }
}

Only assistant.id is required within the assistant object. The other fields override the stored assistant for this call. See the Answer call reference for the complete request schema. The call follows this sequence:

Telnyx accepts the command and attempts to warm up the assistant configuration and dependencies while the call remains unanswered.
Telnyx answers the call and emits call.answered. The HTTP success response can arrive before this webhook.
The assistant starts automatically on the answered call. Do not send a second ai_assistant_start command from the call.answered handler.

If the application first rings a business’s phones, send this combined answer request when the no-answer timeout expires and the assistant should take over. The caller’s inbound leg must still be unanswered. Answering that leg earlier and starting the assistant later cannot move preparation back before pickup.

Reuse one assistant with per-call settings

A single stored assistant can supply defaults for many businesses or call-by-call experiments. Send each call’s greeting, instructions, tools, voice, and transcription overrides inside assistant; a separate stored assistant per voice or business is not required. When migrating from ai_assistant_start, use these locations in the answer request:

Setting	`ai_assistant_start` request	`answer` request
Assistant ID	`assistant.id`	`assistant.id`
Instructions and tools	`assistant.instructions`, `assistant.tools`	`assistant.instructions`, `assistant.tools`
Greeting	`greeting`	`assistant.greeting`
Voice	`voice`	`assistant.voice_settings.voice`
Voice options	`voice_settings`	`assistant.voice_settings`, alongside `voice`
Speech recognition	`transcription`	`assistant.transcription`

The two commands use different voice-settings schemas. Select the supported assistant voice options from the Answer call reference rather than copying the start command’s entire voice_settings object unchanged. Omitted assistant fields retain stored values. A supplied voice_settings or transcription object replaces that entire stored object: include all settings that the call needs, including provider credentials where applicable. dynamic_variables merge with stored variables, with request values taking precedence. The top-level answer.transcription boolean controls standalone call transcription; it does not configure assistant speech recognition.

Understand and measure the remaining delay

Warm-up moves preparation before answer; it does not guarantee a shorter total time from the incoming call to the greeting. It does not wait for greeting audio to be synthesized or guarantee zero silence after pickup. If warm-up fails, Telnyx answers and starts the assistant without the warmed configuration. Compare the same voice and assistant configuration using the time from actual answer to the first audible greeting. Also track the total time from the incoming call to the greeting so that a later answer is visible in the results. Use call.answered for the answer event, rather than the HTTP response time, and verify the greeting onset from call audio. A playback-start event alone does not establish that speech was audible; the playback may contain silence.

Start an AI Assistant on an answered 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

Answer an inbound call with an assistant

Reuse one assistant with per-call settings

Understand and measure the remaining delay

Start an AI Assistant on an answered 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

​Answer an inbound call with an assistant

​Reuse one assistant with per-call settings

​Understand and measure the remaining delay

​Start an AI Assistant on an answered 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

Answer an inbound call with an assistant

Reuse one assistant with per-call settings

Understand and measure the remaining delay

Start an AI Assistant on an answered 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