Skip to main content
POST
/
calls
/
{call_control_id}
/
actions
/
ai_assistant_start
JavaScript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.calls.actions.startAIAssistant('call_control_id');

console.log(response.data);
{ "data": { "result": "ok", "conversation_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a" } }

Documentation Index

Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
call_control_id
string
required

Unique identifier and token for controlling the call

Body

application/json

AI Assistant request

​
assistant
object

AI Assistant configuration. All fields except id are optional — the assistant's stored configuration will be used as fallback for any omitted fields.

​
voice
string
default:Telnyx.KokoroTTS.af

The voice to be used by the voice assistant. Currently we support ElevenLabs, Telnyx and AWS voices.

Supported Providers:

  • AWS: Use AWS.Polly.<VoiceId> (e.g., AWS.Polly.Joanna). For neural voices, which provide more realistic, human-like speech, append -Neural to the VoiceId (e.g., AWS.Polly.Joanna-Neural). Check the available voices for compatibility.
  • Azure: Use `Azure.. (e.g. Azure.en-CA-ClaraNeural, Azure.en-CA-LiamNeural, Azure.en-US-BrianMultilingualNeural, Azure.en-US-Ava:DragonHDLatestNeural. For a complete list of voices, go to Azure Voice Gallery.)
  • ElevenLabs: Use ElevenLabs.<ModelId>.<VoiceId> (e.g., ElevenLabs.BaseModel.John). The ModelId part is optional. To use ElevenLabs, you must provide your ElevenLabs API key as an integration secret under "voice_settings": {"api_key_ref": "<secret_id>"}. See integration secrets documentation for details. Check available voices.
  • Telnyx: Use Telnyx.<model_id>.<voice_id>
  • Inworld: Use Inworld.<ModelId>.<VoiceId> (e.g., Inworld.Mini.Loretta, Inworld.Max.Oliver). Supported models: Mini, Max.
  • xAI: Use xAI.<VoiceId> (e.g., xAI.eve). Available voices: eve, ara, rex, sal, leo.
Example:

"Telnyx.KokoroTTS.af"

​
voice_settings
ElevenLabs Voice Settings · object

The settings associated with the voice selected

​
greeting
string

Text that will be played when the assistant starts, if none then nothing will be played when the assistant starts. The greeting can be text for any voice or SSML for AWS.Polly.<voice_id> voices. There is a 3,000 character limit.

Example:

"Hello, can you tell me your age and where you live?"

​
interruption_settings
object

Settings for handling user interruptions during assistant speech

​
transcription
object

The settings associated with speech to text for the voice assistant. This is only relevant if the assistant uses a text-to-text language model. Any assistant using a model with native audio support (e.g. fixie-ai/ultravox-v0_4) will ignore this field.

​
message_history
(User message. · object | Assistant Message · object | Tool Message · object | System Message · object | Developer Message · object)[]

A list of messages to seed the conversation history before the assistant starts. Follows the same message format as the ai_assistant_add_messages command.

Messages sent by an end user

Example:
{
  "role": "user",
  "content": "Hello, I would like some help."
}
​
send_message_history_updates
boolean
default:false

When true, a webhook is sent each time the conversation message history is updated.

​
participants
object[]

A list of participants to add to the conversation when it starts.

​
client_state
string

Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

Example:

"aGF2ZSBhIG5pY2UgZGF5ID1d"

​
command_id
string

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

Example:

"891510ac-f3e4-11e8-af5b-de00688a4901"

Response

Successful response upon making a call control command that includes conversation_id.

​
data
Call Control Command Result With Conversation ID · object
Example:
{
  "result": "ok",
  "conversation_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a"
}