Overview

TeXML is an XML-based data structure used by Telnyx to build quick applications to be associated with your Telnyx phone numbers. When a call comes into one of your Telnyx Numbers, Telnyx makes an HTTP request to the URL endpoint you configured for that number. The endpoint will contain instructions telling Telnyx what to do next with the call.

Responses to the HTTP request are in an XML format that we call TeXML. TeXML allows you to specify instructions in your file using simple commands called verbs. TeXML Translator starts at the top of your TeXML file and executes your TeXML commands sequentially in the order they are arranged in the file.

| Overview | Dial | Conference | Enqueue | Gather | Leave | Hangup | Pause | Play | Record | Redirect |Reject | Say | Siprec | Stream | Suppression| Transcription |

---

Check out our TeXML Setup Guide to get started on a simple TeXML text-to-speech application.

When a call is received by one of your Telnyx phone numbers, Telnyx looks up the URL endpoint you configured for that number and makes an HTTP request to it. The URL endpoint then responds to the request with a TeXML file that instructs what to do next in the call. TeXML files have a standard .xml file extension.

Telnyx will read the instructions in the TeXML file, from top to bottom, and execute all the verbs/commands in order.

Outbound calls started via the TeXML Translator work the same way. When you start an outbound call, you also pass a link to a TeXML file. Telnyx will make a request to this file to determine how it should proceed with the call.

While a single TeXML document is executed at a time, many documents can be linked together and generated dynamically to create complex applications to fit any need.

TeXML Translator is XML-based and consists of the following elements:

• <Response> element -- tag defining the body of the TeXML document
• verb -- an XML tag denoting the action that you want Telnyx to take
• noun -- the item for the action specified in the associated verb

Here is a simple TeXML file containing an example of a verb and noun used together:

<?xml version="1.0" encoding="UTF-8"?>

<!-- TeXML files must contain the Response element -->
<Response>
 <!-- Say and Dial are Verbs -->
    <Say>Thank you for calling Telnyx. Please hold.</Say>
    <Dial>
   <!-- Number is a Dial Noun -->
        <Number>+13129457420</Number>
    </Dial>
</Response>

When creating a TeXML set of instructions you can make use of Mustache Templates to generate instructions dynamically at runtime.

You can make use of Mustache Dynamic templating to insert content into your TeXML instructions through HTTP request parameters in the webhook URL we use to fetch your TeXML set of instructions. For example, you could create a TeXML set of instructions that calls a number that is set until the HTTP request is made to fetch your TeXML instructions.

You first create your TeXML instructions using Mustache Templating and set the {{PhoneNumber}} as a variable like this

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Number>{{PhoneNumber}}</Number>
  </Dial>
</Response>

The phone number can now be replaced at runtime by setting your TeXML webhook URL to have PhoneNumber as a parameter.

curl -X POST https://api.telnyx.com/v2/texml/calls/{connection_id} \
--data-urlencode "To=+13121230000" \
--data-urlencode "From=+13120001234" \
--data-urlencode "Url=https://www.example.com/texml.xml?PhoneNumber=+18771234567" \
--data-urlencode "StatusCallback=https://www.example.com/statuscallback-listener" \
--header "Authorization: Bearer APIAuthKey_fromPortal"

The request parameters set by Telnyx, i.e. CallSid, From, and To are also available for the Mustache Template. The list of the parameters for each of the callbacks can be found on our developer documentation page.

You can set arrays as parameters in your TeXML webhook URL and let Mustache Template handle them. If for example, you want the dial command to have two numbers you could add a Numbers list parameter to your callback Url.

curl -X POST https://api.telnyx.com/v2/texml/calls/{connection_id} \
--data-urlencode "To=+13121230000" \
--data-urlencode "From=+13120001234" \
--data-urlencode "Url=https://www.example.com/texml.xml?PhoneNumbers[]=+18771234567&PhoneNumbers[]=+18771234568" \
--data-urlencode "StatusCallback=https://www.example.com/statuscallback-listener" \
--header "Authorization: Bearer APIAuthKey_fromPortal"

Then you can handle the PhoneNumbers parameter in the TeXML instructions using the following syntax.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
  {{#PhoneNumbers}}
    <Number>{{.}}</Number>
  {{/PhoneNumbers}}
  </Dial>
</Response>

This will end up being parsed as

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Number>+18771234567</Number>
    <Number>+18771234568</Number>
  </Dial>
</Response>

Conditional content is supported by using if/else statements in the TeXML instructions. You could define a set of instructions to dial a specific number depending on From parameter present in the HTTP request.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
{{#if From == +18771234567}}
  <Dial>
    <Number>+18771234568</Number>
  </Dial>
{{#elseif From == +18771234568}}
  <Dial>
    <Number>+18771234567</Number>
  </Dial>
{{#else}}
  <Say>No valid number is present</Say>
{{/if}}
</Response>

Supported operators are ==, != and no operator for checking if the parameter value is not null.

The baseline of TeXML files is the <Response> tag.

All verbs in a TeXML file must be placed within a single-parent <Response> element and each file can only have a single one.

A verb identifies the action to take.

When using Verbs one instruction must completed before the next one is executed. Verbs may have optional TeXML attributes that override the flow of execution, allowing you to customize the verb behavior.

All verbs are case-sensitive, so <Dial> and <dial> are not interchangeable.

The following verbs cause the specified action to take place during the call:

VERB	ACTION
<Dial>	Initiates a call to a phone or SIP number
<Gather>	Collects DTMF input from the caller or called party
<AIGather>	Collects information from the caller or called party leveraging AI
<Hangup>	Disconnects the call
<Pause>	Waits silently for a specified number of seconds
<Play>	Plays an MP3 or WAV audio file
<Record>	Records and saves the audio in the call
<Redirect>	Transfers control of the call to another TeXML application
<Refer>	SIP refers (transfers) the call towards SIP infrastructure
<Reject>	Rejects the call
<Say>	Executes a Text-to-Speech instruction

A noun is what the verb uses to complete an action and is placed inside a verb element. A noun can be the text that is read in a call or other TeXML elements that represent the action, such as a Number to dial or a SIP URI to transfer the call to.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
 <Dial>
      <Sip>sip:agent1@contactcenter.com</Sip>
 </Dial>
</Response>

Each verb has its own set of nouns. See the documentation for a specific verb for more details.

---

Each time Telnyx makes a request to your application to fetch new TeXML, additional parameters with information about the call will be sent with the request to your URL.

PARAMETER	DESCRIPTION
CallSid	A unique identifier for this call, generated by Telnyx.
From	The phone number of the party that initiated the call. Phone numbers are formatted with a '+' and country code, e.g. +16175551212 E.164 format.
To	The phone number of the called party. Phone numbers are formatted with a '+' and country code, e.g. +16175551212 E.164 format.

---

All dates and times in requests to and from TeXML files follow Telnyx API conventions: UTC, and in RFC 2822 format.

All numbers in requests to or from TeXML files follow Telnyx API conventions: E.164 format. Numbers in this format start with a plus sign ("+") and the country code.

SIP URIs follow Telnyx SIP Trunking and SIP Credentials conventions: sip:telnyxagent@sip.telnyx.com

The <Dial> verb transfers an existing call to another destination. <Dial> will end this new call if: the called party does not answer, the number does not exist, or Telnyx receives a busy signal.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
action	Optional URL where TeXML will make a request when the <Dial> call ends to retrieve a new set of TeXML instructions to continue the call flow.
method	HTTP request type used to retrieve the next set of instructions.	GET, POST	POST
callerId	Caller ID that must be a valid E.164 format number.
fromDisplayName	The fromDisplayName string to be used as the caller id name (SIP From Display Name) presented to the destination. The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If omitted, the display name will be the same as the number in the callerId field.
hangupOnStar	The hangupOnStar attribute lets the initial caller hang up on the called party by pressing the '*' key on their phone. Does not apply for the Conference noun.	true, false	false
record	The record attribute lets you record both legs of a call within the associated <Dial> verb. It works with the <Number> and <Sip> nouns only. If you want to record the conference, please use the record attribute on <Conference> noun. Recordings are available in two options: mono-channel or dual-channel.	do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual	do-not-record
recordMaxLength	Defines the maximum length for the recording in seconds.	0-14400, 0 for infinite	0
recordingStatusCallback	Optional URL that tells Telnyx where to make its GET or POST request when the recording is available.
recordingStatusCallbackMethod	HTTP request type used for recordingStatusCallback.	GET, POST	POST
recordingStatusCallbackEvent	The recording events for which Telnyx should send a webhook. Multiple events are separated by a space.	in-progress, completed, absent	completed
recordingTimeout	The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected. The timer only starts when the speech is detected. Please note that the transcription is used to detect silence and the related charge will be applied.	Any integer greater than 0. 0 for infinite	0
timeLimit	Sets the maximum duration in seconds of the call created by <Dial>.	60 - 14,400	14,400 (4 hours)
timeout	Sets the maximum time in seconds that Telnyx will wait for the dialed party to answer.	5 - 120	30
ringTone	The ringback tone played back to the caller.	at,au,bg,br,be,ch,cl,cn,cz,de,dk,ee,es,fi,fr,gr,hu,il,in,it,lt,jp,mx,my,nl,no,nz,ph,pl,pt,ru,se,sg,th,uk,us,us-old,tw,ve,za	us

NOUN	DESCRIPTION	OPTIONAL ATTRIBUTES
<Number>	E.164 phone number.	method, sendDigits, statusCallback, statusCallbackEvent, statusCallbackMethod
<Sip>	SIP URI.	method, password, statusCallback, statusCallbackEvent, statusCallbackMethod, url, username
<Queue>	queue name	method, url

Send custom headers by appending them to the SIP URI -- just as you'd pass headers in a URI over HTTP. For example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>
            sip:jack@example.com?x-mycustomheader=foo&x-myotherheader=bar
        </Sip>
    </Dial>
</Response>

<Number> and <Sip> Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
statusCallback	A URL for Telnyx to send webhook requests to on each event specified in the statusCallbackEvent attribute for outbound calls only. Inbound Status Callback events can be configured for TeXML the connection settings in the Mission Control Portal.
statusCallbackEvent	The call events for which Telnyx should send a webhook. Multiple events are separated by a space.	initiated, ringing, answered, amd, dtmf, completed	completed
statusCallbackMethod	HTTP request type Telnyx should use when requesting the statusCallback URL.	GET, POST	POST
url	Optional URL to another TeXML document that can contain <Gather> and <Hangup> verbs so that the called party can chose to take an action on the incoming call before the two parties are connected. The callee will continue to hear ringback while the url document is executed.
method	HTTP request type used for url.	GET, POST	POST
machineDetection	Enables Answering Machine Detection. Note: add amd event type to statusCallbackEvent list to receive the detection result webhook.	Enable, Disable, DetectMessageEnd	Disable
detectionMode	Sets the Answering Detection mode.	Regular, Premium	Regular
machineDetectionTimeout	Maximum timeout threshold for overall detection, in milliseconds.	500 - 60000

<Number> Only Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
sendDigits	Digits (DTMF tones) to be automatically applied when the call is answered. Use w for 0.5s of silence.	Any digits

<Sip> Only Attributes

ATTRIBUTE	DESCRIPTION
username	Username for SIP authentication	none
password	Password for SIP authentication	none

<Queue> Attributes

ATTRIBUTE	DESCRIPTION
method	HTTP request type used for url.	GET, POST	POST
url	Optional URL to another TeXML document that can contain <Play>, <Say>, <Gather>, <Pause> and <Redirect> verbs. Document will be executed on the queued call before bridging the calls.

You can use multiple <Number> and <Sip> nouns within a <Dial> verb to dial multiple phone numbers and SIP addresses at the same time. The first person to answer the call will be connected to the caller, while the rest of the call attempts are hung up:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Number>+18775551212</Number>
    <Sip>sip:connection@sip.telnyx.com</Sip>
    <Number>+18771234567</Number>
  </Dial>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial action="/nextinstructions.php" callerId="+13120001234">+19999999999</Dial>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial action="/nextinstructions.php" callerId="+13120001234">
      <Number statusCallback="https://foo.com/my_call_stats" statusCallbackEvent="initiated ringing answered completed">+19999999999</Number>
    </Dial>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial action="/nextinstructions.php" callerId="+13120001234" hangupOnStar="true">
      <Sip statusCallback="https://foo.com/my_sip_call_stats" statusCallbackEvent="initiated">sip:connection@sip.telnyx.com</Sip>
    </Dial>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial action="/nextinstructions.php" callerId="+13120001234">
      <Number statusCallback="https://foo.com/my_call_stats" statusCallbackEvent="initiated ringing answered completed amd" machineDetection="Enable" detectionMode="Regular">+19999999999</Number>
    </Dial>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
      <Queue url="/before_bridge_action">TestQueue</Queue>
    </Dial>
</Response>

If action is set the following callback can be expected. when the call is completed. The new set of instructions can be sent as a response to it. The error code and error message field are provided only in case of failed calls. The full list of errors can be found under the link

{
  "AccountSid" : "19a75cea-02c6-4b9a-84fa-c9bc8341feb8",
  "AnsweredTime" : "2023-09-06T09:05:14.860713Z",
  "CallLegId" : "7d87c352-4c94-11ee-99f7-02420a0daa69",
  "CallSessionId" : "7bf6178c-4c94-11ee-b679-02420aef02a0",
  "CallSid" : "v3:viLNGyAMjOw6H0AAmA3_CL4rbzYWgahKGqeoZ0Eu_TUYPeWs5w3z6w",
  "CallSidLegacy" : "v3:viLNGyAMjOw6H0AAmA3_CL4rbzYWgahKGqeoZ0Eu_TUYPeWs5w3z6w",
  "ConnectionId" : "2034058542482196149",
  "DataLocality" : "USA",
  "DialCallDuration" : "11",
  "DialCallSid" : "v3:t7KEildpy-HskSZeY78-WjFFcJMAaopsPfnkaH2J3NcByeTzgfVS1A",
  "DialCallSidLegacy" : "v3:t7KEildpy-HskSZeY78-WjFFcJMAaopsPfnkaH2J3NcByeTzgfVS1A",
  "DialCallStatus" : "completed | busy | no-answer | failed",
  "EndTime" : "2023-09-06T09:05:26.720715Z",
  "ErrorCode": "10010"
  "ErrorMessage": "Destination Number is invalid D11"
  "From" : "+13122010094",
  "OccurredAt" : "2023-09-06T09:05:26.720715Z",
  "OrganizationId" : "19a75cea-02c6-4b9a-84fa-c9bc8341feb8",
  "StartTime" : "2023-09-06T09:05:14.080710Z",
  "To" : "+12029925624",
  "UserId" : "19a75cea-02c6-4b9a-84fa-c9bc8341feb8",
}

If statusCallbackEvent are set you can expect the following webhooks.

initiated

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallStatus": "initiated",
   "CallbackSource": "call-progress-events",
   "From": "+18445931290",
   "ParentCallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "ParentCallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "SequenceNumber": "0",
   "Timestamp": "2021-04-28 21:51:13.591099Z",
   "To": "+13122010055"
}

ringing

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallStatus": "ringing",
   "CallbackSource": "call-progress-events",
   "From": "+18445931290",
   "ParentCallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "ParentCallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "SequenceNumber": "1",
   "Timestamp": "2021-04-28 21:51:13.591107Z",
   "To": "+13122010055"
}

in-progress

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallStatus": "in-progress",
   "CallbackSource": "call-progress-events",
   "From": "+18445931290",
   "ParentCallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "ParentCallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "SequenceNumber": "2",
   "Timestamp": "2021-04-28 21:51:15.532975Z",
   "To": "+13122010055"
}

completed

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallDuration": "2",
   "CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallStatus": "completed",
   "CallbackSource": "call-progress-events",
   "From": "+18445931290",
   "HangupSource": "",
   "ParentCallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "ParentCallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "RecordingDuration": "5",
   "RecordingUrl": "https://recording.com/your-recording-url",
   "SequenceNumber": "3",
   "Timestamp": "2021-04-28 21:51:18.731479Z",
   "To": "+13122010055"
}

failed

{
    "AccountSid": "6106a32e-75c8-4c72-9d56-26d2e34ddf46",
    "CallSid": "",
    "CallSidLegacy": "",
    "CallStatus": "failed",
    "CallbackSource": "call-progress-events",
    "ConnectionId": "1776656324537354013",
    "ErrorCode": "10010",
    "ErrorMessage": "Destination Number is invalid D11",
    "ParentCallSid": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
    "ParentCallSidLegacy": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
    "SequenceNumber": "0",
    "Timestamp": "2024-10-25 09:50:56.718456Z",
    "To": "+111"
}

busy

{
    "AccountSid": "6106a32e-75c8-4c72-9d56-26d2e34ddf46",
    "CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
    "CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
    "CallStatus": "busy",
    "CallbackSource": "call-progress-events",
    "ConnectionId": "1776656324537354013",
    "ParentCallSid": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
    "ParentCallSidLegacy": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
    "SequenceNumber": "0",
    "Timestamp": "2024-10-25 09:50:56.718456Z",
    "To": "+13122010055"
}

no-answer

{
    "AccountSid": "6106a32e-75c8-4c72-9d56-26d2e34ddf46",
    "CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
    "CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
    "CallStatus": "no-answer",
    "CallbackSource": "call-progress-events",
    "ConnectionId": "1776656324537354013",
    "ParentCallSid": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
    "ParentCallSidLegacy": "v3:0QBt0RFkWk-73gGoCwhrIWq934SqGZ186VBzKRiCM0MVzcDYEeTKZA",
    "SequenceNumber": "0",
    "Timestamp": "2024-10-25 09:50:56.718456Z",
    "To": "+13122010055"
}

amd

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "AnsweredBy": "machine_start|human|fax|machine_end_beep|machine_end_other|unknown",
   "CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "MachineDetectionDuration": "23357"
}

If recordingStatusCallbackEvent are set you can expect the following webhooks.

in-progress

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "CallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "From": "Defaultj35z6@sip.telnyx.com",
   "RecordingChannels": "1",
   "RecordingSource": "DialVerb",
   "RecordingStatus": "in-progress",
   "To": "+12132045020"
}

completed

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "CallSidLegacy": "v2:qiaymU9Ij90xJRRkYGWHOIx_41EVJPrzlny2zC67hwL1wVIUnnMrqQ",
   "From": "Defaultj35z6@sip.telnyx.com",
   "RecordingChannels": "1",
   "RecordingDuration": "5",
   "RecordingSid": "35094891-3290-4142-b2c2-b2eda57534cf",
   "RecordingSource": "DialVerb",
   "RecordingStatus": "completed",
   "RecordingUrl": "https://recording.com/your-recording-url",
   "To": "+12132045020"
}

The attributes contained in the statusCallback request to your URL.

ATTRIBUTE	DESCRIPTION
AccountSid	A unique identifier for the account generating this call.
CallSid	A unique identifier for this call, generated by Telnyx.
ParentCallSid	A unique identifier for the parent call.
CallStatus	A descriptive status for the call. The value is one of initiated, ringing, in-progress, completed, no-answer, busy, failed or canceled.
Timestamp	The timestamp when the event was fired, given as UTC in RFC 2822 format.
CallbackSource	A string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always call-progress-events.
From	The outbound caller number.
To	The inbound callee number.
RecordingDuration	Recording duration in seconds.
RecordingUrl	Url where the recording can be downloaded from.
RecordingSid	A unique identifier for the recording, generated by Telnyx.
RecordingChannels	1 for mono-channel, 2 for dual-channel
RecordingStatus	The status for the recording. The value is one of in-progress, completed or absent.
SequenceNumber	A sequence number ordering the multiple callbacks received. The first callback has the lowest, the last callback the highest.

The <Dial> verb's <Conference> noun allows you to connect to a conference room. Much like how the <Number> noun allows you to connect to another phone number, the <Conference> noun allows you to connect to a named conference room and talk with the other callers who have also connected to that room. Conference is commonly used as a container for calls when implementing hold, transfer, and barge. If the specified conference name does not exist, a new conference will be created. More <Conference> attributes are coming soon.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
beep	Specify whether a notification beep is played to the conference when a participant joins or leaves the conference. The participant joining the conference will never hear a beep.	true, false, onEnter, onExit	true
muted	Specify whether a participant is muted or not.	true, false	false
startConferenceOnEnter	Start the conference when a participant joins. If this is false and the participant joins a conference that has not started, they are muted and hear background music until a participant joins where startConferenceOnEnter is true. This is useful for implementing moderated conferences.	true, false	true
endConferenceOnExit	If a participant has this attribute set to true, then when that participant leaves, the conference ends and all other participants drop out. This is useful for implementing moderated conferences that bridge two calls and allow either call leg to continue executing TexML if the other hangs up.	true, false	false
statusCallback	A URL for Telnyx to send webhook requests to on each event specified in the statusCallbackEvent attribute.
statusCallbackEvent	The conference events for which Telnyx should send a webhook on. Multiple events are separated by a space.	start, end, join, leave, speaker	None
statusCallbackMethod	HTTP request type Telnyx should use when requesting the statusCallback URL.	GET, POST	POST
record	The record attribute lets you record entire conference. When set to record-from-start, recording begins immediately after conference starts.	record-from-start, do-not-record	do-not-record
recordBeep	If enabled, a beep sound will be played at the start of a recording.	true, false	true
recordingStatusCallback	Optional URL that tells Telnyx where to make its GET or POST request when the recording is available.
recordingStatusCallbackEvent	The recording events for which Telnyx should send a webhook. Multiple events are separated by a space.	in-progress, completed, absent	completed
recordingStatusCallbackMethod	HTTP request type used for recordingStatusCallback.	GET, POST	POST
recordingTimeout	The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected. The timer only starts when the speech is detected. Please note that the transcription is used to detect silence and the related charge will be applied.	Any integer greater than 0. 0 for infinite	0
trim	Whether to trim any leading and trailing silence from the recording.	trim-silence, do-not-trim	trim-silence
waitUrl	A URL to an MP3 or WAV file that should be used for the conference's hold music before the conference starts. The URL can also return an XML document with instructions that will be executed while the call is waiting for the conference to start.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference>Room 1234</Conference>
  </Dial>
</Response>

If statusCallbackEvent are set you can expect the following webhooks.

join

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:r3Cj9j-Hx7NAZETtYpdgktVUYKhsc8D1mSmzY8_6r4HHZYViWIs6Fw",
   "CallSidLegacy": "v2:r3Cj9j-Hx7NAZETtYpdgktVUYKhsc8D1mSmzY8_6r4HHZYViWIs6Fw",
   "ConferenceSid": "58b4eda9-03de-4bee-9178-d0e10d83e519",
   "FriendlyName": "Room 1234",
   "From": "telephonyappssquad24104@sip.telnyx.com",
   "SequenceNumber": "1",
   "StatusCallbackEvent": "participant-join",
   "Timestamp": "2021-04-28 22:51:29.993535Z",
   "To": "+12132045020"
}

leave

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:r3Cj9j-Hx7NAZETtYpdgktVUYKhsc8D1mSmzY8_6r4HHZYViWIs6Fw",
   "CallSidLegacy": "v2:r3Cj9j-Hx7NAZETtYpdgktVUYKhsc8D1mSmzY8_6r4HHZYViWIs6Fw",
   "ConferenceSid": "58b4eda9-03de-4bee-9178-d0e10d83e519",
   "FriendlyName": "Room 1234",
   "From": "telephonyappssquad24104@sip.telnyx.com",
   "SequenceNumber": "3",
   "StatusCallbackEvent": "participant-leave",
   "Timestamp": "2021-04-28 22:51:47.114479Z",
   "To": "+12132045020"
}

end

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:0YXD2QVLtba0UDTe3k6H9gEsAEs4qRLsuy6u_zoS364PKR6DApuKuw",
   "CallSidLegacy": "v2:0YXD2QVLtba0UDTe3k6H9gEsAEs4qRLsuy6u_zoS364PKR6DApuKuw",
   "ConferenceSid": "58b4eda9-03de-4bee-9178-d0e10d83e519",
   "FriendlyName": "Room 1235",
   "From": "telephonyappssquad24104@sip.telnyx.com",
   "SequenceNumber": "4",
   "StatusCallbackEvent": "conference-end",
   "Timestamp": "2021-04-28 22:51:51.480853Z",
   "To": "+12132045020"
}

speaker

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:0YXD2QVLtba0UDTe3k6H9gEsAEs4qRLsuy6u_zoS364PKR6DApuKuw",
   "CallSidLegacy": "v2:0YXD2QVLtba0UDTe3k6H9gEsAEs4qRLsuy6u_zoS364PKR6DApuKuw",
   "ConferenceSid": "58b4eda9-03de-4bee-9178-d0e10d83e519",
   "FriendlyName": "Room 1235",
   "From": "telephonyappssquad24104@sip.telnyx.com",
   "SequenceNumber": "5",
   "StatusCallbackEvent": "participant-speech-start",
   "Timestamp": "2021-04-28 22:51:51.480853Z",
   "To": "+12132045020"
}

The attributes contained in the statusCallback request to your URL.

ATTRIBUTE	DESCRIPTION
AccountSid	A unique identifier for the account generating this call.
CallSid	A unique identifier for this call, generated by Telnyx.
ConferenceSid	A unique identifier for this conference, generated by Telnyx.
FriendlyName	Name given to the conference.
From	The outbound caller number.
Timestamp	The timestamp when the event was fired, given as UTC in RFC 2822 format.
To	The inbound callee number.
SequenceNumber	A sequence number ordering the multiple callbacks received. The first callback has the lowest, the last callback the highest.
StatusCallbackEvent	Event generating the callback.

The <Enqueue> verb enqueues the current call in a call queue.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
action	Defines an absolute or relative URL used to send a request when the call leaves the queue. It will be sent right away when the call is dequeued using <Leave> verb. When a call is dequeued using <Dial> verb, the request will be sent once the bridged calls disconnect.
method	HTTP request type used for action.	GET, POST	POST
maxWaitTimeSecs	Maximum time in seconds to wait in the queue.	1-14400	14400
waitUrl	Specifies the URL to the TeXML document that will be executed when the call is waiting in the queue. Once all the commands from the flow are executed, the waitUrl is re-requested, and the TeXML document is run once again. Verbs that are supported in the waitUrl TeXML document: <Play>, <Say>, <Gather>, <Pause>, <Hangup>, <Redirect>, <Leave>.
waitUrlMethod	HTTP request type used for waitUrl.	GET, POST	POST

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Enqueue waitUrl="/wait_in_queue">TestQueue</Enqueue>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Enqueue maxWaitTimeSecs="60" action="/dequeue_action">TestQueue</Enqueue>
</Response>

The <Gather> verb collects DTMF tones during a call. <Say> can be nested within <Gather> to create an interactive IVR with text-to-speech.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
action	URL where TeXML will send the gathered digits. The same method (GET/POST) as set for the TexML application is used. Transfers control of the current call to the TeXML file returned.
finishOnKey	The set of digits, (0-9, *, #), that indicates the end of the gather.
numDigits	The number of digits to be gathered.
minDigits	Minimum number of digits to be gathered.	1-128	1
maxDigits	Maximum number of digits to be gathered.	1-128	128
language	The language used.	See RESTful API documentation	en-US
timeout	Time in seconds between digits before the <Gather> digits are sent to your action URL. Telnyx will wait until all nested verbs have been executed before beginning the timeout period.	1-120	5
validDigits	The set of valid digits for the gather action.
invalidDigitsAction	URL where TeXML will send the invalid gathered digits. The same method (GET/POST) as set for the TeXML application is used. Transfers control of the current call to the TeXML file returned.		action

NOUN	DESCRIPTION
<Say>	Reads supplied text back to the caller.
<Play>	Plays an audio URL back to the caller.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather action="/processdtmf.php" finishOnKey="*" timeout="20">
        <Say>Please press 1 for sales, or 2 for support. Press * to exit the menu.</Say>
    </Gather>
   <Say>We did not receive any input. Goodbye!</Say>
</Response>

action

{
    "AccountSid":"cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
    "CallSid":"v2:DPNqxVjTNtQYaKdcKbU0QgRFrQ3YzuAQrVYC4Ggcuq7zTpDkUB7A4w",
    "CallSidLegacy":"v2:DPNqxVjTNtQYaKdcKbU0QgRFrQ3YzuAQrVYC4Ggcuq7zTpDkUB7A4w",
    "Digits":"1",
    "From":"Defaultj35z6@sip.telnyx.com",
    "To":"+12132045020"
}

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.
Digits	The digits entered in the gather process by the callee.

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>

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.

The <Leave> verb removes a call from the queue and continues with the next verb after the original <Enqueue>.

The <Leave> verb doesn't support any attributes.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Leave />
</Response>

The <Hangup> verb ends the current call. There are no attributes associated with <Hangup> and no nouns can be nested within it.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Support line is closed. Please try again tomorrow.</Say>
    <Hangup />
</Response>

completed

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallDuration": "2",
   "CallSid": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallSidLegacy": "v2:7V3r4VFCGLTzKLOveE0-7vM9dX17-NRQgU1byo-uuOIX9JcDadLLKw",
   "CallStatus": "completed",
   "CallbackSource": "call-progress-events",
   "From": "+18445931290",
   "HangupSource": "callee",
   "SequenceNumber": "0",
   "Timestamp": "2021-04-28 21:51:18.731479Z",
   "To": "+13122010055"
}

The attributes contained in the statusCallback request to your URL.

ATTRIBUTE	DESCRIPTION
AccountSid	A unique identifier for the account generating this call.
CallSid	A unique identifier for this call, generated by Telnyx.
CallStatus	A descriptive status for the call. The value is one of completed, no-answer, busy, failed or canceled.
Timestamp	The timestamp when the event was fired, given as UTC in RFC 2822 format.
CallbackSource	A string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always call-progress-events.
From	The outbound caller number.
To	The inbound callee number.
SequenceNumber	A sequence number ordering the multiple callbacks received. The first callback has the lowest, and the last callback the highest.
HangupSource	Source of the hangup. The value can be callee or caller

The <HttpRequest> verb sends a request to the external servers. It consists of 2 child nodes <Request> and <Response>

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
async	Defines if TeXML process should wait for the request response. When it is set to false, the callback will be sent to the action URL, when the request is processed	true	false
action	Defines the action url that will be used to send the callback when the request is processed (only if async is set to false)	http://example.com

The <Request> node defines all the attributes of the request. It can have 2 child nodes <Headers> and <Body>

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
url	Url to send the request.	http://example.com
method	Method for the request (GET or POST)	GET	GET

<Response>
    <HttpRequest async=”true”>
        <Request url="https://example.com" method="POST">
        <Headers>
            <Header>
                <Key>Authorization</Key>
                <Value>Bearer API_key</Value>
            </Header>
            <Header>
                <Key>Content-Type</Key>
                <Value>application/json</Value>
            </Header>
        </Headers>
        <Body>
        <![CDATA[
                {
                    "from":{{From}}
                }
                ]]>
        </Body>
        </Request>
    </HttpRequest>
</Response>

The <Response> node allows assigning required parts of the response to the variables that will be passed to the action url. It will be triggered only if the async is set to false.

<Response>
    <HttpRequest  async=”false” action="https://example.com">
        <Request url="https://example.com" method="POST">
        ...
        </Request>
        <Response>
            <Type>JSON</Type>
            <StatusCode>200</StatusCode>
            <Content>
                <Field>
                    <Name>contact.name.first</Name>
                    <Value>first_name</Value>
                </Field>
                <Field>
                    <Name>contact.name.last</Name>
                    <Value>last_name</Value>
                </Field>
            </Content>
        </Response>
    </HttpRequest>
</Response>

The <Pause> verb waits silently for a specified number of seconds or one second by default. No nouns can be nested within <Pause> and a self-closing tag must be used.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
length	Optional length of time in seconds to wait.	1-180	1

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pause length="5"/>
</Response>

The <Play> verb plays an MP3 or WAV audio file, that Telnyx fetches from the URL you configure, back to the caller.

Alternatively, specify mediaStorage="true" to fetch a file you previously uploaded to Telnyx using media storage APIs. When mediaStorage="true" is used the verb expects a media_name instead of a URL.

<Play> can be used independently as a verb or nested within <Gather> as a noun to play an audio file while waiting for DTMF tones.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
loop	The number of times between 1-100 to repeat the audio file.	1-100. 0 for infinite.	1
mediaStorage	When true fetches the file from Telnyx media storage using the provided media name.	true, false	false

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Gather action="/processdtmf.php">
    <Play loop="10">http://www.example.com/sounds/greeting.wav</Play>
  </Gather>
</Response>

The <Record> verb creates an audio file with the call audio. If a recordingStatusCallback, Telnyx will deliver the URL for the recording to that address once the call has ended. Recording URLs are valid for 10 minutes after the call has ended. All recordings are also available via the Telnyx Mission Control Portal>

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
action	Optional URL where TeXML will make a request when the <Record> ends to retrieve a new set of TeXML instructions to continue the call flow sent with additional request parameters.
method	HTTP request type used to retrieve the next set of instructions.	GET, POST	POST
finishOnKey	Set of digits specified together, any one of which will end the recording.	Any digit, #, *	1234567890*#
playBeep	Whether or not a sound is played before the start of a recording.	true, false	true
maxLength	Defines the maximum length for the recording in seconds.	0-14400, 0 for infinite	0
channels	When using dual channels, the final audio file will be stereo recorded with the first leg on channel A, and the rest on channel B.	dual, mono	dual
recordingStatusCallback	Optional URL that tells Telnyx where to make its GET or POST request when the recording is available.
recordingStatusCallbackMethod	HTTP request type used for recordingStatusCallback.	GET, POST	POST
timeout	The number of seconds that Telnyx will wait for the recording to be stopped if silence is detected. The timer only starts when the speech is detected. Please note that the transcription is used to detect silence and the related charge will be applied.	Any integer greater than 0. 0 for infinite	0
trim	Will remove silence from the beginning and end of the recording when set to trim-silence.	trim-silence

recordingStatusCallback will be used to deliver the final URL and information on the call recording. If available TeXML will also send recording information along with the request to the action URL with the following parameters:

ATTRIBUTE	DESCRIPTION
RecordingURL	The URL of the recorded audio. The recording file may not yet be accessible when the action callback is sent. Use recordingStatusCallback for reliable notification on when the recording is available for access.
RecordingDuration	The duration of the recorded audio (in seconds). To get a final accurate recording duration after any trimming of silence, use recordingStatusCallback.
Digits	The key (if any) pressed to end the recording or hangup if the caller hung up.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Record action="/recordingfinish.php" recordingStatusCallback="https://wwww.foo.com/recording-storage/" playBeep="true" finishOnKey="*9"/>
    <Say>
        You reached Telnyx Sales voicemail.
        Please leave a message after the beep.
        Press the pound key when finished.
    </Say>
</Response>

The <Redirect> verb transfers control of the current call to another TeXML application. This is useful to create a tree structure of TeXML files for different applications. No nouns can be nested within <Redirect>.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
method	The type of requested used <Redirect> URL.	GET, POST	POST

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Redirect>http://www.example.com/TeXML/redirect.xml</Redirect>
</Response>

The <Refer> verb in Telnyx allows you to transfer a phone call to another SIP infrastructure during a TeXML call. You can initiate it at any point during the call. When you use the <Refer> verb, Telnyx will replace the original call with a new call to the external system you specify, effectively transferring the call to that system.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
action	Optional URL where TeXML will make a request when the <Refer> verb ends, to retrieve a new set of TeXML instructions to continue the call flow.
method	HTTP request type used to retrieve the next set of instructions.	GET, POST	POST

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Refer>
        <Sip>sip:john@example.com</Sip>
    </Refer>
</Response>

If action is set you can expect the following webhook when the <Refer> verb finishes. A new set of TeXML instructions should be returned in response.

{
  "AccountSid": "6d547b4f-993a-4e87-b95c-2d9460b3824b",
  "CallSid": "v3:wf0h6MLq0PIHItrkFyEPM0WLPAarG_fUA2MLQqkLYRhRRrCqnT6TPg",
  "CallSidLegacy": "v3:wf0h6MLq0PIHItrkFyEPM0WLPAarG_fUA2MLQqkLYRhRRrCqnT6TPg",
  "ReferCallStatus": "in-progress",
  "ReferSipResponseCode": "202",
  "NotifySipResponseCode": "200",
  "Timestamp": "2021-04-28 21:51:13.591099Z"
}

The attributes contained in the action request to your URL.

ATTRIBUTE	DESCRIPTION
AccountSid	A unique identifier for the account generating this call.
CallSid	A unique identifier for this call, generated by Telnyx.
ReferCallStatus	Provides new call status based on SIP NOTIFY messages. May be omitted if REFER fails or no NOTIFY requests are received. Possible values: in-progress, no-answer, busy, canceled, failed
ReferSipResponseCode	This indicates the SIP response code that Telnyx receives from the SIP endpoint in response to the REFER request.
NotifySipResponseCode	Reflects final SIP response code on the referred leg, based on NOTIFY messages. May be omitted if REFER fails or no NOTIFY requests are received.
Timestamp	The timestamp when the event was fired, given as UTC in RFC 2822 format.

The <Reject> verb rejects a call to your Telnyx number. It is effectively an exit statement from the current document, as there is no way to return to any instructions listed after the <Reject> verb. If placed as the very first verb in an incoming call, <Reject> will prevent the call from being answered and will incur no cost. If placed elsewhere in the call, the call will hang up but will be charged up to that point.

You can't nest any verbs within <Reject> and you can't nest <Reject> in any other verbs.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
reason	The tone to play to indicate the reason the call was rejected.	rejected, busy	rejected

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Reject />
</Response>

The <Say> verb speaks the text specified back to the caller enabling text-to-speech for any application.

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
voice	Optional text-to-speech voice type. For premium text-to-speech use alice or prescribe a specific Amazon Polly voice in the form of Polly.*. If you want to use neural voice, use the following format: Polly.*-Neural. The ElevenLabs integration requires providing an API key that can stored in the secrets storage integration secrets documentation for more details. The voice can be specified in the following way: ElevanLabs.modelId.VoiceId. For basic text-to-speech use man or woman. Only en-US language is supported in that case.	man, woman, alice, Polly.*	man
api_key_ref	Identifier of ElevenLabs API key stored in the secrets storage	api_key_name
language	ISO language type to be used if voice type alice is selected. If man or woman is selected, the language accent will always be en-US. This parameter is ignored when a specific Amazon Polly voice is used.	See RESTful API documentation	en-US
loop	The number of times to repeat the speech.	1-100. 0 for infinite.	1

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say voice="alice">This is a premium Amazon Polly text-to-speech message!</Say>
</Response>

The <Siprec> instruction starts siprec session on given call.

<Siprec> Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
connectorName	Specifiec which pre-configured external connector shall be used for this request.		Default
statusCallback	A URL for Telnyx to send webhook requests to on each event related to siprec session.	Default
statusCallbackMethod	HTTP request type used for StatusCallback.	GET, POST	POST
track	Specifies which track should be forwarded to SRS.	inbound_track, outbound_track, both_tracks	both_tracks
includeMetadataCustomHeaders	Controls whether custom parameters are added as metadata, if false they are added to sip headers.	true, false	false
secure	Controls whether to encrypt media sent to your SRS using SRTP and TLS. When set you need to configure SRS port in your connector to 5061.	true, false	false
sessionTimeoutSecs	Sets Session-Expires header to the INVITE. A reinvite is sent every half the value set. Usefull for session keep alive. Minimum value is 90, set to 0 to disable.	0, >= 90	1800 (30 minutes)

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Start>
    <Siprec track="both_tracks" connectorName="my-connector" statusCallback="https://example.com/siprec_callback" />
  </Start>
</Response>

The <Stream> instruction starts streaming the media from a call to a specific WebSocket address in near-realtime. Audio will be delivered as base64-encoded RTP payloads (no headers), wrapped in JSON payloads. When used with <Start> verb it starts an asynchronous stream to your websocket destination URL. For synchronous bi-directional stream please use <Connect> verb.

<Stream> Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
url	The destination WebSocket address where the stream is going to be delivered.
track	Specifies which track should be streamed.	inbound_track, outbound_track, both_tracks	inbound_track
name	Specifies custom name for the stream instance
bidirectionalMode	Bidirectional streaming mode	mp3, rtp	mp3
bidirectionalCodec	Bidirectional streaming codec, used only with bidirectionalMode=rtp	PCMU, PCMA, G722	PCMU

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Start>
    <Stream url="wss://yourdomain.com/stream" track=”both_tracks” />
  </Start>
</Response>

The <Suppression> instruction starts noise suppression on the call to improve audio quality.

<Suppression> Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
direction	Specifies which side of the audio shall be denoised.	inbound, outbound, both	inbound

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Start>
    <Suppression direction="both" />
  </Start>
</Response>

The <Transcription> instruction starts real-time transcription on the call.

<Transcription> Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
interimResults	Whether to send also interim results. If set to false, only final results will be sent. Applies to transcriptionEngine A only.	true, false	false
language	Language to use for speech recognition.	de, en, es, fr, it, pl	en
transcriptionEngine	Engine to use for speech recognition.	A - google, B - telnyx	A
transcriptionTracks	Indicates which leg of the call will be transcribed. Use inbound for the leg that requested the transcription, outbound for the other leg, and both for both legs of the call.	inbound, outbound, both	inbound
transcriptionCallback	URL that tells Telnyx where to make its GET or POST requests with transcription data.
transcriptionCallbackMethod	HTTP request type used for transcriptionCallback	GET, POST	POST

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Start>
    <Transcription language="en" interimResults="true" transcriptionCallback="/transcription" />
  </Start>
</Response>

The <Stop> verb stops specified by noun instruction on a call.

NOUN	DESCRIPTION
<Stream>	Stops current media stream, no attributes need to be provided
<Transcription>	Stops current transcription, no attributes need to be provided
<Suppression>	Stops current suppression, no attributes need to be provided

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Stop>
    <Stream />
  </Stop>
</Response>