Making a Call With Twilio and Webscript

A previous post demonstrated how how Twilio and Webscript work well together to receive SMS messages and voice calls. Today's post will demonstrate how to make an outgoing Twilio call with Webscript.

Making an outgoing call is a little bit more involved than receiving calls because of Twilio's webhook model. For a simple call, the process involves two steps: making an HTTP request from Webscript to Twilio to initiate the call, and then providing a webhook that Twilio will call to report all events that happen during that call. So, we'll be providing two scripts. The event that we will handle today is when the call is answered.

The demonstration will accept an incoming text and then initiate a voice call to the sender that replies with a synthesized "Hello, World!". The first script will accept the incoming text and initiate outgoing call with the appropriate Twilio credentials. The second script will respond to the events on that call, and, if answered, will <Say> "Hello, World!". The first script uses Webscript's Twilio library to make calling Twilio's REST API easier:

twiliodemo.webscript.io/receive-sms

local twilio = require 'twilio'

local ACCOUNTSID = '<twilio account SID>'
local AUTHTOKEN = '<twilio auth token>'

local scripturl = 'https://twiliodemo.webscript.io/say-helloworld'

twilio.call(ACCOUNTSID, AUTHTOKEN, '+18635786423', request.form.From, scripturl)

twiliodemo.webscript.io/say-helloworld

return
        [[<?xml version="1.0"?>
        <Response>
                <Say>Hello, World!</Say>
        </Response>]], {['Content-Type']='text/xml'}

The callback code above initiates the call from Twilio to the number of the phone that sent the SMS message. Part of placing that call is to specify the URL for the webhook that will handle that call's events. In this simplified version, that webhook—the second script above—just returns the TwiML to synthesize "Hello, World!".

To do more interesting things after voice calls are initiated, it's convenient to pass information from the initiating routine to the event webhook by encoding them into the webhook's URL as query parameters. This is a common Twilio pattern that enables stateless event handlers.

For this example, we will have the script that initiates the call pass back the original text message by including it as a query string parameter in the webhook URL that it specifies when initiating the call:

twiliodemo.webscript.io/receive-sms (full version)

local twilio = require 'twilio'

local ACCOUNTSID = '<twilio account SID>'
local AUTHTOKEN = '<twilio auth token>'

local message = request.form.Body

local scripturl = 'https://twiliodemo.webscript.io/echo-message?'
                .. http.qsencode { text = message }

twilio.call(ACCOUNTSID, AUTHTOKEN, '+18635786423', request.form.From, scripturl)

Now that the webhook URL has a query string that specifies what to say, it's a simple matter to have the webhook grab that query string, and generate TwiML to synthesize that message:

twiliodemo.webscript.io/echo-message

local twiml = string.format(
        [[<?xml version="1.0"?>
        <Response>
                <Say>%s</Say>
        </Response>]], request.query.text)

return twiml, {['Content-Type'] = 'text/xml'}

(You can try this by texting 863-578-6423.)

This demonstration showed that Twilio and Webscript work really well together to place voice calls that can do something interesting. In a future post, we'll use Webscript and Twilio to accept voicemail messages.