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
- Create an account on twilio
- Add a new phone number under the Manage Numbers Page.
- This will be the number you call from.
- 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.
- 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
- Open up a new Terminal and navigate to whichever namespace you defined your Twilio.Rest.Client in.
- 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)
- 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!
Sponsored by InterSystems