Sign in

v47

latestOpenAPI 3.1.0raw.githubusercontent.com2026-06-181,0851,7264.5 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

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

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

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.
  • xAI: Use xAI.<VoiceId> (e.g., xAI.eve). Available voices: eve, ara, rex, sal, leo.
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.

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.

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.

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.

user_response_timeout_msinteger

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

gather_ended_speechstring

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

Example request

{
  "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"
  },
  "voice": "Telnyx.KokoroTTS.af",
  "greeting": "Hello, can you tell me your age and where you live?",
  "send_partial_results": true,
  "send_message_history_updates": true,
  "message_history": [
    {
      "content": "Hello, what's your name?",
      "role": "assistant"
    },
    {
      "content": "Hello, I'm John.",
      "role": "user"
    }
  ],
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  "user_response_timeout_ms": 5000
}

Response

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

Example response

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