Sign in

v52

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB
Call Commands

Gather using AI

Gather parameters defined in the request payload using a voice assistant.

You can pass parameters described as a JSON Schema object and the voice assistant will attempt to gather these informations.

Expected Webhooks:

  • call.ai_gather.ended
  • call.conversation.ended
  • call.ai_gather.partial_results (if send_partial_results is set to true)
  • call.ai_gather.message_history_updated (if send_message_history_updates is set to true)
post/calls/{call_control_id}/actions/gather_using_ai

Path parameters

call_control_idstring required

Unique identifier and token for controlling the call

Request body

client_statestring

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

command_idstring

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

gather_ended_speechstring

Text that will be played when the gathering has finished. There is a 3,000 character limit.

greetingstring

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

language'af' | 'sq' | 'am' | 'ar' | 'hy' | 'az' | 'eu' | 'bn' | 'bs' | 'bg' | 'my' | 'ca' | 'yue' | 'zh' | 'hr' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fil' | 'fi' | 'fr' | 'gl' | 'ka' | 'de' | 'el' | 'gu' | 'iw' | 'hi' | 'hu' | 'is' | 'id' | 'it' | 'ja' | 'jv' | 'kn' | 'kk' | 'km' | 'ko' | 'lo' | 'lv' | 'lt' | 'mk' | 'ms' | 'ml' | 'mr' | 'mn' | 'ne' | 'no' | 'fa' | 'pl' | 'pt' | 'pa' | 'ro' | 'ru' | 'rw' | 'sr' | 'si' | 'sk' | 'sl' | 'ss' | 'st' | 'es' | 'su' | 'sw' | 'sv' | 'ta' | 'te' | 'th' | 'tn' | 'tr' | 'ts' | 'uk' | 'ur' | 'uz' | 've' | 'vi' | 'xh' | 'zu'

Language to use for speech recognition

parametersobject required

The parameters described as a JSON Schema object that needs to be gathered by the voice assistant. See the JSON Schema reference for documentation about the format

send_message_history_updatesboolean

Default is false. If set to true, the voice assistant will send updates to the message history via the call.ai_gather.message_history_updated callback in real time as the message history is updated.

send_partial_resultsboolean

Default is false. If set to true, the voice assistant will send partial results via the call.ai_gather.partial_results callback in real time as individual fields are gathered. If set to false, the voice assistant will only send the final result via the call.ai_gather.ended callback.

user_response_timeout_msinteger

The maximum time in milliseconds to wait for user response before timing out.

voicestring

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.<VoiceId>. (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, Inworld.TTS2.Loretta). Supported models: Mini, Max, TTS2.
  • Fish Audio: Use FishAudio.<ModelId>.<VoiceId> (e.g., FishAudio.s2.1-pro.<reference_id>). Supported models: s2.1-pro, s2-pro, s1. VoiceId is a Fish Voice-Library reference ID.
  • xAI: Use xAI.<VoiceId> (e.g., xAI.eve). Available voices: eve, ara, rex, sal, leo.
  • Humain: Use Humain.<VoiceId> (e.g., Humain.sara-ar). Available voices: sara-en, abdulaziz-en, sara-ar, abdulaziz-ar, nourah-ar, abdullah-ar. Native Arabic (Saudi dialect) and English voices only — no ModelId segment.

Example request

{
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  "greeting": "Hello, can you tell me your age and where you live?",
  "message_history": [
    {
      "content": "Hello, what's your name?",
      "role": "assistant"
    },
    {
      "content": "Hello, I'm John.",
      "role": "user"
    }
  ],
  "parameters": {
    "properties": {
      "age": {
        "description": "The age of the customer.",
        "type": "integer"
      },
      "location": {
        "description": "The location of the customer.",
        "type": "string"
      }
    },
    "required": [
      "age",
      "location"
    ],
    "type": "object"
  },
  "send_message_history_updates": true,
  "send_partial_results": true,
  "user_response_timeout_ms": 5000,
  "voice": "Telnyx.KokoroTTS.af"
}

Response

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

Example response

{
  "data": {
    "conversation_id": "d7e9c1d4-8b2a-4b8f-b3a7-9a671c9e9b0a",
    "result": "ok"
  }
}