Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Setting Up a Server for Twilio Client

Create a TwiML Application

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.

Build a Backend Application Server

You'll need to deploy a server to perform two functions:

  1. Provide a Capability Token to our client application.
  2. 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.

Get the Helper Library

The Twilio Helper Libraries allow you to create capability tokens for your client applications. Follow the instructions for your preferred language to get the helper library installed.

Capability Tokens

Capability tokens allow you to add Twilio capabilities to web and mobile applications without exposing your AuthToken in JavaScript or any other client-side environment. You create a token on your server and specify what capabilities you'd like your device to have. All tokens have a limited lifetime to protect you from abuse. The lifetime is configurable up to 24 hours, but you should make it as short as possible for your application.

        
        
        
        

        For more details, check out our Capability Tokens guide.

        Response TwiML

        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.

              
              
              
              

              Host the Application Server

              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.

              Running Locally Using ngrok

              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.

              ngrok screen

              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:

              https://aaf29606.ngrok.io/token
              

              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:

              eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzY29wZSI6InNjb3BlOmNsaWVudDppbmNvbWluZz9jbGllbnROYW1lPWpvZXkgc2NvcGU6Y2xpZW50Om91dGdvaW5nP2FwcFNpZD1BUFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYJmNsaWVudE5hbWU9am9leSIsImlzcyI6IkFDWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLCJleHAiOjE0NzEzNzIxNjF9.FY547naRvxnDQDpJiAAN5oP5lf606HmIQDUCebUjhXE
              

              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:

              JWT JSON Web Token

              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.

              Test TwiML Generation

              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>
              
              David Prothero Devin Rader
              Rate this page:

              Need some help?

              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.