TeXML Translator

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.

How TeXML Translator works

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 lookup the URL endpoint you configured for that number and make 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 Syntax

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>

Response

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.

Verbs

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 customize the verb behavior.

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

Voice Verbs

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

VERB	ACTION
`<Conference>`	Connects to a conference room
`<Dial>`	Initiates a call to a phone number or SIP address or queue
`<Enqueue>`	Enqueues the current call in a call queue
`<Gather>`	Collects DTMF input from the caller or called party
`<Hangup>`	Disconnects the call
`<Leave>`	Exits the queue
`<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
`<Reject>`	Rejects the call
`<Say>`	Executes a Text-to-Speech instruction

Nouns

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 Number to dial or a SIP URI to transfer the call to.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
 <Dial>
      <Sip>sip:[email protected]</Sip>
 </Dial>
</Response>

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

Additional Request Parameters

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

Data Formats

Dates and Times

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

Phone Numbers

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:[email protected]

Dial

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.

Verb Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
`action`	Optional URL where TeXML will make a request to 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 ommited, 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. 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 a webhook on. Multiple events are separated by a space.	`in-progress`, `completed`, `absent`	`completed`
`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`

Nouns

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:[email protected]?x-mycustomheader=foo&amp;x-myotherheader=bar
        </Sip>
    </Dial>
</Response>

Noun Attributes

<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 a webhook on. Multiple events are separated by a space.	`initiated`, `ringing`, `answered`, `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`

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

Simultaneous Dialing

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:[email protected]</Sip>
    <Number>+18771234567</Number>
  </Dial>
</Response>

Examples

<?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:[email protected]</Sip>
    </Dial>
</Response>

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

Expected Callbacks

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

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": "[email protected]",
   "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": "[email protected]",
   "RecordingChannels": "1",
   "RecordingDuration": "5",
   "RecordingSid": "35094891-3290-4142-b2c2-b2eda57534cf",
   "RecordingSource": "DialVerb",
   "RecordingStatus": "completed",
   "RecordingUrl": "https://recording.com/your-recording-url",
   "To": "+12132045020"
}

Status Callback HTTP Attributes

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`, `busy` 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 staus for the recording. The value is one of `in-progress`, `completed` or `absent`.
`SequenceNumber`	A sequence number ordering the multiple callbacks received. First callback has the lowest, last callback the highest.

Initiate a TeXML Call using the Telnyx API

It is possible to initiate a TeXML call using a Telnyx API endpoint. Simply specify the connection_id (application_id) for the connection you want to use for the call. Telnyx will request TeXML from the XML Request URL configured for that connection in the Telnyx Mission Control Portal.

PARAMETER	DESCRIPTION	OPTIONS	DEFAULT
`FallbackUrl`	A failover URL for which Telnyx will retrieve the TeXML call instructions if the `Url` is not responding.
`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).
`StatusCallback`	URL destination for Telnyx to send status callback events to for the call.
`StatusCallbackMethod`	HTTP request type used for `StatusCallBack`.	`GET`,`POST`	`POST`
`To`	The phone number of the called party. Phone numbers are formatted with a '+' and country code, e.g. +16175551212 (E.164 format).
`Url`	The URL from which Telnyx will retrieve the TeXML call instructions.
`UrlMethod`	HTTP request type used for `Url`.	`GET`,`POST`	Inherited from TeXML Application setting.

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" \
--data-urlencode "StatusCallback=https://www.example.com/statuscallback-listener" \
--header "Authorization: Bearer APIAuthKey_fromPortal"

Success Response

{
  "from": "+13120001234",
  "status": "queued",
  "to": "+13121230000"
}

Conference

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.

Verb Attributes

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 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`
`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`	Specify which events shall trigger webhook to the URL from `recordingStatusCallback`.	`in-progress`, `completed`	`completed`

Example

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

Expected Callbacks

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": "[email protected]",
   "SequenceNumber": "1",
   "StatusCallbackEvent": "participant-join",
   "Timestamp": "2021-04-28 22:51:29.993535Z",
   "To": "+12132045020"
}

start

{
   "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": "[email protected]",
   "SequenceNumber": "2",
   "StatusCallbackEvent": "conference-start",
   "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": "[email protected]",
   "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 1234",
   "From": "[email protected]",
   "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 1234",
   "From": "[email protected]",
   "SequenceNumber": "5",
   "StatusCallbackEvent": "participant-speech-start",
   "Timestamp": "2021-04-28 22:51:51.480853Z",
   "To": "+12132045020"
}

If recordingStatusCallbackEvent are set you may expect one of the following webhooks:

in-progress

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:0YXD2QVLtba0UDTe3k6H9gEsAEs4qRLsuy6u_zoS364PKR6DApuKuw",
   "CallSidLegacy": "v2:0YXD2QVLtba0UDTe3k6H9gEsAEs4qRLsuy6u_zoS364PKR6DApuKuw",
   "ConferenceSid": "58b4eda9-03de-4bee-9178-d0e10d83e519",
   "RecordingStatus": "in-progress",
   "To": "+12132045020"
}

completed

{
   "AccountSid": "cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
   "CallSid": "v2:0YXD2QVLtba0UDTe3k6H9gEsAEs4qRLsuy6u_zoS364PKR6DApuKuw",
   "CallSidLegacy": "v2:0YXD2QVLtba0UDTe3k6H9gEsAEs4qRLsuy6u_zoS364PKR6DApuKuw",
   "ConferenceSid": "58b4eda9-03de-4bee-9178-d0e10d83e519",
   "FriendlyName": "Room 1234",
   "From": "[email protected]",
   "RecordingChannels": "1",
   "RecordingDuration": "366",
   "RecordingSid": "855e80cf-511f-4a97-8476-9e4d49f12267",
   "RecordingSource": "Conference",
   "RecordingStartTime": "2022-04-28 22:51:52.080853Z",
   "RecordingStatus": "completed",
   "RecordingUrl": "https://recording.com/your-recording-url",
   "To": "+12132045020"
}

Status Callback HTTP Attributes

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`	A 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. First callback has the lowest, last callback the highest.
`StatusCallbackEvent`	An event generating the callback.
`RecordingSid`	A unique identifier for the conference recording.
`RecordingUrl`	The url of the recorded audio.
`RecordingStatus`	Indicates the status of recording. Expected values: `in-progress`, `completed`.
`RecordingDuration`	The lenght of the recording in seconds
`RecordingChannels`	The number of channels in the final recording. For conferences a single channel `1` is supported only.
`ReocordingStartTime`	The timestamp of when the recording was started.
`RecordingSource`	Initiation method of creating the recording. `Conference` is returned for recordings initiated from `Conference` noun.

Enqueue

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

Verb Attributes

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 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`

Examples

<?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>

Gather

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

Verb Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
`action`	URL where TeXML will send the gathered digits. Same method (`GET`/`POST`) as set for the TexML application is used. Transfers control of the current call to the TeXML file returned.
`input`	Specifies which input should be accepted.	`dtmf`, `speech`, `dtmf speech`	`dtmf`
`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`	Specifies the language used for speech recognition.	docs/api/v2/call-control/Call-Commands#callTranscriptionStart)	`en`
`partialResultCallback`	URL where TeXML in real time will be sending recognition results. These transcriptions may change as the speech recognition progresses.
`partialResultCallbackMethod`	HTTP request type used for `partialResultCallback`.	`GET`, `POST`	`POST`
`speechTimeout`	Specifies the timeout (in seconds) after which speech recognition is stopped. If `auto` is set speech recognition is stopped after first pause in speech.	`1`-`60` or `auto`
`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. Same method (`GET`/`POST`) as set for the TeXML application is used. Transfers control of the current call to the TeXML file returned.		`action`

Nouns

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

Example

<?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>

Expected Callbacks

action

{
    "AccountSid":"cb6cfbbc-eb00-41af-a3f3-0d7b32009e4b",
    "CallSid":"v2:DPNqxVjTNtQYaKdcKbU0QgRFrQ3YzuAQrVYC4Ggcuq7zTpDkUB7A4w",
    "CallSidLegacy":"v2:DPNqxVjTNtQYaKdcKbU0QgRFrQ3YzuAQrVYC4Ggcuq7zTpDkUB7A4w",
    "Digits":"1",
    "From":"[email protected]",
    "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.

Leave

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

Verb Attributes

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

Example

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

Hangup

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

Example

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

Expected Callbacks

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

Status Callback HTTP Attributes

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`, `busy` 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. First callback has the lowest, last callback the highest.
`HangupSource`	Source of the hangup. The value can be `callee` or `caller`

Pause

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.

Verb Attributes

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

Example

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

Play

The <Play> verb plays an MP3 or WAV audio file back to the caller. The file can be chosen to be either fetched by Telnyx from the URL you provide, or from the Telnyx Media Storage API, once previously uploaded.

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

Verb Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
`loop`	The number of times between 1-100 to repeat the audio file.	`1`-`100`. `0` for infinite.	`1`
`mediaStorage`	If `true`, the audio file will be fetched from Telnyx Media Storage. The value of the tag should contain the `media_name` pointing to a file prior uploaded by the same user.	`true`, `false`	`false`

Examples

<?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>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Play mediaStorage="true">my-stored-media-name</Play>
</Response>

Record

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.

Verb Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
`action`	Optional URL where TeXML will make a request to when the 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`
`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`

Additional Action Parameters

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.

Example

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

Redirect

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

Verb Attributes

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

Example

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

Reject

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.

Verb Attributes

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

Example

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

Say

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

Verb Attributes

ATTRIBUTE	DESCRIPTION	OPTIONS	DEFAULT
`voice`	Optional text-to-speech voice type. For `basic` text-to-speech use `man` or `woman`. For `premium` text-to-speech including additional language accent support beyond `en-US`, use `alice`.	`man`, `woman`, `alice`	`man`
`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`.	See RESTful API documentation	`en-US`
`loop`	The number of times to repeat the speech.	`1`-`100`. `0` for infinite.	`1`

Example

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

Start

The <Start> verb starts streaming the media from a call to a specific WebSocket address in near-realtime. Audio will be delivered as base64-encoded RTP packets, wrapped in JSON payloads.

Nouns

NOUN	DESCRIPTION	ATTRIBUTES
`<Stream>`	Provides information about desired media stream	`url`, `track`

Noun Attributes

<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`

Examples

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

Stop

The <Stop> verb stops streaming a call to a WebSocket.

Nouns

NOUN	DESCRIPTION
`<Stream>`	Selects current media stream, no attributes need to be provided

Examples

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

Previous: TeXML Applications

Next: TeXML REST Commands