Skip to main content

Start AI Assistant (BETA)

POST 
/calls/:call_control_id/actions/ai_assistant_start

BETA - Start an AI assistant on the call.

Request ​

Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call

Body

required

AI Assistant request

    assistant

    object

    AI Assistant configuration

    id string

    The identifier of the AI assistant to use

    openai_api_key_ref string

    Reference to the OpenAI API key. Required only when using OpenAI models

    AI Assistant configuration

    voice VoiceConfig (string)

    Default value: Telnyx.LibriTTS.0

    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.

    • 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>

    voice_settings

    object

    The settings associated with the voice selected

    oneOf

    api_key_ref string

    The identifier for an integration secret /v2/integration_secrets that refers to your ElevenLabs API key. Warning: Free plans are unlikely to work with this integration.

    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.

    interruption_settings

    object

    Settings for handling user interruptions during assistant speech

    enable boolean

    Default value: true

    When true, allows users to interrupt the assistant while speaking

    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.

    model string

    Default value: distil-whisper/distil-large-v2

    The speech to text model to be used by the voice assistant. distil-whisper/distil-large-v2 is lower latency but English-only. openai/whisper-large-v3-turbo is multi-lingual but slightly higher latency.

    client_state string

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

    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.

Responses ​

200: Successful response upon making a call control command.

Schema

    data

    object

    result string

default: Unexpected error

Schema

    errors

    Error[]

  • Array [

    • code integerrequired
    title stringrequired
    detail string

    source

    object

    pointer json-pointer

    JSON pointer (RFC6901) to the offending entity.

    parameter string

    Indicates which query parameter caused the error.

    meta object

  • ]

Request samples

curl -L 'https://api.telnyx.com/v2/calls/:call_control_id/actions/ai_assistant_start' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "assistant": {
    "id": "string",
    "openai_api_key_ref": "string"
  },
  "voice": "Telnyx.LibriTTS.0",
  "voice_settings": {
    "api_key_ref": "my_elevenlabs_api_key"
  },
  "greeting": "Hello, can you tell me your age and where you live?",
  "interruption_settings": {
    "enable": true
  },
  "transcription": {
    "model": "distil-whisper/distil-large-v2"
  },
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}'

Response samples

{
  "data": {
    "result": "ok"
  }
}