A TwiML Application is a configuration profile created in the Twilio Console that will be used to specify the Webhook URL that Twilio will use when a connection is made from a Client into Twilio. To create one, visit TwiML Apps in the Console and click 'Create TwiML App'. Enter 'My Client App' (or whatever you prefer) as the app's Friendly Name and click 'Save'.
Don't worry about the Voice and Messaging URLs yet – we'll fill them in shortly.
Once the application is saved, make note of its ApplicationSid (a long string like "APa4983020a0b29fb5db1b1dc68e322fbe"). You'll need this when you're ready to set up the Twilio Client.
You'll need to deploy a server to perform two functions:
- Provide a Capability Token to our client application.
- Serve up TwiML; this instructs Twilio what to do when our client connects to Twilio.
Your server can be built using one of the six Twilio-supported languages: C#, Java, Node.js, PHP, Python, or Ruby.
For more details, check out our Capability Tokens guide.
Finally, your server needs to be able to produce TwiML output that can be used by Twilio to route your connections from your client apps. This may be for allowing outgoing calls to regular phones or client-to-client calls or anything else you can do with TwiML such as conferencing or creating IVRs. Below you can see example code that uses the Twilio Helper Library to generate a TwiML response that simply speaks a greeting.
Now, we need to make this application accessible via the public Internet. Why? Because Twilio's servers (which are connected to the phone network) need to access your server in order to fetch instructions for how your Twilio calls should be handled. This is a standard requirement for any Twilio-powered application. You can do this with any public hosting service such as Heroku, AWS, Azure, Digital Ocean, etc. For testing, however, you can use ngrok to make your local development machine accessible.
First, download ngrok. If your application server is listening for requests on port 3000, for example, you can simply run:
ngrok http -host-header="localhost:3000" 3000
This will create a randomly generated (but publicly accessible!) URL that you provide to Twilio for your TwiML App Voice URL.
The easiest feature to test is the capability token generation. You can simply open up any web browser and request the
/token route and see what comes back from your server. The url you will want to enter will be something like
http://your.server.name/token. For example, if you were running ngrok, as shown in the previous screen shot, the URL would be:
If you request that URL in your browser, you will likely get a file downloaded named
token or perhaps a string of characters shown in the browser window (depending on how your browser handles the
application/jwt content type). The string of characters (whether shown in the browser or in the contents of the downloaded file) will look something like:
This is a JSON Web Token or JWT, for short. You can see the contents of this token by pasting this string into the web site jwt.io:
Within the payload of the token, you will see your application SID, client name, and your Account SID. The token is signed with your Auth Token, which Twilio will use to verify the token.
For TwiML generation, we will want to test the
/voice route, but this time, our handler is expecting a POST request. This is the default request type for most Twilio webhooks. Testing a POST request from a browser isn't as simple, so you will likely want to use a tool like Postman or Fiddler. Or, you can just run
curl from the command line:
curl -X POST https://aaf29606.ngrok.io/voice -d ''
If you are on Windows, you can open PowerShell and run this command:
Invoke-WebRequest -Method POST https://aaf29606.ngrok.io/voice
Be sure to replace
https://aaf29606.ngrok.io/voice with the correct URL for your server application.
You'll know you're successful when you see the following XML output (probably not formatted quite as nicely):
<?xml version="1.0" encoding="UTF-8"?> <Response> <Say>Thanks for calling!</Say> </Response>