Gather using AI (BETA)
POST/calls/:call_control_id/actions/gather_using_ai
BETA 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. At the moment only English is supported.
Expected Webhooks (see callback schema below):
call.ai_gather.ended
Request
Path Parameters
Unique identifier and token for controlling the call
- application/json
Body
required
Gather using AI request
Array [
]
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
Default value: Telnyx.LibriTTS.0
The voice to be used by the voice assistant. Currently we support ElevenLabs, Telnyx and AWS voices only, for ElevenLabs voices you can pass the voice as ElevenLabs.<model_id>.<voice_id>, for Telnyx voices you can pass the voice as Telnyx.<model_id>.<voice_id>, for AWS Polly voices you can pass the voice as AWS.Polly.<voice_id>
voice_settings
object
The settings associated with the voice selected
oneOf
The settings associated with the voice selected
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.
assistant
object
Default value: meta-llama/Meta-Llama-3.1-70B-Instruct
The model to be used by the voice assistant.
The system instructions that the voice assistant uses during the gather command
This is necessary only if the model selected is from OpenAI. You would pass the identifier for an integration secret /v2/integration_secrets that refers to your OpenAI API Key. Warning: Free plans are unlikely to work with this integration.
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.
The content of the message
Possible values: [assistant, user]
The role of the message sender
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.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded 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.
- application/json
default: Unexpected error
- application/json
Request samples
curl -L 'https://api.telnyx.com/v2/calls/:call_control_id/actions/gather_using_ai' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"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.LibriTTS.0",
"voice_settings": {
"voice_speed": 1.25
},
"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"
}
],
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}'
Response samples
{
"data": {
"result": "ok"
}
}
{
"errors": [
{
"code": "string",
"title": "string",
"detail": "string",
"source": {
"pointer": "string",
"parameter": "string"
},
"meta": {}
}
]
}