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 result and message history. Same method (GET/POST) as set for the TexML application is used. Transfers control of the current call to the TeXML file returned.

Child Node	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 The same described as a JSON Schema object that needs to be gathered by the voice assistant. It needs to be provided within CDATA tags.
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..

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.LibriTTS.0
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		1

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. Such as:

<Parameters>need
    <![CDATA[
        {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The location of the user"
                },
                "age": {
                    "type": "number",
                    "description": "The age of the user"
                }
            },
            "required": ["location", "age"]
        }
    ]]>
</Parameters>

This must 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. Such as:

<MessageHistory>
    <Message role="user">Hello</Message>
    <Message role="assistant">Hi, how can I help you?</Message>
</MessageHistory>

<Response>
    <AIGather action="https://example.com/aigather">
        <Greeting>Hello, please provide your age and location.</Greeting>
        <Voice name="Polly.Joanna"/>
        <Parameters>
            <![CDATA[
                {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The location of the user"
                        },
                        "age": {
                            "type": "number",
                            "description": "The age of the user"
                        }
                    },
                    "required": ["location", "age"]
                }
            ]]>
        </Parameters>
        <MessageHistory>
            <Message role="assistant">Hello, what's your name?</Message>
            <Message role="user">Hi, I'm Enzo.</Message>
        </MessageHistory>
    </AIGather>
</Response>

<Response>
    <AIGather action="https://example.com/aigather">
        <Greeting>Hello, please provide your age and location.</Greeting>
        <Voice name="Polly.Joanna"/>
        <Parameters>
            <![CDATA[
                {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The location of the user"
                        },
                        "age": {
                            "type": "number",
                            "description": "The age of the user"
                        }
                    },
                    "required": ["location", "age"]
                }
            ]]>
        </Parameters>
        <MessageHistory>
            <Message role="assistant">Hello, what's your name?</Message>
            <Message role="user">Hi, I'm Enzo.</Message>
        </MessageHistory>
    </AIGather>
</Response>

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

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.