Programmable Voice Quickstart for Twilio Functions

With Twilio Functions you can build Programmable Voice applications without needing to spin-up or operate any web infrastructure. Let's see how it's done!

Receiving an Inbound Phone Call

Purchase a Number

Buy voice-capable Phone Number

Before you can make or receive phone calls, you'll need to sign up for a Twilio account and purchase a voice-capable phone number. When you search for a number to buy, you'll be able to see what types of communication it can power. You can then configure this Phone Number to run a Function every time someone calls in.

Writing a Function

Functions are part of the Twilio Runtime 

Let's write a Function that says "hello world" to anyone who calls your Twilio number. Select Runtime in the product navigation and then click on Functions. You'll see a list of your Functions (if you have any) and a "+" button for creating a new one. Go ahead and create a new Function.

Function Templates

Function Templates

Templates are pre-written code and configuration that help you more quickly build a Twilio application. There are currently several templates built-in to Functions that help you do everything from forwarding an incoming phone call to minting a Sync Access Token. For now, select the "Hello World" Template.

Function Name and Path

Function name and path

Now it's time to build your Function. Make sure your Function has a descriptive name so you can reference it in other parts of the Twilio Console. For now, you can leave it as Hello World. Next, set the path for your Function. The combination of your unique Runtime domain and the path gives you a fully qualified URL that can be used to invoke your Function.

Setting Access and Event Type

Function access and event type

Twilio makes it easy to secure your Functions with a single click. If you only want the Function to run if Twilio is making the HTTP request, check the Access Control checkbox. If you want to be able to curl the Function from your laptop during development, you can uncheck the box. We highly recommend that all Functions that respond to Twilio Webhook Events be secured in production. Next, you can optionally configure which kind of Twilio Webhook Event this Function can handle. This will allow us to warn you if you are configuring your SMS webhook with a Function written for Voice.

Loading Code Samples...
Language
Format:
  • XML
exports.handler = function(context, event, callback) {
  let twiml = new Twilio.twiml.VoiceResponse()
  twiml.say("Hello World")
  callback(null, twiml)
}
<Response>
  <Say>Hello World</Say>
</Response>
Receiving an incoming phone call using Functions
Receiving an incoming phone call using Runtime Functions

Receiving an incoming phone call using Functions

Save your Function

Once it's done being deployed, copy the URL to your Function.

Configuring your Twilio Number

Handling an incoming phone call with a Function

Go to Phone Number and click on the Phone Number that you just purchased. In the Voice section of your Phone Number, set the "Call Comes In" event to your Function's URL. Click Save.

Now the moment of truth. Give your Twilio number a call. You should hear "Hello World".

Making an Outbound Phone Call

Now that we know how to handle an incoming phone call, let's see how to make an outbound call. Making an outbound call requires using the Twilio REST API, so we'll need to make sure we have access to our Account Sid and Auth Token from within our Function.

Configuring Functions

Configuring Functions

 

Go to Configure and check the box that says "Enable ACCOUNT_SID and AUTH_TOKEN". This will do two things for you:

  1. Attach ACCOUNT_SID and AUTH_TOKEN as properties to the context object passed-in to your Function
  2. Enable you to get a Twilio REST API client object with a call to context.getTwilioClient()

On this page you'll notice a section called Environment Variables. Any key/value you set here will also be attached to the context object and made available on every Function invocation. Let's go ahead and create a new Environment Variable called PHONE_NUMBER and set the value to the Twilio Phone Number you configured above.

Create a New Function

Go to Functions/Manage and create a new Function. Set the path to /make_call. Leave the Access box unchecked, as we want to be able to invoke this Function from the command line. Don't select anything for the Twilio Webhook Event, as this Function is not designed to respond to one.

Loading Code Samples...
Language
Format:
  • text
exports.handler = function(context, event, callback) {
  // get an initialized Twilio REST API client
  // MUST have ACCOUNT_SID and AUTH_TOKEN turned on under Configuration
  const client = context.getTwilioClient()
  client.calls.create({
    // event contains all the HTTP parameters passed to this invocation
    to:   event.NumberToCall, 
    // the Twilio Number you set in the Configuration
    from: context.PHONE_NUMBER, 
    // the URL to your Hello World Function
    url:  'https://your-runtime-domain-123/hello'}, 
    function(err, res) {
      // if the REST API call failed, return the error. Otherwise, return OK.
      callback(err, "OK")
    })
};
OK
Make a phone call using a Runtime Function
Make a phone call using a Runtime Function

Make a phone call using a Runtime Function

Make sure you replace the url with the URL of your Hello World Function. Click Save. Once it's done being deployed to Runtime, make an HTTP request to your Function's URL. Make sure to replace the value of the NumberToCall parameter with the phone that you'd like to have ring.

curl -XPOST -d "NumberToCall=%2B17035551212" https://your-runtime-domain-1234.twil.io/make_call 

The phone should ring and the caller ID should be your Twilio number. Answer the call and you should hear "Hello World".

Where to next?

Now that you know the basics of making and receiving phone calls with Twilio Functions, you can consult the REST API and TwiML reference docs to build even richer Voice experiences. Happy hacking!

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.

1 / 1
Loading Code Samples...
Format:
  • XML
exports.handler = function(context, event, callback) {
  let twiml = new Twilio.twiml.VoiceResponse()
  twiml.say("Hello World")
  callback(null, twiml)
}
<Response>
  <Say>Hello World</Say>
</Response>
Format:
  • text
exports.handler = function(context, event, callback) {
  // get an initialized Twilio REST API client
  // MUST have ACCOUNT_SID and AUTH_TOKEN turned on under Configuration
  const client = context.getTwilioClient()
  client.calls.create({
    // event contains all the HTTP parameters passed to this invocation
    to:   event.NumberToCall, 
    // the Twilio Number you set in the Configuration
    from: context.PHONE_NUMBER, 
    // the URL to your Hello World Function
    url:  'https://your-runtime-domain-123/hello'}, 
    function(err, res) {
      // if the REST API call failed, return the error. Otherwise, return OK.
      callback(err, "OK")
    })
};
OK