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

const client = new Telnyx({
  apiKey: 'My API Key',
});

const response = await client.calls.actions.gatherUsingAI('call_control_id', {
  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',
  },
});

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

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

Gather using AI request

​
parameters
object
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

Example:
{
  "properties": {
    "age": {
      "description": "The age of the customer.",
      "type": "integer"
    },
    "location": {
      "description": "The location of the customer.",
      "type": "string"
    }
  },
  "required": ["age", "location"],
  "type": "object"
}
​
assistant
Assistant · object

Assistant configuration including choice of LLM, custom instructions, and tools.

​
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.

​
language
enum<string>
default:en

Language to use for speech recognition

Available options:
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
Example:

"en"

​
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.<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>
Example:

"Telnyx.KokoroTTS.af"

​
voice_settings
ElevenLabs Voice Settings · object

The settings associated with the voice selected

  • ElevenLabs Voice Settings
  • Telnyx Voice Settings
  • AWS Voice Settings
​
greeting
string

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.

Example:

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

​
send_partial_results
boolean

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.

Example:

false

​
send_message_history_updates
boolean

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.

Example:

false

​
message_history
object[]

The message history you want the voice assistant to be aware of, this can be useful to keep the context of the conversation, or to pass additional information to the voice assistant.

​
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"

​
interruption_settings
object

Settings for handling user interruptions during assistant speech

​
user_response_timeout_ms
integer
default:10000

The number of milliseconds to wait for a user response before the voice assistant times out and check if the user is still there.

Example:

5000

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"
}