TeXML is an XML-based data structure you can use to control calls with Telnyx. TeXML is the quickest way to get started with Call Control using a simple
.xml file, allowing you to specify call instructions in your file using commands called verbs and nouns. TeXML Translator starts at the top of your TeXML file and executes your TeXML commands sequentially in the order they are arranged in the file.
In this guide, you'll learn how to write a simple text to speech TeXML application using Telnyx Call Control in just five lines of code.
First, follow our Quickstart guide to create a Telnyx account and TeXML application, purchase a phone number and assign it to your application.
If you already have an XML call instruction file from another provider, skip to Step 3. TeXML Translator will seamlessly interpret your existing verbs and nouns.
Create an empty standard
.xml file using your preferred editor.
TeXML files contain the following items:
<Response>element -- tag defining the body of the TeXML document
- verb -- an XML tag denoting the action that you want Telnyx to take
- noun -- the item for the action specified in the associated verb
Our TeXML Translator API documentation contains full details of currently supported commands.
In this example, we want to our application to answer incoming calls, play some speech to the caller and hangup so we only need
<?xml version="1.0" encoding="UTF-8"?> <!-- XML file setup above--> <!-- The Response element wraps the body and is required --> <Response> <!-- You don't need to issue an answer command, start with Say for text to speech --> <Say>This is TeXML text to speech setup in seconds! The call will now hangup.</Say> <!-- For this example, you want to hangup the call otherwise there will be silence --> <Hangup /> </Response>
In order to execute your TeXML file, it has to be available via the internet for Telnyx Call Control to execute. Upload the XML file to your own publicly accessible server or use a temporary file storage service such as https://uguu.se/ for this example.
We want our application to read the contents of the TeXML file we just made accessible on the internet, and instruct Telnyx to execute the TeXML commands contained in this file when the number associated with the application receives an inbound call. Here's how to set all that up inside the Mission Control Portal.
In your Telnyx Mission Control Portal account created in Step 1:
- Select "Call Control" on the left-hand side navigation menu and navigate to the TeXML Applications tab.
- Edit the TeXML Application you created in Step 1 by clicking on the pencil ✎ icon next to it.
- For this example, change the Voice Method to
GET, as we want to read the contents of the TeXML file.
- Configure the application to send a TeXML webhook to the URL of the XML file that you made available via the internet in Step 3, by entering the URL of the file in the field marked Send a TeXML Webhook to the URL:.
- Don't worry about the other settings in the TeXML application for now - they won't affect this example.
- Save all changes.
Using your favorite telephony client or your own device, dial the number you purchased in Step 1 which is connected to the TeXML Application we just configured. The call will answer automatically and you should hear your text to speech playing. It's that simple!
- Now that you've successfully configured TeXML to handle an incoming call, check out our video guide showing you how to make an outbound call from your Telnyx number using Telnyx API, and play some text-to-speech when that call is answered using the same TeXML file from this example. Be sure you've set up an Outbound Voice Profile first - double back on our Quickstart guide if you're not sure.
- If you'd prefer to start building with our RESTful API, check out our guide to setting up your development environment. After you're set up, you can learn how to send commands and receive webhooks.
- Built something cool? Why not show it off in our developers Slack community? You can get feedback and recognition from your fellow Telnyx developers, and the engineers who built the API in the first place!