Overview

A proper TeXML response comprises the following elements:

• <Response> element -- tag defining the body of the TeXML document
• verb -- an XML tag denoting the desired action
• noun -- an XML tag denoting the object of the desired action

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.