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 Client
Class 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!