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.

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

Dynamic parameters

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

Inserting dynamic content

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.

Iterate through lists

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>

Render conditional content

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.

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

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

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.