# Telnyx Calling: TeXML — Full Documentation > Complete page content for TeXML (Calling section) of the Telnyx developer docs (https://developers.telnyx.com). > Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this subsection: https://telnyx-openapi-ng.s3.us-east-1.amazonaws.com/llms/calling/texml.txt ## Guides ### TeXML Fundamentals > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-fundamentals.md ## Overview TeXML is an XML-based markup language to define call control and processing instructions. When properly configured, Telnyx will fetch TeXML instructions from the user's application and process the calls accordingly. See [Verbs & Nouns](/docs/voice/programmable-voice/texml-twiml-compatibility). ## TeXML Application An instance of TeXML Application is a collection of configuration parameters that defines the interaction between Telnyx and the user's application: | Field | Description | |-------|-------------| | **Application Name** | A descriptive name to identify your TeXML application. | | **AnchorSite** | Defines preferable data center for handling the traffic. In case of `latency` ICMP ping to the webhook URL address will be used to calculate the closed data center. | | **Voice method** | HTTP method that will be used to interact with your webhooks | | **Webhook URL** | The URL where Telnyx will fetch TeXML instructions when a call is initiated. The instruction can be served by Telnyx. In that case select `TeXML bin URL`. See [TeXML bin quickstart](/docs/voice/programmable-voice/texml-bin-quickstart) for more details. | | **Webhook Failover URL** | A backup URL that Telnyx will use if the primary webhook URL fails to respond | | **Call progress events URL** | URL where Telnyx will send event callbacks related to your calls | | **Status Callback Method** | HTTP method (GET or POST) used for status callbacks | | **Hang-up on timeout** | Specifies the number of seconds Telnyx will wait for initial application response before hanging up | | **DTMF Type** | Configuration for how DTMF (touch-tone) inputs are handled | | **Enable Call Cost** | Specify if the call cost webhook should be sent | A TeXML Application can be created through the [Telnyx Mission Control Portal](https://portal.telnyx.com/#/call-control/texml/new) or via the [Telnyx API](https://developers.telnyx.com/api-reference/texml-applications/creates-a-texml-application#creates-a-texml-application). ## Instruction Fetching See [Instruction Fetching](/docs/voice/programmable-voice/texml-instruction-fetching). ## Twilio Compatibility See [Twilio Compatibility](/docs/voice/programmable-voice/texml-twiml-compatibility). --- ### Instruction Fetching > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-instruction-fetching.md On inbound calls (PSTN or External SIP to Telnyx), Telnyx fetches TeXML instructions from the URL defined on the TeXML Application associated with the SIP subdomain or phone number. On outbound calls (Telnyx to PSTN or External SIP), there are two ways the user can trigger instructions fetching, the details of which are described below. ## Instruction Fetching on Inbound Calls An instance of TeXML application can have a specific SIP subdomain or phone number assigned to it. When Telnyx receives a call to that SIP subdomain or phone number, Telnyx will fetch the instructions from the URL defined on the TeXML Application. ## Instruction Fetching on Outbound Calls ### Using TeXML Application Instructions fetching can be triggered by [TeXML Calls API](/api-reference/texml-rest-commands/initiate-an-outbound-call). In this case, a TeXML application is required. Example: ```bash curl -L 'https://api.telnyx.com/v2/texml/Accounts/:account_sid/Calls' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "ApplicationSid": "xxxxxxxx", "To": "+13121230000", "From": "+13120001234", "Url": "https://www.example.com/texml.xml", "StatusCallback": "https://www.example.com/statuscallback-listener" }' ``` ### Using SIP Trunking Connections The user can configure a SIP trunking connection of any type to "Park Outbound Calls". When the user initiates an outbound call on that SIP connection, Telnyx will "park" that call leg, fetch the instructions from the URL defined on the connection, and then process the call based on the instructions. In this use case, a TeXML application is not required. ## HTTP Request Details When a call is being handled by a TeXML application, Telnyx makes HTTP requests to fetch instructions from the user's application. These requests include specific parameters that provide context about the call, allowing the user's application to generate appropriate TeXML responses. * Method: Configurable (GET or POST, default is GET) * URL: The URL configured for the user's TeXML application * Failover URL: Used if the primary URL is unavailable (optional) ### Request Parameters When Telnyx makes a request to fetch TeXML instructions, the following parameters are always included: | Parameter | Description | Example | |-----------|-------------|---------| | AccountSid | The user's Telnyx account ID | 6a9a7976-012e-45d2-9258-6f5dc68d861e | | CallSid | Unique identifier for the call | fcc47bc6-e428-11ed-ad79-02420aef00b4 | | CallSidLegacy | Legacy call ID format for backward compatibility | fcc47bc6-e428-11ed-ad79-02420aef00b4 | | CallerId | The identifier of the caller | +13122010091 | | CallingPartyType | The type of calling party. Possible values: sip or pstn | sip | | From | The phone number that initiated the call | +13122010091 | | FromSipUri | Sip Uri address of the caller | +13122010091@10.239.182.10 | | To | The phone number that received the call | +13122010090 | | ToSipUri | Sip Uri address that received the call | +13122010090@sip.telnyx.com | | ConnectionId | Telnyx connection ID used for the call | 1568109700606592442 | ### Optional Parameters Depending on the call context, additional parameters are added to the request. Full list of the parameters can be found on the documentation page for each of the [TeXML verbs](/docs/voice/programmable-voice/texml-twiml-compatibility) ### Parameter Format Depending on the HTTP method selected for the requests, the parameters are added in the following way: - GET requests - as URL query parameters - POST requests - in the request body as form-encoded data ### Response Requirements The user's application should respond with valid TeXML. The response should: - Be valid XML with a root `` element - Not exceed size limits - Return HTTP status code 200 OK ### Example #### Request (GET method) ```bash GET /texml-instructions? AccountSid=6a9a7976-012e-45d2-9258-6f5dc68d861e& CallSid=fcc47bc6-e428-11ed-ad79-02420aef00b4& CallSidLegacy=fcc47bc6-e428-11ed-ad79-02420aef00b4& From=%2B13122010091& To=%2B13122010090& ConnectionId=1568109700606592442& CallStatus=in-progress ``` #### Response ```xml Welcome to the Telnyx TeXML service. Press 1 to continue. ``` ## Best Practices Here are a few best practices to follow: - Always verify the CallSid parameter to ensure the request is legitimate - Include error handling in your application to handle unexpected parameters - Keep response times low to avoid call delays - Use the parameters to customize call flows based on caller information - Test your application with various parameter combinations - By properly handling these parameters, you can create dynamic, responsive TeXML applications that provide excellent caller experiences --- ### TeXML Interpreter > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-interpreter.md ## Basic Syntax A proper TeXML response comprises the following elements: * **`` 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 Thank you for calling Telnyx. Please hold. +13129457420 ``` ## Dynamic parameters When creating a TeXML set of instructions you can make use of [Mustache Templates](https://mustache.github.io/mustache.5.html) 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 {{PhoneNumber}} ``` The phone number can now be replaced at runtime by setting your TeXML webhook URL to have `PhoneNumber` as a parameter. ```bash 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 YOUR_API_KEY" ``` 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](/api-reference/texml-applications/list-all-texml-applications). ### 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. ```bash 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 YOUR_API_KEY" ``` Then you can handle the `PhoneNumbers` parameter in the TeXML instructions using the following syntax. ```xml {{#PhoneNumbers}} {{.}} {{/PhoneNumbers}} ``` This will end up being parsed as ```xml +18771234567 +18771234568 ``` ### 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 {{#if From == +18771234567}} +18771234568 {{#elseif From == +18771234568}} +18771234567 {{#else}} No valid number is present {{/if}} ``` Supported operators are `==`, `!=` and no operator for checking if the parameter value is not null. --- ### TeXML TwiML Compatibility > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-twiml-compatibility.md TeXML services was created to allow the easy migration from Twilio to Telnyx, allowing you to use the same verbs and nouns in both platforms. This page provides a comparison of verb support between TeXML and TwiML, helping you understand which features are available in each platform. ## Verb Compatibility | Verb | TwiML Support | TeXML Support | |------|---------------|---------------| | [``](/docs/voice/programmable-voice/texml-verbs/aigather) | ❌ Not supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/dial) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/enqueue) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/gather) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/hangup) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/httprequest) | ❌ Not supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/leave) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/pause) | ✅ Supported | ✅ Supported | | `` | ✅ Supported | ❌ Not supported | | [``](/docs/voice/programmable-voice/texml-verbs/play) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/record) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/redirect) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/refer) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/reject) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/say) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/siprec) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/stop) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/stream) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/suppression) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/transcription) | ✅ Supported | ✅ Supported | For detailed information about particular TeXML verb click the link under the name of the verb in the table. ## Noun Compatibility | Noun | TwiML Support | TeXML Support | |------|---------------|---------------| | `` | ✅ Supported | ❌ Not supported | | [``](/docs/voice/programmable-voice/texml-verbs/conference) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/dial#child-verbsnouns) | ✅ Supported | ✅ Supported | | `` | ✅ Supported | ❌ Not supported | | [``](/docs/voice/programmable-voice/texml-verbs/dial#child-verbsnouns) | ✅ Supported | ✅ Supported | | [``](/docs/voice/programmable-voice/texml-verbs/dial#child-verbsnouns) | ✅ Supported | ✅ Supported | | `` | ✅ Supported | ❌ Not supported | More information about the nouns can be found on [`` documentation page](/docs/voice/programmable-voice/texml-verbs/dial) ## REST API Endpoint Compatibility The following table outlines the compatibility between Twilio's REST API endpoints and Telnyx's TeXML API endpoints. | Title | Compatibility | Method | Endpoint | |-------|--------|----------|---------------| | [Fetch a call](/api-reference/texml-rest-commands/fetch-a-call) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Calls/{CallSid}` | | [Update call](/api-reference/texml-rest-commands/update-call) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Calls/{CallSid}` | | [Fetch multiple call resources](/api-reference/texml-rest-commands/fetch-multiple-call-resources) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Calls` | | [Initiate an outbound call](/api-reference/texml-rest-commands/initiate-an-outbound-call) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Calls` | | [Fetch a conference resource](/api-reference/texml-rest-commands/fetch-a-conference-resource) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}` | | [Update a conference resource](/api-reference/texml-rest-commands/update-a-conference-resource) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}` | | [List conference resources](/api-reference/texml-rest-commands/list-conference-resources) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Conferences` | | [List conference participants](/api-reference/texml-rest-commands/list-conference-participants) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Participants` | | [Dial a new conference participant](/api-reference/texml-rest-commands/dial-a-new-conference-participant) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Participants` | | [List conference recordings](/api-reference/texml-rest-commands/list-conference-recordings) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings` | | [Get conference participant resource](/api-reference/texml-rest-commands/get-conference-participant-resource) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Participants/{CallSid}` | | [Update a conference participant](/api-reference/texml-rest-commands/update-a-conference-participant) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Participants/{CallSid}` | | [Delete a conference participant](/api-reference/texml-rest-commands/delete-a-conference-participant) | ✅ Compatible | DELETE | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Participants/{CallSid}` | | [Request recording for a call](/api-reference/texml-rest-commands/request-recording-for-a-call) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Recordings` | | [Fetch recordings for a call](/api-reference/texml-rest-commands/fetch-recordings-for-a-call) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Calls/{CallSid}/Recordings` | | [Update recording on a call](/api-reference/texml-rest-commands/update-recording-on-a-call) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Recordings/{RecordingSid}` | | [Fetch multiple recording resources](/api-reference/texml-rest-commands/fetch-multiple-recording-resources) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Recordings` | | [Fetch recording resource](/api-reference/texml-rest-commands/fetch-recording-resource) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Recordings/{RecordingSid}` | | [Delete recording resource](/api-reference/texml-rest-commands/delete-recording-resource) | ✅ Compatible | DELETE | `/Accounts/{AccountSid}/Recordings/{RecordingSid}` | | [Fetch recordings for a conference](/api-reference/texml-rest-commands/fetch-recordings-for-a-conference) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Conferences/{ConferenceSid}/Recordings` | | [Start streaming media from a call](/api-reference/texml-rest-commands/start-streaming-media-from-a-call) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Streams` | | [Update streaming on a call](/api-reference/texml-rest-commands/update-streaming-on-a-call) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Streams/{StreamSid}` | | [Request siprec session for a call](/api-reference/texml-rest-commands/request-siprec-session-for-a-call) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Siprec` | | [Updates siprec session for a call](/api-reference/texml-rest-commands/updates-siprec-session-for-a-call) | ✅ Compatible | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Siprec/{SiprecSid}` | | [List recording transcriptions](/api-reference/texml-rest-commands/list-recording-transcriptions) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Recordings/{RecordingSid}/Transcriptions` | | [Fetch a recording transcription resource](/api-reference/texml-rest-commands/fetch-a-recording-transcription-resource) | ✅ Compatible | GET | `/Accounts/{AccountSid}/Recordings/{RecordingSid}/Transcriptions/{TranscriptionSid}` | | [Delete a recording transcription](/api-reference/texml-rest-commands/delete-a-recording-transcription) | ✅ Compatible | DELETE | `/Accounts/{AccountSid}/Recordings/{RecordingSid}/Transcriptions/{TranscriptionSid}` | | Create a Queue resource | ✅ Compatible | POST | `/Accounts/{AccountSid}/Queues.json` | | Fetch a Queue resource | ✅ Compatible | GET | `/Accounts/{AccountSid}/Queues/{Sid}.json` | | Read multiple Queue resources | ✅ Compatible | GET | `/Accounts/{AccountSid}/Queues.json` | | Update a Queue resource | ✅ Compatible | POST | `/Accounts/{AccountSid}/Queues/{Sid}.json` | | Delete a Queue resource | ✅ Compatible | DELETE | `/Accounts/{AccountSid}/Queues/{Sid}.json` | | Fetch a Member resource | ✅ Compatible | GET | `/Accounts/{AccountSid}/Queues/{QueueSid}/Members/{CallSid}.json` | | Read multiple Member resources | ✅ Compatible | GET | `/Accounts/{AccountSid}/Queues/{QueueSid}/Members.json` | | Start a Real-Time Transcription | ❌ Not supported | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Transcriptions.json` | | Stop a Real-Time Transcription | ❌ Not supported | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Transcriptions/{Sid}.json` | | Starting a Pay session | ❌ Not supported | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Payments.json` | | Update a Pay session | ❌ Not supported | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/Payments/{Sid}.json` | | Create a UserDefinedMessage | ❌ Not supported | POST | `/Accounts/{AccountSid}/Calls/{CallSid}/UserDefinedMessages.json` | | Create a UserDefinedMessageSubscription | ❌ Not supported | POST | `Accounts/{AccountSid}/Calls/{CallSid}/UserDefinedMessageSubscriptions.json` | For detailed information about TeXML REST API endpoints and their usage, please use the links to the documentation from the table. --- ### Dynamic TeXML Bins > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-bin-dynamic.md In this guide, we’ll cover how to create dynamic parameters in TeXML Bin using Mustache Templates. You can get started with TeXML Bin in the Mission Control Portal by following the first steps in our [previous guide](/docs/voice/programmable-voice/texml-bin-quickstart "TeXML Bin Static Interactions"). ## Dynamic parameters for TeXML Mustache is a logic-less web template system used mainly for mobile and web applications. And a great way to generate instructions dynamically at runtime when creating a TeXML set of instructions. By using Mustache Dynamic templating you can insert content into your TeXML instructions through HTTP request parameters in the webhook URL that is used to fetch your TeXML set of instructions. For example, you could create a TeXML set of instructions that calls a phone number which is set until the HTTP request is made to fetch your TeXML instructions. To do this you'll first need create your TeXML instructions using Mustache Templating, and set the `{{PhoneNumber}}` as a variable like this: ```xml {{PhoneNumber}} ``` After pasting the above content, kindly check and remove any new lines added The phone number can now be replaced at runtime by setting your TeXML webhook url to have `PhoneNumber` as a parameter like so: *Don't forget to update `YOUR_API_KEY` here.* ```bash 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 YOUR_API_KEY" ``` The request parameters set by Telnyx - for example, CallSid, From and To - are also available for the Mustache Template. The list of parameters for each of the callbacks can be found on our [TeXML Instruction Fetching](/docs/voice/programmable-voice/texml-instruction-fetching "TeXML Instruction Fetching") page. ### Iterating through lists TeXML Bin allows users to set arrays as parameters in the TeXML webhook url and let Mustache Template handle them. For example, if you want the dial command to have two numbers, you could add a `Numbers` list parameter to your callback Url. ```bash 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 YOUR_API_KEY" ``` Then you can handle the `PhoneNumbers` parameter in the TeXML instructions using the following syntax: ```xml {{#PhoneNumbers}} {{.}} {{/PhoneNumbers}} ``` This will end up being parsed as: ```xml +18771234567 +18771234568 ``` ### How to 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 an specific number depending on `From` parameter present in the HTTP request. ```xml {{#if {{From}} == +18771234567}} +18771234568 {{#elseif {{From}} == +18771234568}} +18771234567 {{#else}} No valid number is present {{/if}} ``` Note that supported operators are `==`, `!=` and there is no operator for checking if the parameter value is not null. --- ### Sending HTTP Requests > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-sending-http-requests.md In the [previous tutorial](/docs/voice/programmable-voice/texml-bin-dynamic), we explained how to use dynamic parameters in the TeXML instructions. In this tutorial, we’ll cover how to integrate your systems using HTTP requests from a TeXML file without needing your own server-side application, as well as retrieve required information for call flows from external systems and send notifications to any REST API. ## Sending HTTP request The requests can be sent using `` verb in the following way: ```xml Authorization Bearer API_key Content-Type application/json ``` As part of the verb structure you can define the following aspects of the request: * Headers * The method for the request (GET or POST) * And the body ## Synchronous requests The requests are sent asynchronously by default. The TeXML process does not wait for the result of the request and immediately executes the next instruction from the TeXML file. It is possible to change that behavior by using the `async` attribute and setting it to true. In that case, the TeXML process will wait for the HTTP response and send a callback to the action URL immediately afterward. ```xml Authorization Bearer API_key Content-Type application/json ``` You can define new variables that will be sent with the callbacks using the values from the HTTP response. ```xml Authorization Bearer API_key Content-Type application/json JSON 200 contact.name.first first_name contact.name.last last_name ``` ## Using secrets API keys or any other secrets can be stored in the secure storage. You can upload them using a dedicated REST endpoint. ```bash curl --location --request POST 'https://api.telnyx.com/v2/texml/secrets/' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "name":"your_secret_name", "value":"your_secret_value" }' ``` Stored secrets can be used in the TeXML definitions. They will be redacted from all logs and won’t be sent in the callbacks as well. ```xml Authorization Bearer {{#secret}}your_secret_name{{/secret}} Content-Type application/json ``` ## Sending notifications about the call to your Slack workspace using information about the caller retrieved from Salesforce database In this section we will present how to retrieve the information about the caller from the Salesforce database and send it as a message to the Slack channel. 1. Upload an api_key to your Slack workspace under the name slack_api_key ```bash curl --location --request POST 'https://api.telnyx.com/v2/texml/secrets/' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "name":"slack_api_key", "value":"your_api_key_value" }' ``` 2. Upload a token to the Salesforce API under the name salesforce_token ```bash curl --location --request POST 'https://api.telnyx.com/v2/texml/secrets/' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "name":"salesforce_token", "value":"your_token_value" }' ``` 3. Create a TeXML file that will send a message to the Slack channel and make a call to your SIP account and name it slack_http_request ```xml Authorization Bearer {{#secret}}slack_api_key{{/secret}} Content-Type application/json sip:jack@example.com ``` 4. Create a TeXML file that will retrieve the information about the caller and their name from Salesforce. ```xml Authorization Bearer {{#secret}}salesforce_token{{/secret}} Content-Type application/json JSON 200 records[0].Name caller_name ``` 5. Update your TeXML application webhook URL (If you need to create your application, please take a look at this [tutorial](/docs/voice/programmable-voice/texml-setup)) ![TeXML application setup](/img/salesforce_slack_tutorial.png) 6. Make a call to the number associated with the TeXML application and observe the notification in your Slack workspace --- ### TeXML Answering Machine > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-answering-machine.md TeXML is an XML-based data structure you can use to control calls with Telnyx and is the quickest way to get started with Programmable Voice using a simple .xml file, allowing you to specify call instructions in your file using commands called verbs and nouns. ## Initiating a TeXML outbound call using REST endpoint with AMD enabled There are 2 possible options for using Answering Machine Detection for outbound calls: 1. __Synchronous mode__: In this case, the TeXML instructions are not executed until the results of AMD process are provided in the status callback. The new instructions can be sent back as response to be processed by the TeXML engine. 2. __Asynchronous mode__: Here, the TeXML instructions are processed in parallel to the AMD process. The results of the AMD analysis are being provided in the AsyncAmdStatusCallback callback. ### Synchronous mode request The outbound TeXML call with AMD support enable in the synchronous mode can be requested in the following way: *Don't forget to update `YOUR_API_KEY` here.* ```bash curl --request POST \ --url https://api.telnyx.com/v2/texml/calls/{connection_id} \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "From": "+13127367421", "To": "your-sip-user@sip.telnyx.com", "Url": "https://your-server.example.com/texml/instructions", "FallbackUrl": "https://your-server.example.com/texml/fallback", "StatusCallback": "https://your-server.example.com/callback/status", "StatusCallbackMethod": "POST", "Method": "POST", "MachineDetection": "Enable", "DetectionMode": "Premium", "AsyncAmd": "false" }' ``` The results of the analysis will be sent as a value of the `AnsweredBy` parameter of the `StatusCallback` request. #### `AnsweredBy` parameter values | Value | Description | |-------|-------------| | `human` | A human answered the call | | `machine` | An answering machine was detected | | `fax` | A fax machine was detected | | `unknown` | Detection was inconclusive | The `MachineDetection` parameter accepts the following values: `Enable`, `Disable` (default), and `DetectMessageEnd`. The `DetectionMode` parameter accepts `Regular` (default) or `Premium`. ### Asynchronous mode request Similarly, the asynchronous AMD processing can be requested for outgoing TeXML calls: ```bash curl --request POST \ --url https://api.telnyx.com/v2/texml/calls/{connection_id} \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "From": "+13127367421", "To": "your-sip-user@sip.telnyx.com", "Url": "https://your-server.example.com/texml/instructions", "FallbackUrl": "https://your-server.example.com/texml/fallback", "Method": "POST", "StatusCallback": "https://your-server.example.com/callback/status", "StatusCallbackMethod": "POST", "MachineDetection": "Enable", "DetectionMode": "Premium", "AsyncAmd": "true", "AsyncAmdStatusCallback": "https://your-server.example.com/callback/amd-status", "AsyncAMDStatusCallbackMethod": "POST" }' ``` The results of the AMD analysis will be sent as callback requests to the address provided as `AsyncAmdStatusCallback` parameter. Note that this can be used for basic and premium AMD. #### `AsyncAmdStatusCallback` parameters The callback to your `AsyncAmdStatusCallback` URL includes the following parameters: | Parameter | Description | |-----------|-------------| | `AnsweredBy` | The result of AMD analysis (`human`, `machine`, `fax`, or `unknown`) | | `CallSid` | The unique identifier for the call | | `AccountSid` | Your Telnyx account SID | --- ## Markup Language ### Dial > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/dial.md The `` verb transfers an existing call to another destination. `` will end this new call if: the called party does not answer, the number does not exist, or Telnyx receives a busy signal. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT action Optional URL where TeXML will make a request when the `` call ends to retrieve a new set of TeXML instructions to continue the call flow. - method HTTP method to use when requesting the action URL. 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. false timeout The number of seconds to wait for the called party to answer the call. 5 - 120 30 timeLimit The maximum duration of the call in seconds. 60 - 14400 14400 record The record attribute lets you record both legs of a call within the associated `` verb. It works with the `` and `` nouns only. If you want to record the conference, please use the record attribute on `` noun. Recordings are available in two options: single or dual. do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual do-not-record recordingChannels The number of channels in the final recording. Possible values are: single (for mono) and dual (for stereo). Defaults to single. single, dual single recordMaxLength Defines the maximum length for the recording in seconds (0 for infinite) 0 - 14400 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 sendRecordingUrl Defines if the recording URL is sent in the callbacks. true 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, tw, ve, za, us, us-old, uk us audioUrl A URL to an audio file that will be played as a custom ringback tone to the caller while waiting for the call to be answered. When set, overrides the ringTone attribute. - answerOnBridge If set to true, the inbound call will not be answered until the dialed call is answered. This preserves the ringing state on the caller's side. Only takes effect when the inbound call has not yet been answered. false sequential When set to true with multiple `` or `` nouns, Telnyx dials each destination one at a time in the order listed. The next destination is attempted only if the current attempt completes without being answered. If omitted or set to false, all destinations are dialed at the same time and the first answered call is connected. false passDiversionHeader When set to true, the Diversion SIP header from the inbound call is passed through to the outbound dial attempt. false machineDetectionSpeechThreshold Maximum duration of a greeting in milliseconds. If a greeting is longer than this value, the call is classified as a machine. Only used when machineDetection is enabled and detectionMode is Premium. - machineDetectionSpeechEndThreshold Silence duration in milliseconds after a greeting to wait before classifying the call as a machine. Only used when machineDetection is enabled and detectionMode is Premium. - machineDetectionSilenceTimeout Maximum duration of initial silence in milliseconds before the call is classified as a silence. Only used when machineDetection is enabled and detectionMode is Premium. - ## Child verbs/nouns NOUN/VERB DESCRIPTION Number Specifies a phone number to dial. Sip The `` noun specifies a SIP endpoint to dial. Queue The `` noun allows you to add a call to a queue. ## Number 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 `` and `` 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 sendDigits Specifies DTMF tones to play when the call is answered. The value can include: digits 0-9, #, *, and w. 'w' indicates a 0.5 second pause. - machineDetection Enables Answering Machine Detection. Note: add amd event type to statusCallbackEvent list to receive the detection result webhook. Enable, DetectMessageEnd, Disable Disable detectionMode Sets the Answering Machine Detection mode. Use PremiumCallScreening for premium iOS call screening detection. See https://developers.telnyx.com/docs/voice/programmable-voice/answering-machine-detection Regular, Premium, PremiumCallScreening Regular machineDetectionTimeout Maximum timeout threshold for overall detection, in milliseconds. 500 - 60000 3500 machineDetectionPromptEndTimeout Silence duration threshold after a call screening prompt before ending prompt detection, in milliseconds. Only used when machineDetection is enabled and detectionMode is PremiumCallScreening. 1000 - 120000 - ## Sip Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT username Username to use for SIP authentication. - password Password to use for SIP authentication. - 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 `` and `` 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, DetectMessageEnd, Disable Disable detectionMode Sets the Answering Machine Detection mode. Use PremiumCallScreening for premium iOS call screening detection. See https://developers.telnyx.com/docs/voice/programmable-voice/answering-machine-detection Regular, Premium, PremiumCallScreening Regular machineDetectionTimeout Maximum timeout threshold for overall detection, in milliseconds. 500 - 60000 3500 machineDetectionPromptEndTimeout Silence duration threshold after a call screening prompt before ending prompt detection, in milliseconds. Only used when machineDetection is enabled and detectionMode is PremiumCallScreening. 1000 - 120000 - ## Queue Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT url Optional URL to another TeXML document that can contain ``, ``, ``, `` and `` verbs. The document will be executed on the queued call before bridging the calls. - method HTTP request type used for url. GET, POST POST ## Simultaneous dialing You can use multiple `` and `` nouns within a `` 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 +18775551212 sip:connection@sip.telnyx.com +18771234567 ``` ## Sequential dialing Set `sequential="true"` to dial multiple `` and `` nouns one at a time in the order listed. Telnyx attempts the next destination only if the current attempt completes without being answered. If a destination answers, it is connected to the caller and the remaining destinations are not dialed. ```xml +18775551212 sip:connection@sip.telnyx.com +18771234567 ``` ## Examples ```xml +19999999999 ``` ```xml +19999999999 ``` ```xml sip:connection@sip.telnyx.com ``` ```xml +19999999999 ``` ```xml +19999999999 ``` ```xml +19999999999 ``` ```xml +19999999999 ``` ## Expected callbacks If `action` is set, a callback is sent when the dialed call ends. See [Dial Action Callback](/api-reference/callbacks/texml-call-completed) for the full payload reference. The `error_code` and `error_message` fields are provided only in case of failed calls. The full list of errors can be found under the [API Errors](/development/api-fundamentals/api-errors/index) page. If `statusCallbackEvent` is set, the following webhooks are sent based on configured events: | Event | Callback Reference | |-------|-------------------| | `initiated` | [Call Initiated](/api-reference/callbacks/texml-call-initiated) | | `ringing` | [Call Ringing](/api-reference/callbacks/texml-call-ringing) | | `answered` | [Call Answered](/api-reference/callbacks/texml-call-answered) | | `completed` | [Call Completed](/api-reference/callbacks/texml-call-completed) | If `machineDetection` is enabled, an AMD callback is sent to `amdStatusCallback`. See [AMD Callback](/api-reference/callbacks/texml-call-amd) for the full payload reference. If `deepfakeDetection` is set to `Enable`, a deepfake detection callback is sent to `deepfakeDetectionCallbackUrl` (or to `statusCallback` if `"deepfake"` is included in `statusCallbackEvent`). The callback payload includes `DeepfakeResult` (`real`, `fake`, or `silence_timeout`), `DeepfakeScore` (0.0–1.0), and `DeepfakeConsistency` (0–100). On detection failure, a `DeepfakeError` field is sent instead. If `recordingStatusCallbackEvent` is set, the following webhooks are sent: | Event | Callback Reference | |-------|-------------------| | `in-progress` | [Recording In Progress](/api-reference/callbacks/texml-recording-in-progress) | | `completed` | [Recording Completed](/api-reference/callbacks/texml-recording-completed) | --- ### Say > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/say.md The `` verb speaks the text specified back to the caller, enabling text-to-speech for any application. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT voice Optional text-to-speech voice type. For basic text-to-speech use man or woman (en-US only). For premium text-to-speech use alice or one of the following provider-prefixed formats: Polly.VoiceId / Polly.VoiceId-Neural for Amazon Polly, AWS.Polly.VoiceId for direct AWS Polly notation, Azure.VoiceId for Azure TTS (supports gender and effect attributes), ElevenLabs.ModelId.VoiceId for ElevenLabs (requires api_key_ref), Telnyx.ModelId.VoiceId for Telnyx native TTS, Resemble.ModelId.VoiceId for Resemble AI, Minimax.ModelId.VoiceId for Minimax, Rime.ModelId.VoiceId for Rime, and Inworld.ModelId.VoiceId for Inworld. man, woman, alice, Polly.VoiceId, Polly.VoiceId-Neural, AWS.Polly.VoiceId, Azure.VoiceId, ElevenLabs.ModelId.VoiceId, Telnyx.ModelId.VoiceId, Resemble.ModelId.VoiceId, Minimax.ModelId.VoiceId, Rime.ModelId.VoiceId, Inworld.ModelId.VoiceId 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. This parameter is ignored when a specific Amazon Polly voice is used. - loop The number of times to repeat the text. 0 means infinite. 0 - 10 1 gender Specifies the gender of the voice. Only applicable when using Azure voices (Azure.*). Male, Female - effect Applies an audio effect to the spoken text. Only applicable when using Azure voices (Azure.*). eq_telecomhp8k, eq_car - voiceSpeed Speech rate for the voice. Must be a decimal between 0.1 and 2.0. Defaults to 1. 0.1 - 2.0 1 api_key_ref Reference to the API key for authentication with the TTS provider. The key must be stored via the [integration secrets API](/api-reference/integration-secrets/create-a-secret). Used with ElevenLabs and Azure voices. - region Cloud region to use with the TTS provider. Required for Azure voices when using a custom API key. - pronunciationDictId UUID of a pronunciation dictionary to apply to the spoken text. - languageBoost Language hint for Telnyx Qwen3TTS voices. Accepted as full names (Auto, English, German, Chinese, French, Italian, Japanese, Korean, Portuguese, Russian, Spanish) or ISO 639-1 codes (en, de, zh, fr, it, ja, ko, pt, ru, es). - ## Examples ```xml This is a premium Amazon Polly text-to-speech message! ``` --- ### Play > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/play.md The `` verb plays an MP3 or WAV audio file, which Telnyx fetches back to the caller from the URL you configure. 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. You can also use the `digits` attribute to play DTMF tones instead of an audio file. `` can be used independently as a verb or nested within `` as a noun to play an audio file while waiting for DTMF tones. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT loop Times to repeat the audio 1 mediaStorage When true fetches the file from Telnyx media storage using the provided media name. true, false false digits DTMF tones to play. The value can include digits 0-9, *, #, and w (for a 0.5 second pause). When specified, the verb plays DTMF tones instead of an audio file. - failoverUrl Backup audio source played when the primary URL fails. The `mediaStorage` flag also applies to this URL. Only one retry attempt is made. - continueOnError When true, a playback failure does not abort the script. Telnyx still logs the error and continues with the next verb. false ringTone Plays a country-specific ringback tone instead of an audio file. Cannot be combined with an audio body. Not supported inside ``. 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, tw, ve, za, us, us-old, uk - ## Examples ```xml https://example.com/welcome.mp3 ``` ```xml ``` ```xml https://example.com/might-404.mp3 Sorry, we could not play the message. ``` ```xml https://cdn.example.com/welcome.mp3 ``` --- ### Gather > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/gather.md The `` verb collects DTMF tones during a call. `` can be nested within `` to create an interactive IVR with text-to-speech. ## Attributes 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. - timeout Time in seconds between digits before the `` 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 input The input type for the gather action. dtmf, speech, dtmf speech dtmf speechTimeout Time in seconds to wait after speech ends before timing out. - partialResultCallback URL for sending partial gather results. - partialResultCallbackMethod HTTP request type used for partialResultCallback. GET, POST POST profanityFilter Whether to filter profanity from speech recognition results (camelCase format). - useEnhanced Enables enhanced transcription, this works for models phone_call and video (camelCase format). - hints Hints to improve transcription accuracy. On Deepgram, this maps to the Nova-2 keyword biasing feature and is supported only on `model="deepgram/nova-2"`; it is silently dropped on Nova-3 (use `keyterms` instead). Accepts a comma-separated string. - keyterms Deepgram Nova-3 keyterm prompting. Biases recognition toward domain-specific terms or brand names. Supported only on `model="deepgram/nova-3"`; silently dropped on Nova-2 (use `hints` instead). Accepts a comma-separated string. - smartFormat Disable Deepgram's smart formatting so the transcript stays lowercase with no punctuation. Deepgram-only; silently dropped on other engines. true transcriptionEngine Engine to use for speech recognition: Google, Telnyx, Azure, Deepgram, xAI, AssemblyAI, Soniox, Speechmatics Google, Telnyx, Azure, Deepgram, xAI, AssemblyAI, Soniox, Speechmatics - model Speech recognition model. Format is `vendor/model-name` — e.g. `deepgram/nova-2`, `deepgram/nova-3`, `azure/fast`, `assemblyai/universal-streaming`, `soniox/stt-rt-v4`, `speechmatics/standard`, `xai/grok-stt`. The vendor must match `transcriptionEngine`. On Deepgram, defaults to `deepgram/nova-3` when unset. - apiKeyRef Reference to the API key for authentication. See [integration secrets documentation](/api-reference/integration-secrets/create-a-secret) for details. The parameter is optional as defaults are available for some regions. Used with Azure transcriptionEngine. - region Region to use with the specified transcription engine. Required for Azure. See regions in [transcription_engine_config](/api-reference/call-commands/transcription-start). - finishOnKey The set of digits, (0-9, *, #), that indicates the end of the gather. # numDigits The number of digits to be gathered. - language The language used. See RESTful API documentation for supported values. By default en-US. en-US 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. - minDigits Minimum number of digits to be gathered. 1 - 128 1 maxDigits Maximum number of digits to be gathered. 1 - 128 128 ## Child verbs/nouns NOUN/VERB DESCRIPTION Say Play ## Examples ```xml Press 1 for sales, press 2 for support. ``` ## Expected callbacks If `action` is set, a callback is sent when gather completes with the collected digits or speech. See [Gather Callback](/api-reference/callbacks/texml-gather) for the full payload reference. --- ### AIGather > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/aigather.md The `` verb collects specific information from call participants leveraging AI. It requires the child node `` to be provided with a JSON Schema object that describes the parameters to be gathered. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT action URL where TeXML will send the gathered speech input. The same method (GET/POST) as set for the TeXML application is used. Transfers control of the current call to the TeXML file returned. - method HTTP request type used to retrieve the next set of instructions. GET, POST POST ## Child verbs/nouns NOUN/VERB 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 described as a JSON Schema object that needs to be gathered by the voice assistant. It needs to be provided within CDATA tags (see the example below). 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. They can be provided as a list of `` nodes. Each `` 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 `` node (see the example below). Tools The list of `` to be used by the AI assistant. The `` should contain at tool definition in json format. All of the available tools are defined in the [Voice API Gather using AI documentation](/api-reference/call-commands/gather-using-ai). ## Voice Attributes 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.NaturalHD.Astra 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 0.1 - 2.0 1 ## Examples ```xml Hello my name is Enzo. ``` ## Expected callbacks If `action` is set, a callback is sent when the AI gather completes with the collected result and message history. See [AI Gather Callback](/api-reference/callbacks/texml-ai-gather) for the full payload reference. --- ### AIAssistant > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/aiassistant.md The `` verb allows you to start a voice assistant on the call. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT id The identifier of the AI assistant. The AI assistant can be created using the [AI Assistant API](/api-reference/assistants/create-an-assistant). - join The ID of an existing AI assistant conversation to join. When set, the call leg is added as a participant to the specified conversation instead of starting a new one. Use `participantName` and `participantRole` to configure the joining participant. - participantName The display name of the participant joining the conversation. Only used when `join` is set. - participantRole The role of the participant joining the conversation. Only used when `join` is set. user, assistant user ## Examples ```xml ``` ```xml ``` --- ### Record > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/record.md The `` 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 **Note** In addition to recording, the `` verb supports automatic transcription by setting `transcription="true"` and providing a `transcriptionCallback` URL. The transcription result will be sent via webhook. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT action Optional URL where TeXML will make a request 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. Supported characters values: Any digit, #, *. 1234567890*# 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. 0 for infinite. 0 maxLength Defines the maximum length for the recording in seconds. 0 for infinite. 0 - 14400 3600 playBeep Whether or not a sound is played before the start of a recording. true trim Will remove silence from the beginning and end of the recording when set to trim-silence. trim-silence - 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. single, dual 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 transcription Enables automatic transcription of the recorded audio. When set to 'true', a transcription will be generated and delivered to the transcriptionCallback URL. true, false false transcriptionCallback The URL where Telnyx will send the transcription result once available. - transcriptionEngine Specifies the engine to use for transcription. A, B A transcriptionLanguage Language to use for transcription when transcription is enabled. en-US format The format of the recording file. mp3, wav mp3 recordingStatusCallbackEvent The recording events for which Telnyx should send a webhook to the recordingStatusCallback URL. Multiple events are separated by a space. in-progress, completed completed ## Examples Example 1 ```xml ``` Example 2 ```xml This call will be recorded and transcribed for quality purposes. ``` ## Expected callbacks If `action` or `statusCallback` is set, recording status callbacks are sent: | Event | Callback Reference | |-------|-------------------| | `in-progress` | [Recording In Progress](/api-reference/callbacks/texml-recording-in-progress) | | `completed` | [Recording Completed](/api-reference/callbacks/texml-recording-completed) | If `transcribe` is enabled, a transcription callback is sent to `transcribeCallback`: See [Transcription Callback](/api-reference/callbacks/texml-transcription) for the full payload reference. --- ### Conference > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/conference.md The `` verb's `` noun allows you to connect to a conference room. Much like how the `` noun allows you to connect to another phone number, the `` 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. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT muted Specify whether a participant is muted or not. 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 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. false maxParticipants The maximum number of participants allowed in the conference. 2 - 250 250 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. Note: this attribute does not affect the recording start beep. To disable the beep played when recording starts, set the recordBeep attribute to false. true, false, onEnter, onExit true participantLabel A unique label for the participant which will be added into the conference as a result of executing the TeXML instruction. The label can be used to read or update participant attributes using the TeXML REST API. - record The record attribute lets you record entire conference. When set to record-from-start, recording begins immediately after the conference starts do-not-record, record-from-start do-not-record recordBeep If enabled, a beep sound will be played at the start of a recording. This is independent of the beep attribute, which only controls join/leave notification sounds. Set to false to disable the recording start beep. 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. 0 means no timeout. 0 - 14400 0 trim Whether to trim any leading and trailing silence from the recording. trim-silence, do-not-trim do-not-trim sendRecordingUrl Defines if the recording URL is sent in the callbacks. true statusCallback A URL for Telnyx to send webhook requests to on each event specified in the statusCallbackEvent attribute. - statusCallbackMethod HTTP method to use when requesting the status callback URL. GET, POST POST statusCallbackEvent The conference events for which Telnyx should send a webhook on. Multiple events are separated by a space. start, end, join, leave, speaker - 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. - waitMethod HTTP method to use when requesting the wait URL. GET, POST POST ## Examples ```xml conference_name ``` ## Expected callbacks If `statusCallbackEvent` is set, the following webhooks are sent based on configured events: | Event | Callback Reference | |-------|-------------------| | `start` | [Conference Start](/api-reference/callbacks/texml-conference-start) | | `end` | [Conference End](/api-reference/callbacks/texml-conference-end) | | `join` | [Participant Join](/api-reference/callbacks/texml-conference-join) | | `leave` | [Participant Leave](/api-reference/callbacks/texml-conference-leave) | | `speaker` | [Participant Speaker](/api-reference/callbacks/texml-conference-speaker) | --- ### Enqueue > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/enqueue.md The `` verb enqueues the current call in a call queue. ## 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 `` verb. When a call is dequeued using `` verb, the request will be sent once the bridged calls disconnect. - method HTTP request type used for action. GET, POST POST 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: ``, ``, ``, ``, ``, ``, ``. - waitUrlMethod HTTP request type used for waitUrl. GET, POST POST maxWaitTimeSecs Maximum time in seconds a call can stay in the queue. If the call is not dequeued within this time, it will be removed from the queue and the action URL will be called. Must be at least 1 second. 14400 ## Examples ```xml ``` ## Expected callbacks If `waitUrl` is set, a callback is sent when the call enters the queue. See [Queue Callback](/api-reference/callbacks/texml-queue) for the full payload reference. --- ### Hangup > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/hangup.md Ends the call ## Examples ```xml ``` ## Expected callbacks When the call ends, a callback is sent to the webhook URL defined on the connection level with `CallStatus` set to `completed`. See [Call Completed Callback](/api-reference/callbacks/texml-call-completed) for the full payload reference. --- ### Pause > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/pause.md The `` verb waits silently for a specified number of seconds or one second by default. No nouns can be nested within ``, and a self-closing tag must be used. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT length Seconds to pause 1 - 180 1 ## Examples ```xml ``` --- ### Redirect > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/redirect.md The `` verb transfers control of a call to the TeXML document to another TeXML application. This is useful to create a tree structure of TeXML files for different applications. No nouns can be nested within `` ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT method The type of requested used `` URL. GET, POST POST ## Examples ```xml https://example.com/next-instructions ``` --- ### Reject > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/reject.md The `` 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 `` verb. If placed as the very first verb in an incoming call, `` 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 `` and you can't nest `` in any other verbs. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT reason The tone to play to indicate the reason the call was rejected. rejected, busy rejected ## Examples ```xml ``` --- ### Stream > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/stream.md The `` instruction starts streaming the media from a call to a specific WebSocket address in near-real-time. Audio will be delivered as base64-encoded RTP payloads (no headers), wrapped in JSON payloads. ## 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 - codec Specifies the codec to be used for the streamed audio. When set to 'default' or when transcoding is not possible, the codec from the call will be used. Currently, transcoding is only supported between PCMU and PCMA codecs. PCMU, PCMA, G722, OPUS, AMR-WB, default default bidirectionalMode Bidirectional streaming mode mp3, rtp mp3 bidirectionalCodec Bidirectional streaming codec, used only with bidirectionalMode=rtp PCMU, PCMA, G722, OPUS, AMR-WB PCMU bidirectionalSamplingRate Bidirectional streaming sampling rate in Hz 8000, 16000, 24000 8000 statusCallback A URL for Telnyx to send webhook requests to on stream status events (e.g. stream started, stopped, or failed). - statusCallbackMethod HTTP request type used for statusCallback. GET, POST POST enableReconnect Whether the platform should automatically attempt to reconnect the WebSocket stream if disconnected. Defaults to `true`. true ## Child verbs/nouns NOUN/VERB DESCRIPTION Parameter Custom key-value parameter to pass to the WebSocket server. Parameters are included in the `start` message sent over the WebSocket connection. ## Parameter Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT name The name of the custom parameter. - value The value of the custom parameter. - ## Examples ```xml ``` ```xml ``` ### Disabling automatic reconnection By default, `enableReconnect` is `"true"`, and the platform will automatically attempt to reconnect the WebSocket stream if it is disconnected. Set `enableReconnect="false"` to disable this behavior, for example when a disconnection should immediately end the stream. ```xml ``` ## Expected callbacks If `statusCallback` is set, stream status callbacks are sent for the following events: - `stream-started` — Stream has started - `stream-stopped` — Stream has stopped - `stream-failed` — Stream failed to start or was interrupted See [Stream Callback](/api-reference/callbacks/texml-stream) for the full payload reference. --- ### ConversationRelay > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/conversationrelay.md The `` verb routes a call to a ConversationRelay service that provides voice interactions over a WebSocket connection. It provides speech-to-text transcription and allows requesting text-to-speech synthesis for the call over WebSocket. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT url The WebSocket URL of the conversation relay server. - welcomeGreeting A greeting message to be spoken when the conversation relay session starts. - voice The TTS voice to use (e.g., `Telnyx.Natural.abbie`, `Telnyx.NaturalHD.astra`). - language The language for TTS and transcription (e.g., `en`, `fr`, `es`). - transcriptionProvider The speech-to-text provider (e.g., `deepgram`). - interruptible Whether TTS playback can be interrupted by the caller. `true` is an alias for `any`, `false` is an alias for `none`. none, any, speech, dtmf, true, false any welcomeGreetingInterruptible Whether the welcome greeting can be interrupted by the caller. `true` is an alias for `any`, `false` is an alias for `none`. none, any, speech, dtmf, true, false any dtmfDetection Whether to enable DTMF detection during the conversation relay session. false ## Child verbs/nouns NOUN/VERB DESCRIPTION Language Configures a supported language with optional per-language voice and provider settings. Multiple `` elements can be specified to enable multilingual conversations. Parameter Custom key-value parameter passed to the WebSocket server as assistant dynamic variables. ## Language Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT code The language code (e.g., `en`, `fr`, `es`). - ttsProvider The text-to-speech provider to use for this language (e.g., `telnyx`, `google`). - voice The voice to use for this language. - transcriptionProvider The speech-to-text provider to use for this language (e.g., `google`, `telnyx`, `deepgram`). - speechModel The speech recognition model to use for this language (e.g., `nova-2`). - ## Parameter Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT name The name of the custom parameter. - value The value of the custom parameter. - ## Examples ### Basic usage with greeting and voice ```xml ``` ### Multilingual with DTMF language selection ```xml ``` ### Custom parameters Custom parameters are passed to the WebSocket server as assistant dynamic variables. ```xml ``` ### Non-interruptible greeting Use `welcomeGreetingInterruptible="none"` to ensure the greeting plays fully before accepting input. ```xml ``` --- ### Connect > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/connect.md The `` verb starts the service defined in the nested noun in synchronous mode. The following instructions will be executed when the service is stopped. ## Child verbs/nouns NOUN/VERB DESCRIPTION Stream Start media stream over websocket. See the [Stream documentation](/docs/voice/programmable-voice/texml-verbs/stream) for more information. ConversationRelay Route a call to a ConversationRelay service that provides voice interactions over a WebSocket connection. See the [ConversationRelay documentation](/docs/voice/programmable-voice/texml-verbs/conversationrelay) for more information. --- ### HttpRequest > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/httprequest.md The `` verb sends a request to the external servers. It consists of 2 child nodes `` and `` ## Attributes 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 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) - ## Child verbs/nouns NOUN/VERB DESCRIPTION Request The `` node defines all the attributes of the request. It can have 2 child nodes `` and `` Response The `` node defines all the attributes of the response. It can have 2 child nodes `` and `` ## Examples ```xml Authorization Bearer API_key Content-Type application/json ``` ```xml ... JSON 200 contact.name.first first_name contact.name.last last_name ``` ## Expected callbacks When the HTTP request completes, a callback is sent to the `action` URL. See [HTTP Request Callback](/api-reference/callbacks/texml-http-request) for the full payload reference. --- ### Leave > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/leave.md The `` verb removes a call from the queue and continues with the next verb after the original ``. The `` verb doesn't support any attributes. ## Examples ```xml ``` --- ### Refer > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/refer.md The `` 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 `` verb, Telnyx will replace the original call with a new call to the external system you specify, effectively transferring the call to that system. ## Attributes 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 ## Examples ```xml sip:john@example.com ``` ## Expected callbacks If `action` is set, a callback is sent when the `` verb finishes. See [Refer Status Callback](/api-reference/callbacks/texml-refer-status) for the full payload reference. --- ### Siprec > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/siprec.md The `` instruction starts the SIPREC session on the given call. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT connectorName Specifies which pre-configured external connector shall be used for this request. - statusCallback A URL for Telnyx to send webhook requests to on each event related to siprec session. - 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 name Name of the SIPREC session. It can be used to stop the session. - includeMetadataCustomHeaders Controls whether custom parameters are added as metadata, if false, they are added to sip headers. 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. false sessionTimeoutSecs Sets Session-Expires header to the INVITE. A reinvite is sent every half the value set. Useful for session keep alive. Minimum value is 90, set to 0 to disable. 90 - 14440 1800 ## Examples ```xml ``` ```xml ``` ## Expected callbacks If `statusCallback` is set, SIPREC status callbacks are sent for the following events: - `siprec-started` — SIPREC session has started - `siprec-stopped` — SIPREC session has stopped - `siprec-failed` — SIPREC session failed to start See [SIPREC Callback](/api-reference/callbacks/texml-siprec) for the full payload reference. --- ### Start > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/start.md The `` verb starts the service defined in the nested noun. As soon as the service is started, the next TeXML instructions will be executed from the provided instructions. ## Child verbs/nouns NOUN/VERB DESCRIPTION Suppression Start noise suppression. See the [Suppression documentation](/docs/voice/programmable-voice/texml-verbs/suppression) for more information. Transcription Start transcription. See the [Transcription documentation](/docs/voice/programmable-voice/texml-verbs/transcription) for more information. Stream Start media stream over websocket. See the [Stream documentation](/docs/voice/programmable-voice/texml-verbs/stream) for more information. --- ### Stop > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/stop.md The `` verb stops the instruction specified by noun on a call. ## Child verbs/nouns NOUN/VERB DESCRIPTION Suppression Stops current suppression, no attributes need to be provided. Transcription Stops current transcription, no attributes need to be provided. Stream Stops current media stream, no attributes need to be provided. ## Examples ```xml ``` --- ### Suppression > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/suppression.md The `` instruction starts noise suppression on the call to improve audio quality. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT direction Specifies which side of the audio shall be denoised. inbound, outbound, both inbound ## Examples ```xml ``` --- ### Transcription > Source: https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/transcription.md The `` verb enables real-time speech-to-text transcription for the call. ## Attributes ATTRIBUTE DESCRIPTION OPTIONS DEFAULT language Language to use for speech recognition. See languages in [transcription_engine_config](/api-reference/call-commands/transcription-start). en interimResults Whether to send also interim results. If set to false, only final results will be sent. Applies to transcriptionEngine A only. false transcriptionEngine Engine to use for speech recognition. Available engines: Google (default), Telnyx, Deepgram, Azure, xAI, AssemblyAI, Soniox, Speechmatics. Each engine supports different models and languages - see model attribute and examples below. Legacy values "A" (maps to Google) and "B" (maps to Telnyx) are supported for backward compatibility. Google, Telnyx, Deepgram, Azure, xAI, AssemblyAI, Soniox, Speechmatics, A, B Google 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 model Optional model to use with the specified transcription engine. Format is `vendor/model-name` — e.g. `deepgram/nova-2`, `deepgram/nova-3`, `azure/fast`, `assemblyai/universal-streaming`, `soniox/stt-rt-v4`, `speechmatics/standard`, `xai/grok-stt`. The vendor must match `transcriptionEngine`. If not specified, the engine's default model will be used. On Deepgram, defaults to `deepgram/nova-3`. See transcription models in [transcription_engine_config](/api-reference/call-commands/transcription-start). - hints Hints to improve transcription accuracy. On Deepgram, this maps to the Nova-2 keyword biasing feature and is supported only on `model="deepgram/nova-2"`; it is silently dropped on Nova-3 (use `keyterms` instead). Accepts a comma-separated string. - keyterms Deepgram Nova-3 keyterm prompting. Biases recognition toward domain-specific terms or brand names. Supported only on `model="deepgram/nova-3"`; silently dropped on Nova-2 (use `hints` instead). Accepts a comma-separated string. - smartFormat Disable Deepgram's smart formatting so the transcript stays lowercase with no punctuation. Deepgram-only; silently dropped on other engines. true apiKeyRef Reference to the API key for authentication. See [integration secrets documentation](/api-reference/integration-secrets/create-a-secret) for details. The parameter is optional as defaults are available for some regions. - region Region to use with the specified transcription engine. Required for Azure. See regions in [transcription_engine_config](/api-reference/call-commands/transcription-start). - ## Examples **Example 1: Basic transcription using Google (default)** ```xml ``` **Example 2: Google with phone call optimized model** ```xml ``` **Example 3: Telnyx engine with Whisper model** ```xml ``` **Example 4: Deepgram with Nova-3 model** ```xml ``` **Example 5: Azure with Fast model and credentials** ```xml ``` **Example 6: Azure with Realtime model** ```xml ``` ## Expected callbacks If `transcriptionCallback` is set, transcription results are sent as they become available. See [Transcription Callback](/api-reference/callbacks/texml-transcription) for the full payload reference. --- ## API Reference ### Applications > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/applications.md A TeXML application defines how inbound and outbound calls are handled using TeXML instructions. Each TeXML application instance encapsulates a set of configuration parameters that control call behavior, instruction retrieval, and webhook interactions. These parameters determine where Telnyx fetches TeXML from, how call events are handled, and how call flows are executed. More details: [Applications](https://developers.telnyx.com/docs/voice/programmable-voice/texml-fundamentals/index#texml-application) --- ### Calls > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/calls.md A call object represents a single call leg. It contains all state, metadata, and lifecycle information of that call leg. ## Creating calls A call object is instantiated in the following situations: 1\. When an outbound call is initiated through the [REST API](https://developers.telnyx.com/api-reference/texml-rest-commands/initiate-an-outbound-call). Telnyx immediately creates a call resource to represent this outbound call. 2\. When an inbound call reaches a phone number assigned to a TeXML application. * Before processing any TeXML, a call resource is created to represent the inbound call itself. * At that point, the call is answered and the instruction fetch request is sent. The lifecycle of this inbound call is driven by the instructions defined in the TeXML response. 3\. When a [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/dial) verb is executed inside a TeXML script. Each execution of `` creates a new call resource. This call is logically associated with the parent call that initiated the TeXML request, and Telnyx manages both calls as part of a multi-leg call flow if needed. ## Fetching call details The details of the call can be retrieved using [the calls endpoint](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-a-call) up to 30 days after the call has ended. --- ### Conferences > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/conferences.md A conference object represents a multi-participant audio session. ## Creating conference A conference is instantiated in the following way: 1\. When a `` to a non-existent `` is executed Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/conference) 2\. When Telnyx processes a TeXML response that includes a `` verb with a `` noun, it attempts to place the current call into a named conference. Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/dial) ## Managing Existing Conferences Once instantiated, conferences can be managed via REST API endpoints, including: - [Fetch a conference resource](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-a-conference-resource) - [List all conferences](https://developers.telnyx.com/api-reference/texml-rest-commands/list-conference-resources) - [Update a conference](https://developers.telnyx.com/api-reference/texml-rest-commands/update-a-conference-resource) - [List associated recordings](https://developers.telnyx.com/api-reference/texml-rest-commands/list-conference-recordings) --- ### Conference participants > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/conference-participants.md A conference participant object represents an individual call leg that has been added to a conference. ## Creating a conference participant A conference participant is instantiated in the following situations: 1\. When a new participant is dialed and added to a conference via the REST API API reference: [dial-a-new-conference-participant](https://developers.telnyx.com/api-reference/texml-rest-commands/dial-a-new-conference-participant). When your application requests to dial a new party into an existing conference using the REST API, a conference participant resource for the new call leg is created. 2\. When a call leg is added to a conference via `` with `` in TeXML Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/conference) When a TeXML `` verb that contains a `` element is executed, the call leg joins the specified conference. At that point, Telnyx creates a conference participant object associated with that call leg. ## When Participant API Responses Return No Results Certain situations cause the participant API to return no participant records, even if the call or conference previously existed. Telnyx will return no participant objects under the following conditions: 1\. The conference has been completed Once a conference ends (e.g., all participants disconnect or the session is terminated), Telnyx no longer returns participant objects associated with that completed conference. 2\. A participant’s call leg is no longer active (i.e., has been hung up) If a participant disconnects - whether intentionally, due to call failure, or because of application logic - their call leg is considered complete, and the participant object is no longer returned by the API. 3\. The participant has been explicitly removed via the REST API API reference: [delete-a-conference-participant](https://developers.telnyx.com/api-reference/texml-rest-commands/delete-a-conference-participant) 4\. The participant’s call leg has been given new TeXML instructions via the REST API API reference: [update-call](https://developers.telnyx.com/api-reference/texml-rest-commands/update-call) If a call leg that was previously in a conference is updated with new TeXML instructions via the REST API, it effectively leaves the conference context. As a result, it is no longer included in participant API responses. --- ### Recordings > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/recordings.md A recording object represents an audio recording generated during a call or conference using TeXML application. Recording objects track metadata such as format, duration, start and end times, and storage locations. ## Creating recording A recording can be created in the following situations: 1\. When an outbound call is initiated with record enabled via the REST API API reference: [Initiate an outbound call](https://developers.telnyx.com/api-reference/texml-rest-commands/initiate-an-outbound-call) If your application initiates an outbound call and specifies the record attribute, Telnyx automatically begins recording the call when it is answered. 2\. When a `` verb is executed in a TeXML script Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/record) Whenever a `` verb is encountered in a TeXML response, Telnyx initiates audio capture for the call leg that executed the verb. Each execution produces a distinct recording object that captures the audio during the `` period 3\. When a `` verb is executed with record attributes enabled Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/dial) If a `` verb includes recording parameters (e.g., to record the outbound leg created by the dial), Telnyx begins recording as soon as that outbound call leg is created. 4\. When a `` to `` is executed with record attributes Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/conference) When a `` connects a call into a `` and recording attributes are provided, Telnyx initiates conference recording. 5\. When recording is started manually via the REST API API reference: [Request recording for a call](https://developers.telnyx.com/api-reference/texml-rest-commands/request-recording-for-a-call) The recording may be triggered dynamically on any existing call by making a request to the start recording endpoint. When the request is executed, Telnyx creates a new recording object associated with that ongoing call. 6\. When a conference participant is dialed and joined via the REST API with recording enabled API reference: [Dial a new conference participant](https://developers.telnyx.com/api-reference/texml-rest-commands/dial-a-new-conference-participant) If a new participant is added to a conference using the REST API and recording is enabled for that action, Telnyx begins capturing audio for the participant or the entire conference session. ## Fetching Recordings Recording objects can be retrieved through several query paths depending on how the recording was initiated: 1\. By Recording ID - [API reference](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-recording-resource) 2\. By Conference ID - [API reference](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-recordings-for-a-conference) 3\. By Call ID - [API reference](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-recordings-for-a-call) ## Controlling Ongoing Recordings Once recording is active, your application can manage or modify the recording session using the REST API: 1\. Update or stop an ongoing recording on a call - [API reference](https://developers.telnyx.com/api-reference/texml-rest-commands/update-recording-on-a-call) --- ### Transcripts > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/transcripts.md ## Transcription Creation A transcription can be enabled from TeXML in 2 scenarios: 1\. When a `` verb is executed in TeXML Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/transcription) When Telnyx processes a TeXML document containing the `` verb, it initiates an audio capture operation based on the parameters defined in that verb. Once the audio is captured and processed, a transcription is provided in statuscallbacks in real-time. 2\. When a `` verb is executed with transcription attributes Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/record) If a TeXML `` verb includes transcription-related attributes, Telnyx performs transcription on the recorded audio once the recording is complete. ## Retrieving recording transcription Upon completion of the transcription process, a transcription object representing the text output associated with that recording segment is created and can be retrieved using the following endpoint: [Fetch a recording transcription resource](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-a-recording-transcription-resource) --- ### SIPREC > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/siprec.md A SIPREC session represents an active SIP Client Recording (SIPREC) media session associated with a call. SIPREC sessions enable the delivery of call media to an external SIP recording server for compliance recording, monitoring, or archival purposes. Each SIPREC session object encapsulates the configuration, state, and lifecycle of a single recording session tied to a call. In order to use SIPREC, the SIPREC client connectors must be configured in your Telnyx account. See [SIPREC client tutorial](https://developers.telnyx.com/docs/voice/programmable-voice/siprec-client) for more information. ## Creating SIPREC session A SIPREC session can be started in the following ways: 1\. Starting a SIPREC session via the REST API API reference: [Request a SIPREC session for a call](https://developers.telnyx.com/api-reference/texml-rest-commands/request-siprec-session-for-a-call) Using the REST API, an application can explicitly request the initiation of a SIPREC session for an active call. When this endpoint is invoked, Telnyx creates a SIPREC session object and begins streaming the call media to the configured SIP recording endpoint according to the supplied parameters. This approach allows SIPREC to be started dynamically at any point during the call lifecycle. 2\. Starting a SIPREC session via the TeXML `` verb Documentation: [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/siprec) The SIPREC session is initiated synchronously (nested to `` verb) as part of the sequential TeXML execution flow. Subsequent TeXML instructions are processed only after the SIPREC session has been stopped. ## Managing and Stopping a SIPREC Session Once a SIPREC session has been started—either via the REST API or via TeXML - it can be managed throughout its lifecycle using the REST API. API reference: [Update a SIPREC session for a call](https://developers.telnyx.com/api-reference/texml-rest-commands/updates-siprec-session-for-a-call) This endpoint allows an application to update the state of an active SIPREC session or explicitly stop the recording. --- ### Streams > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/streams.md A stream object represents an active media streaming session originating from a call. Streams allow real-time audio from a call to be delivered to an external destination using WebSockets. Each stream object encapsulates the configuration, state, and lifecycle of a single streaming session associated with a call. ## Creating stream A stream object can be started in the following ways: 1\. Starting a stream via the REST API API reference: [Start streaming media from a call](https://developers.telnyx.com/api-reference/texml-rest-commands/start-streaming-media-from-a-call) Using the REST API, an application can explicitly start streaming media from an active call. When this endpoint is invoked, a stream object is created and audio begins streaming from the specified call according to the provided configuration. This method allows streaming to be initiated dynamically at any point during the call lifecycle. 2\. Starting a stream via the TeXML `` verb Streams can also be initiated as part of TeXML execution using the `` verb, which supports two operational modes: - Asynchronous streaming via `` When the `` verb is nested inside a `` verb, the stream is started asynchronously. In this mode, streaming begins in parallel with the ongoing call flow, allowing audio to be streamed without interrupting or blocking other TeXML instructions. - Synchronous streaming via `` When the `` verb is nested inside a `` verb, streaming is initiated synchronously. In this mode, the call flow waits for the streaming operation to stop before proceeding to the next TeXML instruction. In both cases, execution of the `` verb results in the creation of a stream object associated with the active call. ## Managing and Stopping a Stream Once a stream has been started—whether via the REST API or TeXML—it can be managed throughout its lifecycle using the REST API. 1\.Updating or stopping a stream via the REST API. API reference: [Update streaming on a call](https://developers.telnyx.com/api-reference/texml-rest-commands/update-streaming-on-a-call) When streaming is stopped, the associated stream object transitions to a completed state, and websockets are closed. --- ### Queues > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/queues.md A queue object represents a holding area for calls. Calls in a queue are ordered by the time they were enqueued (First-In-First-Out). ## Creating queues There are two ways to instantiate a new queue: 1\. Using the REST API A queue can be explicitly created by sending a request to the [Create New Queue](https://developers.telnyx.com/api-reference/texml-rest-commands/create-a-new-queue) endpoint. 2\. Using the `` Verb A queue can also be created dynamically during call flow execution. When an [``](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/enqueue) verb is executed inside a TeXML script with a specific queue name, Telnyx checks if a queue with that name already exists. If the queue exists, the call is added to it. If it does not exist, a new queue is automatically created with default settings, and the call is then added. ## Managing queues Once a queue is instantiated, it can be managed using the TeXML REST API. - **[Fetch a Queue](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-a-queue-resource)** Get detailed information about a specific queue by its Queue SID or name. This returns the current state, including the number of calls currently waiting (current size), the average wait time, and the maximum size configuration. - **[Update a Queue](https://developers.telnyx.com/api-reference/texml-rest-commands/update-a-queue-resource)** Modify the properties of an existing queue. For example, you can change the maximum number of allowed calls (max size) to prevent overloading the system. - **[Delete a Queue](https://developers.telnyx.com/api-reference/texml-rest-commands/delete-a-queue-resource)** Remove a queue from your account. --- ### TeXML application secrets > Source: https://developers.telnyx.com/docs/voice/texml/rest-api/secrets.md The TeXML Secrets API provides a secure mechanism for storing, managing, and retrieving sensitive information required by your TeXML applications. This includes credentials, API keys, tokens, and other confidential values that should not be hardcoded into TeXML documents or exposed in application source code. See [the tutorial](https://developers.telnyx.com/docs/voice/programmable-voice/texml-sending-http-requests#using-secrets) for more information. ## Creating a Secret The secret can be created using the following endpoint: [Create a TeXML secret](https://developers.telnyx.com/api-reference/texml-rest-commands/create-a-texml-secret) --- ## API Reference (TeXML) ### TeXML Applications - [List all TeXML Applications](https://developers.telnyx.com/api-reference/texml-applications/list-all-texml-applications.md) - [Creates a TeXML Application](https://developers.telnyx.com/api-reference/texml-applications/creates-a-texml-application.md) - [Retrieve a TeXML Application](https://developers.telnyx.com/api-reference/texml-applications/retrieve-a-texml-application.md) - [Update a TeXML Application](https://developers.telnyx.com/api-reference/texml-applications/update-a-texml-application.md) - [Deletes a TeXML Application](https://developers.telnyx.com/api-reference/texml-applications/deletes-a-texml-application.md) ### TeXML REST Commands - [Fetch multiple call resources](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-multiple-call-resources.md) - [Initiate an outbound call](https://developers.telnyx.com/api-reference/texml-rest-commands/initiate-an-outbound-call.md) - [Fetch a call](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-a-call.md) - [Update call](https://developers.telnyx.com/api-reference/texml-rest-commands/update-call.md) - [Initiate an outbound AI call](https://developers.telnyx.com/api-reference/texml-rest-commands/initiate-an-outbound-ai-call.md) - [List conference resources](https://developers.telnyx.com/api-reference/texml-rest-commands/list-conference-resources.md) - [Fetch a conference resource](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-a-conference-resource.md) - [Update a conference resource](https://developers.telnyx.com/api-reference/texml-rest-commands/update-a-conference-resource.md) - [List conference participants](https://developers.telnyx.com/api-reference/texml-rest-commands/list-conference-participants.md) - [Dial a new conference participant](https://developers.telnyx.com/api-reference/texml-rest-commands/dial-a-new-conference-participant.md) - [Get conference participant resource](https://developers.telnyx.com/api-reference/texml-rest-commands/get-conference-participant-resource.md) - [Update a conference participant](https://developers.telnyx.com/api-reference/texml-rest-commands/update-a-conference-participant.md) - [Delete a conference participant](https://developers.telnyx.com/api-reference/texml-rest-commands/delete-a-conference-participant.md) - [Fetch multiple recording resources](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-multiple-recording-resources.md) - [Fetch recording resource](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-recording-resource.md) - [Delete recording resource](https://developers.telnyx.com/api-reference/texml-rest-commands/delete-recording-resource.md) - [Fetch recordings for a call](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-recordings-for-a-call.md) - [Request recording for a call](https://developers.telnyx.com/api-reference/texml-rest-commands/request-recording-for-a-call.md) - [Update recording on a call](https://developers.telnyx.com/api-reference/texml-rest-commands/update-recording-on-a-call.md) - [List conference recordings](https://developers.telnyx.com/api-reference/texml-rest-commands/list-conference-recordings.md) - [Fetch recordings for a conference](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-recordings-for-a-conference.md) - [List recording transcriptions](https://developers.telnyx.com/api-reference/texml-rest-commands/list-recording-transcriptions.md) - [Fetch a recording transcription resource](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-a-recording-transcription-resource.md) - [Delete a recording transcription](https://developers.telnyx.com/api-reference/texml-rest-commands/delete-a-recording-transcription.md) - [Request siprec session for a call](https://developers.telnyx.com/api-reference/texml-rest-commands/request-siprec-session-for-a-call.md) - [Updates siprec session for a call](https://developers.telnyx.com/api-reference/texml-rest-commands/updates-siprec-session-for-a-call.md) - [Start streaming media from a call.](https://developers.telnyx.com/api-reference/texml-rest-commands/start-streaming-media-from-a-call.md) - [Update streaming on a call](https://developers.telnyx.com/api-reference/texml-rest-commands/update-streaming-on-a-call.md) - [List queue resources](https://developers.telnyx.com/api-reference/texml-rest-commands/list-queue-resources.md) - [Create a new queue](https://developers.telnyx.com/api-reference/texml-rest-commands/create-a-new-queue.md) - [Fetch a queue resource](https://developers.telnyx.com/api-reference/texml-rest-commands/fetch-a-queue-resource.md) - [Update a queue resource](https://developers.telnyx.com/api-reference/texml-rest-commands/update-a-queue-resource.md) - [Delete a queue resource](https://developers.telnyx.com/api-reference/texml-rest-commands/delete-a-queue-resource.md) - [Create a TeXML secret](https://developers.telnyx.com/api-reference/texml-rest-commands/create-a-texml-secret.md) ### Callbacks - [TeXML Call Answered](https://developers.telnyx.com/api-reference/callbacks/texml-call-answered.md) - [TeXML Call Completed](https://developers.telnyx.com/api-reference/callbacks/texml-call-completed.md) - [TeXML Call Initiated](https://developers.telnyx.com/api-reference/callbacks/texml-call-initiated.md) - [TeXML Call Ringing](https://developers.telnyx.com/api-reference/callbacks/texml-call-ringing.md) - [TeXML Call AMD](https://developers.telnyx.com/api-reference/callbacks/texml-call-amd.md) - [TeXML Call DTMF](https://developers.telnyx.com/api-reference/callbacks/texml-call-dtmf.md) - [TeXML Gather](https://developers.telnyx.com/api-reference/callbacks/texml-gather.md) - [TeXML HTTP Request](https://developers.telnyx.com/api-reference/callbacks/texml-http-request.md) - [TeXML AI Gather](https://developers.telnyx.com/api-reference/callbacks/texml-ai-gather.md) - [TeXML Refer Status](https://developers.telnyx.com/api-reference/callbacks/texml-refer-status.md) - [TeXML Conference End](https://developers.telnyx.com/api-reference/callbacks/texml-conference-end.md) - [TeXML Conference Join](https://developers.telnyx.com/api-reference/callbacks/texml-conference-join.md) - [TeXML Conference Leave](https://developers.telnyx.com/api-reference/callbacks/texml-conference-leave.md) - [TeXML Conference Speaker](https://developers.telnyx.com/api-reference/callbacks/texml-conference-speaker.md) - [TeXML Conference Start](https://developers.telnyx.com/api-reference/callbacks/texml-conference-start.md) - [TeXML Recording Completed](https://developers.telnyx.com/api-reference/callbacks/texml-recording-completed.md) - [TeXML Recording In-Progress](https://developers.telnyx.com/api-reference/callbacks/texml-recording-in-progress.md) - [TeXML Transcription](https://developers.telnyx.com/api-reference/callbacks/texml-transcription.md) - [TeXML SIPREC](https://developers.telnyx.com/api-reference/callbacks/texml-siprec.md) - [TeXML Stream](https://developers.telnyx.com/api-reference/callbacks/texml-stream.md) - [TeXML Queue](https://developers.telnyx.com/api-reference/callbacks/texml-queue.md)