TaCode Tuesdays: Create an Automated Outbound Call Dialer Using Zang

Posted by Pedram Mohammadi on December 20, 2016

TaCode_Image_New.jpg

Welcome back to TaCode Tuesdays! This is the only place you can find snippets of code for use in your very own text/voice apps, along with a weekly dose of taco puns. I’m a developer here at Zang and not only am I a big fan of tacos (if that wasn’t already apparent), I’m also a fan of open source. My goal is to share a new app idea each week that you're free to use “as is” or modify and use as the basis for your next app.

In the last few weeks, I have been detailing how to build an interactive voice response system (IVR) using Zang—you can check out PART 1 here, PART 2 here, and as always, if you’d like to learn how to get started on Zang, take a look at our very first post.

This week I’m going to show you the proper way to set up automated outbound dialing so you can use it to increase sales and customer satisfaction. 

What's an auto-dialer?

Auto-dialers, sometimes called robocalls, can help increase sales and customer satisfaction if used correctly. Automated callers work by having a Public Switched Telephone Network (PSTN) spontaneously call a set of pre-defined customers who have subscribed, registered, or given their consent to receive such alerts. Once the call has been picked-up, an Interactive Voice Response (IVR) system can play pre-recorded messages or initiate a call transfer to a live agent. Auto-dialers work best in creating outbound call campaigns that are beneficial to the target market. For instance, a robocall can be set to inform parents that classes have been suspended; send a reminder for a doctor’s appointment; or inform a customer of a new product or service.

Auto-dialers can also help increase productivity. When used in call centers, it can cut down the time needed for an agent to dial a number. When programmed to include other algorithms, such as average call length, number of agents available, and average number of calls, it can intelligently handle huge call volumes. For instance, robocalls can transfer inquiries to the right agent or inform customers of their average waiting time. This helps in managing user expectations at peak hours, or in the event of a system outage leading to operate below SLAs.

On this week’s blog, we will create an auto dialer using Zang cPaaS.

Here are the basic requirements:

  1. Subscription to Zang.io cPaaS. If you do not have one yet, you can get one for free here.
  2. Intermediate knowledge of cURL library
  3. Knowledge of PHP programming language
  4. Knowledge of JavaScript Object Notation (JSON) data format
  5. Working knowledge of some basic Unix commands

Before we start, let’s look at this data flow diagram. This will serve as our guide as we go through the process of development:

automated-outbound-dialer-data-flow-diagram.png 

Figure 1: Zang.io Automated Outbound Dialer – Data Flow Diagram

This diagram shows how to use Zang to create a basic automated dialer. The process starts by having your PHP code initiate the Call API through a HTTP request that will eventually push the outbound call to a set of pre-defined users. Once the call has been picked-up, the IVR will handle it by either playing a pre-recorded message or transferring the call to a customer service representative. Finally, when the user hangs-up and the call has ended, Zang will push a message about its completion.

 We can sum this up to three basic steps:
  1. Create a dialer that will invoke Zang API through REST;
  2. Make the call and allow Zang to process the JSON file request. This will be handled by an InboundXML wherein a return response will be provided if the call recipient is not available to answer; and
  3. Create a call handler that will be invoked once a successful JSON response has been received.

Before we start, it is important that you gain some familiarity with Zang’s XML and InboundXML API commands like the following tags.

  • Zang’s text-to-speech engine is responsible for most of SDK elements. <Say> is good to use with dynamic data, while <Play> may be a better choice for static information or prompts. The text to be read is nested within the <Say> element.
  • <Response> All InboundXML elements are camelCased and are categorized as either Verbs or Nouns. Zang begins reading at <Response> and behaves accordingly as it encounters each new instruction element until the end of the </Response>.
  • When Zang receives an InboundXML document, the "instructions" are contained within the <Response> </Response> elements.
  • <Hangup> will end the current call.

Step 1: Create a dialer that will invoke Zang API through REST

First, get your Account SID and Auth token by logging into the Zang.io developer dashboard. Copy those values and paste them into your {AccountSid} and {AuthToken} variables.  From there, create a PHP code that will call the Zang ‘make call’ API method.

 

curl -X POST 'https://api.zang.io/v2/Accounts/{AccountSid}/Calls.json' -u '{AccountSid}:{AuthToken}' -d 'From=XXX-XXX-XXXX&To=XXX-XXX-XXXX&Url=http://zang.io/ivr/welcome/call'

 

Zang API makes use of cURL extensively. cURL allows you to connect with other URLs and use their HTML responses on your code. Just make sure that proper sever security measures are in place because someone can get between your cURL to inject a UNIX command say for instance "rm -rf /" causing your "ls -l" to freeze. Now, let’s use PHP cURL library to translate the console cURL command.

 <?php

//setup zang variables

$m_url = 'https://api.zang.io/v2/Accounts/';

 

//zang authentication

 

$m_accountSid   = '{AccountSid}';

$m_accountToken = '{AuthToken}';

 

$fld_from       = '{XXX-XXX';

$fld_to         = 'XXX-XXX-XXXX';

$fld_url        = 'http://zang.io/ivr/welcome/call';

 

/*Note: 'URL' must be a valid and should return inboundXML instructions on how to process your call.*/

 

Step 2: Make the call and allow Zang to process the JSON file request.

When the call is complete or if the line is busy or no one answers, Zang will make a request to the URL you specify in the "StatusCallback" parameter. By default, your application isn’t notified when a call is complete, if the line is busy, or no one answers. To get call status notification, include the "StatusCallback" parameter with your REST request.

 

$fields = array(

'To' => urlencode({+17325551212}),

'From' => urlencode({8143}),

/*

this is the inboundXML url on how to process your call once it is initiated.

*/

 

'Url' => urlencode({http://yourwebsitedot.com/xxx}),

'Method' => urlencode('POST'),

'FallbackUrl' => urlencode({url fallback}),

'FallbackMethod' => urlencode({url}),

'StatusCallback' => urlencode({url}),

 

'StatusCallbackMethod' => urlencode(POST}),

'HeartbeatUrl' => urlencode({url}),

'HeartbeatMethod' => urlencode({http POST}),

'ForwardedFrom' => urlencode({telno}),

'PlayDtmf' => urlencode({false}),

'Timeout' => urlencode({60}),

'HideCallerId' => urlencode({false}),

'Record' => urlencode($_POST['phone']),

'RecordCallback' => urlencode({url}),

'RecordCallbackMethod' => urlencode({POST}),

'Transcribe' => urlencode({false}),

'TranscribeCallback' => urlencode({false}),

'StraightToVoicemail' => urlencode($_POST['phone']),

/*

Note: If a voice machine answers your call this will redirect to the Zang field name url as specified by "IfMachineUrl" otherwise it will default to "redirect" URL.

*/

 

'IfMachine' => urlencode({continue}), <--

'IfMachineUrl' => urlencode({redirect url http://..}),

'IfMachineMethod' => urlencode($_POST['phone']),

'SipAuthUsername' => urlencode({SipAuthUsername}),

'SipAuthPassword' => urlencode({SipAuthPassword}),

);

 

//Setup request fields to send json via POST.

$payload = json_encode($fields);

 

//Initialise curl

$ch = curl_init();

 

//Build curl options

//This value is the URL which we are sending the request to.

 

curl_setopt($ch, CURLOPT_URL,$m_url);

 

//Set timeout for response time

curl_setopt($curl_handle,CURLOPT_CONNECTTIMEOUT,2);

 

//The JSON encoded data as required by Zang API

curl_setopt( $ch, CURLOPT_POSTFIELDS, $payload );

 

//False will tell cURL to ignore the header in the return value

curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

 

//Tells cURL to use HTTP POST Method by default per Zang's API its all POST

curl_setopt($ch, CURLOPT_POST, 1);

 

//Receive server response ...

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

 

/*

The curl_exec command in PHP is a bridge to use curl from console. curl_exec makes

it easy to quickly and easily do GET/POST requests, receive responses from other

servers like JSON and download files.

*/

$server_output = curl_exec ($ch);

curl_close ($ch);

 

// Further processing ...

if ($server_output == "OK") { ... } else { ... }

 

?>

 

Step 3: Create a call handler that will be invoked once a successful JSON response has been received.

<?php

$m_xml =’<?xml version="1.0" encoding="UTF-8"?>

<Response>’;

   if ($_GET['AnsweredBy'] == '{nobody}') {

   $m_xml.=’<Say>Greetings! we are about to connect you to {YOUR NAME}</Say>

   <Dial>{XXX-XXX-XXXX}</Dial>’;

  } else {

       $m_xml.=’There was no answer - so we just hang-up.

   <Hangup/>’;

   }

   $m_xml.=’</Response>’;

echo $m_xml;

?>

 

Below is an example JSON response from Zang after invoking the Zang’s make_call API method.

 

{

 "date_updated": "Wed, 13 Jul 2016 15:25:01 -0000",

 "parent_call_sid": "",

 "duration": 0,

 "from": "+15555555555",

 "to": "+19999999999",

 "caller_id_blocked": "false",

 "answered_by": "nobody",

 "sid": "{CallSid}",

 "recordings_count": "",

 "price": "0.00",

 "api_version": "v2",

 "status": "queued",

 "direction": "outbound-api",

 "start_time": null,

 "date_created": "Wed, 13 Jul 2016 15:25:01 -0000",

 "subresource_uris": {

   "notifications": "/v2/Accounts/{AccountSid}/Calls/{CallSid}/Notifications",

   "recordings": "/v2/Accounts/{AccountSid}/Calls/{CallSid}/Recordings"

 },

 "forwarded_from": "",

 "uri": "/v2/Accounts/{AccountSid}/Calls/{CallSid}",

 "account_sid": "{AccountSid}",

 "duration_billed": 0,

 "end_time": null,

 "phone_number_sid": ""

}

 

Note that you can run the program, use a command line or upload it on your web host/server or alternatively on your Dev setup via a third-party Apache package like MAMP /XAMPP/WAMP.

Create Cost-Efficient Auto Dialers with Zang

Robocalls, if used correctly can help in increasing sales and customer satisfaction. Implementing this solution in a standard call center suite is typically expensive. However, you can create a more cost efficient version using Zang cPaaS in just three easy steps. Bear in mind, though, that auto dialers shouldn’t be used to contact customers who have not given their consent or at least were informed that they will be receiving such calls. In the US - AT&T, Apple and Google are teaming up with the government to have this regulated.

Topics: Communication Apps, Ideas, TaCode Tuesday, cPaaS

IMAGINE IT. BUILD IT.

Communicate better. 

Cloud communication technology that transforms your conversations — and your business.

 

Subscribe to Email Updates