AIGather

The <AIGather> verb collects specific information from call participants leveraging AI. It requires the child node <Parameters> to be provided with a JSON Schema object that describes the parameters to be gathered.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
action	URL where TeXML will send the gathered speech input. The same method (GET/POST) as set for the TeXML application is used. Transfers control of the current call to the TeXML file returned.		-
method	HTTP request type used to retrieve the next set of instructions.	GET, POST	POST

NOUN/VERB	DESCRIPTION
Greeting	Reads supplied text back to the caller when the gathering starts, if none then nothing will be played when the gathering starts.
Voice	The voice to be used by the voice assistant.
Parameters	The parameters are described as a JSON Schema object that needs to be gathered by the voice assistant. It needs to be provided within CDATA tags (see the example below).
MessageHistory	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. They can be provided as a list of <Message> nodes. Each <Message> node must contain a role attribute that can be either user or assistant. The role attribute is used to determine if the message is from the user or the assistant. The text of the message is provided in the <Message> node (see the example below).
Tools	The list of <Tools> to be used by the AI assistant. The <Tool> should contain at tool definition in json format. All of the available tools are defined in the Voice API Gather using AI documentation.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
name	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, we also support this notation for AWS Polly voices: Polly.voice_id	Telnyx.NaturalHD.Astra
api_key_ref	The reference to the ElevenLabs API key to be used for the voice assistant. The API key must be added to the account text-to-speech secrets /v2/text-to-speech/secret. Note: this is only used when using an ElevenLabs voice.	-
voice_speed	The voice speed to be used for the voice. The voice speed must be between 0.1 and 2.0. Note: this is only used when using a Telnyx voice	0.1 - 2.0	1

<Response>
     <AIGather action="/after_ai_gather">
    <Greeting></Greeting>
    <Parameters>
    <![CDATA[
    {
      "properties": {
        "age": {
          "description": "The age of the customer.",
          "type": "integer"
        },
        "location": {
          "description": "The location of the customer.",
          "type": "string"
        }
      },
      "required": [
        "age",
        "location"
      ],
      "type": "object"
    }
    ]]>
    </Parameters>
    <Voice name="Telnyx.NaturalHD.Astra" voice_speed="1.0"/>
    <MessageHistory>
      <Message role="user">Hello my name is Enzo.</Message>
    </MessageHistory>
    <InterruptionSettings enable="true"/>
    <Transcription model="some_model"/>
    <Assistant model="openai/gpt-4" api_key_ref="my_key_ref" instructions="You are a helpful assistant that can help the customer with their questions.">
      <Tools>
        <Tool>
          <![CDATA[
          {
            "type": "hangup",
            "hangup": {
              "description": "Hang up the call."
            }
          }
          ]]>
        </Tool>
        <Tool>
          <![CDATA[
          {
            "type": "transfer",
            "transfer": [
              {
                "name": "support",
                "to": "+1234567890"
              }
            ]
          }
          ]]>
        </Tool>
      </Tools>
    </Assistant>
  </AIGather>
</Response>

If action is set, the following callbacks are expected:

action

{
    "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
    "CallSid": "v2:DPNqxVjTNtQYaKdcKbU0QgRFrQ3YzuAQrVYC4Ggcuq7zTpDkUB7A4w",
    "CallSidLegacy": "v2:DPNqxVjTNtQYaKdcKbU0QgRFrQ3YzuAQrVYC4Ggcuq7zTpDkUB7A4w",
    "From": "Defaultj35z6@sip.telnyx.com",
    "To": "+12132045020",
    "Result": {
        "age": 29,
        "location": "Paris"
    },
    "MessageHistory": [
        {
            "role": "assistant",
            "text": "Hello, what's your name?"
        },
        {
            "role": "user",
            "text": "Hi, I'm Enzo."
        },
        {
            "role": "assistant",
            "text": "Hello, please provide your age and location."
        },
        {
            "role": "user",
            "text": "Hi, I'm 29 and I live in Paris."
        }
    ]
}

If statusCallbackEvent is set, the following webhooks are expected:

ATTRIBUTE	DESCRIPTION
AccountSid	A unique identifier for the account generating this call.
CallSid	A unique identifier for this call, generated by Telnyx.
From	The outbound caller number.
To	The inbound callee number.
Result	The result of the AI gather, its type depends on the parameters provided in the command.
MessageHistory	The history of the messages exchanged during the AI gather. It also includes any messages passed in the MessageHistory of the AIGather verb.