This is the API V2 documentation. To switch out of beta revert back to our API V1.

Open SidemenuAPI Reference
API Reference
Close Sidemenu

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

Responseresponse

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.

Verbsverbs

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

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

VERBACTION
<Dial>Initiates a call to a phone or SIP number
<Gather>Collects DTMF input from the caller or called party
<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
<Reject>Rejects the call
<Say>Executes a Text-to-Speech instruction

Nounsnouns

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

PARAMETERDESCRIPTION
CallSidA unique identifier for this call, generated by Telnyx.
FromThe phone number of the party that initiated the call. Phone numbers are formatted with a '+' and country code, e.g. +16175551212 (E.164Telnyx Developers format).
ToThe phone number of the called party. Phone numbers are formatted with a '+' and country code, e.g. +16175551212 (E.164Telnyx Developers format).

Data Formatsdata-formats

Dates and Timesdates-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 Numbersphone-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:telnyxagent@sip.telnyx.com

Dialdial

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

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
actionOptional 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.
methodHTTP request type used to retrieve the next set of instructions.GET, POSTPOST
callerIdCaller ID that must be a valid E.164Telnyx Developers format number.
hangupOnStarThe hangupOnStar attribute lets the initial caller hang up on the called party by pressing the '*' key on their phone.true, falsefalse
recordThe 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-dualdo-not-record
recordingStatusCallbackOptional URL that tells Telnyx where to make its GET or POST request when the recording is available.
recordingStatusCallbackMethodHTTP request type used for recordingStatusCallBack.GET, POSTPOST
recordingStatusCallbackEventThe recording events for which Telnyx should a webhook on. Multiple events are separated by a space.in-progress, completed, absentcompleted

Nounsnouns

NOUNDESCRIPTIONOPTIONAL ATTRIBUTES
<Number>E.164Telnyx Developers phone number.statusCallback, statusCallbackEvent, statusCallbackMethod
<Sip>SIP URI.statusCallback, statusCallbackEvent, statusCallbackMethod

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&amp;x-myotherheader=bar
        </Sip>
    </Dial>
</Response>

Noun Attributesnoun-attributes

<Number> and <Sip> Attributes

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
statusCallbackA 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 PortalTelnyx Developers.
statusCallbackEventThe call events for which Telnyx should a webhook on. Multiple events are separated by a space.initiated, ringing, answered, completedcompleted
statusCallbackMethodHTTP request type Telnyx should use when requesting the statusCallback URL.GET, POSTPOST
urlOptional 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.
methodHTTP request type used for url.GET, POSTPOST

<Number> Only Attributes

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
sendDigitsDigits (DTMF tones) to be automatically applied when the call is answered. Use w for 0.5s of silence.Any digits

Status Callback HTTP Attributesstatus-callback-http-attributes

The attributes contained in the statusCallback request to your URL.

ATTRIBUTEDESCRIPTION
CallSidA unique identifier for this call, generated by Telnyx.
ParentCallSidA unique identifier for the parent call.
CallStatusA descriptive status for the call. The value is one of initiated, ringing, in-progress, completed, busy or canceled.
TimestampThe timestamp when the event was fired, given as UTC in RFC 2822Telnyx Developers format.
CallbackSourceA 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.
FromThe outbound caller number.
ToThe inbound callee number.

Simultaneous Dialingsimultaneous-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:connection@sip.telnyx.com</Sip></Sip>
    <Number>+18771234567</Number>
  </Dial>
</Response>

Examplesexamples

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

Initiate a TeXML Call using the Telnyx APIinitiate-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 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 PortalTelnyx Developers.

curl -X POST https://api.telnyx.com/v2/texml/calls/{connection_id} \
--data-urlencode "To=+ 13121230000" \
--data-urlencode "From=+ 13120001234" \
--header "Authorization: Bearer APIAuthKey_fromPortal"

Conferenceconference

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

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
beepSpecify 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, onExittrue
mutedSpecify whether a participant is muted or not.true, falsefalse
startConferenceOnEnterStart 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, falsetrue
endConferenceOnExitIf 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, falsefalse
statusCallbackA URL for Telnyx to send webhook requests to on each event specified in the statusCallbackEvent attribute.
statusCallbackEventThe conference events for which Telnyx should a webhook on. Multiple events are separated by a space.start, end, join, leaveNone
statusCallbackMethodHTTP request type Telnyx should use when requesting the statusCallback URL.GET, POSTPOST

Exampleexample

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

Gathergather

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

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
actionURL 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.
finishOnKeyThe set of digits, (0-9, *, #), that indicates the end of the gather.
numDigitsThe number of digits to be gathered.
languageThe language used.See RESTful API documentationAPIen-US
timeoutTime 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-1205

Nounsnouns

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

Exampleexample

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

Hanguphangup

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

Exampleexample

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

Pausepause

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

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
lengthOptional length of time in seconds to wait.1-1801

Exampleexample

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

Playplay

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

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

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
loopThe number of times between 1-100 to repeat the audio file.1-100. 0 for infinite.1

Exampleexample

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

Recordrecord

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

Verb Attributesverb-attributes

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
actionOptional 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.
methodHTTP request type used to retrieve the next set of instructions.GET, POSTPOST
finishOnKeySet of digits specified together, any one of which will end the recording.Any digit, #, *1234567890*#
playBeepWhether or not a sound is played before the start of a recording.true, falsetrue
recordingStatusCallbackOptional URL that tells Telnyx where to make its GET or POST request when the recording is available.
recordingStatusCallbackMethodHTTP request type used for recordingStatusCallBack.GET, POSTPOST

Additional Action Parametersadditional-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:

ATTRIBUTEDESCRIPTION
RecordingURLThe 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.
RecordingDurationThe duration of the recorded audio (in seconds). To get a final accurate recording duration after any trimming of silence, use recordingStatusCallback.
DigitsThe key (if any) pressed to end the recording or hangup if the caller hung up.

Exampleexample

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

Redirectredirect

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

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
methodThe type of requested used <Redirect> URL.GET, POSTPOST

Exampleexample

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

Rejectreject

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

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
reasonThe tone to play to indicate the reason the call was rejected.rejected, busyrejected

Exampleexample

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

Saysay

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

Verb Attributesverb-attributes

ATTRIBUTEDESCRIPTIONOPTIONSDEFAULT
voiceOptional 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, aliceman
languageISO 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 documentationAPIen-US
loopThe number of times to repeat the speech.1-100. 0 for infinite.1

Exampleexample

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