TeXML instruction fetching

When a call is being handled by a TeXML application, Telnyx makes HTTP requests to fetch instructions from your application. These requests include specific parameters that provide context about the call, allowing your application to generate appropriate TeXML responses.

Method: Configurable (GET or POST, default is GET) URL: The URL configured for your TeXML application Failover URL: Used if the primary URL is unavailable (optional)

When Telnyx makes a request to fetch TeXML instructions, the following parameters are included always:

Parameter	Description	Example
AccountSid	Your 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
From	The phone number that initiated the call	+13122010091
To	The phone number that received the call	+13122010090
ConnectionId	Telnyx connection ID used for the call	1568109700606592442
ApiVersion	API version in Twilio-compatible format	2010-04-01
CallStatus	Current status of the call	in-progress, ringing, completed

Depending on the call context additional parameters are added to the request. Full list of the parameters can be found on the documentation page foreach of the TeXML verbs

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

Your application should respond with valid TeXML. The response should:

• Be valid XML with a root <Response> element
• Not exceed size limits
• Return HTTP status code 200 OK

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

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Welcome to the Telnyx TeXML service.</Say>
  <Gather timeout="5" numDigits="1">
    <Say>Press 1 to continue.</Say>
  </Gather>
</Response>

When you receive an inbound call to your Telnyx number assigned to TeXML application, the TeXML instruction fetch process begins automatically.

To receive instruction fetch requests for inbound calls, you need to:

1. Create a TeXML Application - Configure a TeXML application in the Telnyx Mission Control Portal or via the API.
2. Configure the Webhook URL - Specify the URL where Telnyx should fetch TeXML instructions when a call is received.
3. Attach a Phone Number - Associate a Telnyx phone number with your TeXML application.

When someone calls the number:

1. Telnyx receives the inbound call
2. Telnyx immediately sends an HTTP request to your configured Webhook URL
3. Your application responds with TeXML instructions
4. Telnyx executes those instructions to handle the call

To initiate outbound calls with TeXML, you will need to use the TeXML Calls API and have your application ready to respond with instructions when the call is answered.

To make outbound calls using TeXML, you need to:

1. Create a TeXML Application - Configure a TeXML application in the Telnyx Mission Control Portal or via the API.
2. Configure the Webhook URL - Specify the URL where Telnyx should fetch TeXML instructions when the call is answered.
3. Use the TeXML Calls API - Make REST API requests to initiate outbound calls.

curl -L 'https://api.telnyx.com/v2/texml/Accounts/:account_sid/Calls' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "To": "+13121230000",
  "From": "+13120001234",
  "Url": "https://www.example.com/texml.xml",
  "StatusCallback": "https://www.example.com/statuscallback-listener"

The process for outbound calls works as follows:

1. Your application makes a request to the Telnyx TeXML Calls REST API
2. Telnyx initiates the outbound call to the specified destination
3. When the call is answered, Telnyx sends an HTTP request to your configured Webhook URL
4. Your application responds with TeXML instructions
5. Telnyx executes those instructions to handle the call

To use SIP trunking connections with TeXML, you can configure your connection to use webhooks and enable the "Park outbound calls" feature:

1. Configure a SIP Trunking Connection - Set up a connection in the Telnyx Mission Control Portal or via the API.
2. Enable TeXML Processing:
   • Set the Webhook API Version to "TeXML"
   • Configure your Webhook URL where Telnyx will fetch TeXML instructions
   • Enable the "Park all outbound calls" option

The "Park all outbound calls" feature park outbound calls initiated through your SIP trunking connection until TeXML instructions are received. This allows you to dynamically control call flow even for calls that originate from your Voice SDK or any other SIP client.

When using SIP trunking with parked outbound calls:

1. The call is initiated using Voice SDK or Sip client
2. Instead of immediately connecting the call, Telnyx "parks" the call (holds it in a waiting state)
3. Telnyx sends an HTTP request to your configured Webhook URL with call details
4. Your application responds with TeXML instructions
5. Telnyx executes those instructions to handle the call

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