How to make phone calls using Caché Objectscript and Twilio

Introduction

Twilio is a great tool for programmatically initiating and managing phone calls. In this example we'll go over basic account setup, create a Cache Class to manage our interaction with the Twilio API, and initiate a phone call from the Cache Terminal.

The full Class used in this example is available on GitHub as well.

Setup

1. Create an account on twilio
2. Add a new phone number under the Manage Numbers Page.
   • This will be the number you call from.
3. Add a new caller ID under the Verified Caller IDs Page.
   • This will be the number you call to.
   • If you have a trial account, you are only able to make calls to verified numbers.
4. Make sure you have an SSL Configuration defined.
   • This can be done through the Cache Management Portal under System Administration > Security > SSL/TLS Configurations.

Our helper Class

/// Cache implementation of the Twilio REST ClientClass Twilio.Rest.Client Extends %RegisteredObject  {  /// Twilio's REST API  Property server As %String [ InitialExpression = "api.twilio.com" ];  /// Twilio Account SID found on https://www.twilio.com/console  Property Sid As %String;  /// Twilio Auth Token found on https://www.twilio.com/console  Property AuthToken As %String;  /// The name of the SSLConfig to use with each request (Required for HTTPS)  Property SSLConfig As %String;  Method %OnNew(pSid As %String, pAuthToken As %String, pSSLConfig As %String) As %Status  {    Set ..Sid = pSid    Set ..AuthToken = pAuthToken    Set ..SSLConfig = pSSLConfig    Quit $$$OK  }  /// Make a call using the Twilio REST API.  /// pFrom should be a registered Twilio Phone Number. It needs to follow Twilio's formatting.  /// pTo should be the phone number you would like to call. It needs to follow Twilio's formatting.  /// pUrl is the URL where your TwiML markup resides. Use the TwiML to dictate how the phone call should  /// be handled.  Method Call(pFrom As %String, pTo As %String, pUrl As %String = "") As %String  {    Set httpRequest = ##class(%Net.HttpRequest).%New()    Set httpRequest.Server = ..server    Set httpRequest.Https = 1 // Twilio requires HTTPS    Set httpRequest.SSLConfiguration = ..SSLConfig // Pass in SSL Configuration to use with HTTPS request    // Determine endpoint we will be posting to    Set endpoint = "/2010-04-01/Accounts/"_..Sid_"/Calls"    // Add Credentials to request    Set httpRequest.Username = ..Sid    Set httpRequest.Password = ..AuthToken    // Add form data to http request    Do httpRequest.InsertFormData("From", pFrom)    Do httpRequest.InsertFormData("To", pTo)    If "" '= pUrl {      Do httpRequest.InsertFormData("Url", pUrl)    }    // Post request to server    Set status = httpRequest.Post(endpoint)    If $$$ISERR(status) { Quit status }    Set responseString = httpRequest.HttpResponse.Data.Read()    Quit responseString  }}

Usage

1. Open up a new Terminal and navigate to whichever namespace you defined your Twilio.Rest.Client in.
2. Instantiate a new Twilio Client using the Account SID and Auth Token found here

	Set sid = "your_sid"
	Set token = "your_token"
	Set sslConfig = "name_of_your_ssl_config" //Step 4 of Setup
	Set twilio = ##class(Twilio.Rest.Client).%New(sid, token, sslConfig)

2. Make a call

	Set from = "+18001234567" 				// Twilio phone from step 2 of Setup
	Set to = "+18008675309" 				// Verified caller ID from step 3 of Setup
	Set url = "http://demo.twilio.com/docs/voice.xml" 	// web page containing TwiML instructions
	Set response = twilio.Call(from, to, url)
	// optionally read/handle response here

Twilio determines how the call is handled based on XML instructions called TwiML. You can see the instructions used in the above example by visiting http://demo.twilio.com/docs/voice.xml. Check out the TwiML docs to learn more.

To change how the call is handled, create a webpage and have it return your own set of TwiML instructions. Then pass that url to the Twilio.Rest.Client instead.

Happy coding!