Build a Call Tracking Application with Programmable Voice
Learn how to get started with Call Tracking on Voxology’s API, including example call flow scripts that show you how to use our Call Flow Actions to do everything from a simple call forward to time of day routing and competitive call distribution, all with only one callback response.
Voxology’s Programmable Voice offering includes both a REST API and a Callback Request/Response Loop. To get started with Call Tracking on Voxology’s API, follow the steps below:
Once you have completed the ‘Receive Calls’ Tutorial and provisioned an inbound phone number, edit the callback of your new phone number in the call flow configuration. These parameters specify where and how Voxology will send callbacks requests when a call is made to or from your phone number. Your response will be an array of our Call Flow Actions, which will give you full control of the call.
After you have edited the callback in your new inbound phone number’s call flow configuration, select a call tracking script from the Example Call Flow Scripts in the section below, and either post the array a as a static .json file at your callback.url, or you can setup a server to respond to our callback request’s dynamically. Either way, be sure to edit the noted variables in the scripts, including the phone numbers.
NOTE: The Advanced Call Forwarding and Shark Tank scripts require an additional inbound phone number or outbound caller id to be provisioned/verified and configured to handle the additional legs of the call.
After you have selected a sample call flow script and posted it at your callback.url, call the phone number. If successful, your call will be directed to the phone number that you specified in your script. Now, you are off and running with call tracking on Voxology’s API.
The example scripts below represent a variety of call flows that you may use to accommodate your Call Tracking needs. From simple call forwarding to multi-agent dialing, you can use these scripts to quickly build the call flows you need to track the effectiveness of your marketing campaigns.
Please note that the example scripts include only a sampling of what Voxology’s API can do. If you do not find what you require, or have any questions, please contact us to discuss your specific needs, and our team will provide assistance.
This call flow script simply forwards an inbound phone call (made to a number provisioned with Voxology) to another phone number (or SIP address) using the [TRANSFER](/api-reference/#transfer) action.
You may specify both the phone number you want to forward the inbound call to: no, and the phone number you want the second leg to appear to be from: caller_id_no (optional). If you want the call to appear to be from inbound caller’s phone number, do not specify the caller_id_no.
NOTE: the TRANSFER action does not give you the ability to control the second leg of the call. If you require control over the second leg, see the Advanced Call Forwarding script below.
Example Callback Response // Simple Call Forwarding
{
"actions":[
{
"type":"TRANSFER",
"params":{
"no":"+TRANSFER_TO_NUMBER",
"caller_id_no":"+TRANSFER_FROM_NUMBER"
}
},
{
"type":"HANGUP"
}
]
}Similar to ‘Simple Call Forwarding’, this call flow script forwards an inbound phone call (made to a number provisioned with Voxology) to another phone number (or SIP address) using the [TRANSFER](/api-reference/#transfer) action, but with one clear distinction. In this call flow, the TRANSFER number no is controlled by the time of day that the call is made.
This call flow makes use of the [IF](/api-reference/#if) Control Flow Action as well as our Variable Support to set a conditional call forwarding rule based on the $openTimeHours, $openTimeMinutes, and $closeTimeHours, $closeTimeMinutes that you specify.
Example Callback Response // Time of Day Routing
{
"actions":[
{
"$callerID":"$callerNo",
"$openTransferNumber":"+TRANSFER_TO_NUMBER_FOR_OPEN",
"$closeTransferNumber":"+TRANSFER_TO_NUMBER_FOR_CLOSE",
"$openTimeHours":"12",
"$openTimeMinutes":"30",
"$closeTimeHours":"23",
"$closeTimeMinutes":"00",
"$openTime":"Number(new Date().setUTCHours($openTimeHours, $openTimeMinutes))",
"$closeTime":"Number(new Date().setUTCHours($closeTimeHours, $closeTimeMinutes))"
},
{
"type":"IF",
"condition":"$startTime > $openTime && $startTime < $closeTime",
"then":[
{
"type":"SAY",
"params":{
"text":"You have called during business hours."
}
},
{
"type":"TRANSFER",
"params":{
"no":"${openTransferNumber}"
}
}
],
"orElse":[
{
"type":"SAY",
"params":{
"text":"You have called after business hours."
}
},
{
"type":"TRANSFER",
"params":{
"no":"${closeTransferNumber}"
}
},
{
"type":"HANGUP"
}
]
}
]
}While many Call Tracking call flows can be accomplished by simply using the TRANSFER action (see the “Simple Call Forwarding” or “Time of Day Routing” scripts above), the TRANSFER action does not enable full call control over the second leg of the call. So if your call flow requires you to SAY or PLAY a message, or COLLECT digits from second leg caller either before or after connecting them with the first leg, you will need to handle both calls separately and connect them using the CONFERENCE action.
The advanced call forwarding example below requires you to to provision an additional inbound phone number or an outbound caller id and configure it to control the additional leg(s) of the call.
The first call flow script accepts the inbound call, immediately drops the caller into a CONFERENCE and initiates an outbound DIAL to the second leg.
NOTE: You will find the script to control the second leg below.
Example Callback Response // First Leg (inbound) // Advanced Call Forwarding
{
"actions":[
{
"$sessionData.conference_name":"$callId"
},
{
"type":"SAY",
"params":{
"text":"Hello. You are the customer leg and all actions on this flow will be for you. If you want a whisper, simply add a PLAY or SAY action before the DIAL action which will bridge the customer."
}
},
{
"type":"CONFERENCE",
"params":{
"name":"${sessionData.conference_name}",
"max_participants":2,
"end_on_exit":"true"
},
"events":{
"on_enter":[
{
"type":"DIAL",
"session_data": "$sessionData",
"params":{
"no":"CUSTOMER NUMBER TO DIAL",
"caller_id_no":"THIS IS THE CALLERID CONFIGURED TO THE SECOND SCRIPT."
}
}
]
}
},
{
"type":"SAY",
"params":{
"text":"Hello. You can add more ACTIONS after the agent leaves the conference, and these will be executed for the customer."
}
},
{
"type":"HANGUP"
}
]
}The second call flow script controls the outbound call that was initiated in the first script, and immediately drops the caller into the same CONFERENCE.
Example Callback Response // Second Leg (outbound) // Advanced Call Forward
{
"actions" :
[
{
"type":"SAY",
"params":{
"text":"Hello. We are connecting you to a new lead. "
}
},
{
"type" :"CONFERENCE",
"params" :
{
"name" :"${sessionData.conference_name}",
"max_participants":2,
"end_on_exit":"true"
}
},
{
"type":"SAY",
"params":{
"text":"Hello. You can add more ACTIONS after the customer leaves the conference, and these will be executed for the agent."
}
},
{
"type":"HANGUP"
}
]
}Competitive Call Distribution, or ‘Shark Tank’ is the same as a single dial conference with one very useful adaptation. With Shark Tank, once the inbound call from the customer connects the script speed dials an array of agent numbers. The first agent to confirm receipt of the call receives the connection to the customer, whereas those which are late to confirm are simply disconnected.
There are two scripts associated with this setup, and each must have its own call flow configuration. Below are the examples of the two JSON scripts:
Example Callback Response // First Leg (inbound) // Competitive Call Distribution
{
"actions":[
{
"$sessionData.conference_name":"$callId",
"$agentNumbers":"['+FIRST_NUMBER', '+SECOND_NUMBER']"
},
{
"type":"SAY",
"params":{
"text":"Hello. You are the customer-first leg. We will find an agent-second leg for you to talk with."
}
},
{
"type":"CONFERENCE",
"params":{
"name":"${sessionData.conference_name}",
"max_participants":2,
"event":"join",
"end_on_exit":"true"
},
"events":{
"on_enter":[
{
"type":"FOREACH",
"params":{
"iterator":"$agentNumbers"
},
"then":[
{
"type":"DIAL",
"params":{
"no":"${val}",
"caller_id_no":"+THIS IS THE CALLERID CONFIGURED TO THE SECOND SCRIPT"
},
"session_data":"$sessionData"
}
]
}
]
}
},
{
"type":"SAY",
"params":{
"text":"Hello. You can add more ACTIONS after the agent leaves the conference, and these will be executed for the customer."
}
},
{
"type":"HANGUP"
}
]
}Example Callback Response // First Leg (outbound) // Competitive Call Distribution
{
"actions":[
{
"type":"LABEL",
"name":"ConfirmDigit"
},
{
"type":"COLLECT",
"actions":[
{
"type":"SAY",
"params":{
"text":"You have a customer waiting. Please press one followed by the pound sign to speak with them."
}
}
],
"params":{
"finish_on_key":"pound",
"num_digits":1,
"timeout":5000
}
},
{
"type":"IF",
"condition":"$collectAttempt == 3",
"then":[
{
"type":"HANGUP"
}
]
},
{
"type":"IF",
"condition":"$keyPresses == '1'",
"then":[
{
"type":"GOTO",
"params":{
"label":"JoinAgent"
}
}
],
"orElse":[
{
"type":"GOTO",
"params":{
"label":"ConfirmDigit"
}
}
]
},
{
"type":"LABEL",
"name":"JoinAgent"
},
{
"type":"CONFERENCE",
"params":{
"name":"${sessionData.conference_Name}",
"event":"join",
"end_on_exit":"true",
"max_participants":2
},
"events":{
"on_enter_error_max_participants":[
{
"type":"SAY",
"params":{
"text":"Sorry. Someone else, more dedicated to our customers answered."
}
},
{
"type":"HANGUP"
}
]
}
},
{
"type":"SAY",
"params":{
"text":"Hello. You can add more ACTIONS after the customer leaves the conference, and these will be executed for the agent."
}
},
{
"type":"HANGUP"
}
]
}