Using IVR with Verboice¶
Contents
Introduction¶
Integrating the IVR module with Verboice is fairly easy. In order to achieve this you are going to need a Verboice account and a Verboice channel. For the sake of this tutorial we are going to use a Skype SIP profile, which we are going to use during the channel creation. The following sections will describe how to do this in details.
Creating Verboice account¶
In order to create a Verboice account, please visit the Verboice Sign up page. There you will have to provide e-mail address and password for the new Verboice account. Once you have provided the information, click the “Sign up” button. For more information on how to create the account, please visit the Verboice Tutorials page and watch the first tutorial named “Verboice - Create an account”.
Creating Skype channel¶
The next thing is setting up a channel for your Verboice account. Please visit the Using Verboice with Skype page for more information on how to create a Skype SIP profile and integrate it with the created Verboice account.
Configuring IVR module to use Verboice¶
Now that you have the Verboice account integrated with Skype SIP profile you can create a configuration for that account
in the IVR module. To achieve this please go to the Settings
tab in the IVR module section.
Here, just click the Add Configuration
button and the following screen will appear.
Name is the name of your configuration. It can be anything, though we are going to call it
Verboice
.Authentication Required? defines if the IVR provider needs credentials in order to initiate a call. Verboice does require them, so we need to check this checkbox.
Credentials are the username and password to your Verboice account.
Outgoing call URI template is an URI template used for enqueuing calls. There are multiple ways for handling query parameters that are required by the Verboice API. You can include them in this URI either as static or parametrized values. For more information on how to create the URI, please read the Building outgoing call URI template section.
Outgoing call HTTP method is the method used when sending request to the Verboice server. Verboice accepts both
GET
andPOST
methods.Ignored status fields are status fields sent back from the Verboice which should be ignored by MOTECH.
Status field map is a map (in the “key1: value1, key2: value2” notation) of fields sent from Verboice which should be mapped to CallDetailRecord fields, for example to map a (key) field named ‘’call_id’’ coming from the Verboice to the ‘’providerCallId’’ (value) field, use “call_id: providerCallId”. In order to use this example you also need the
Expect JSON response?
checkbox checked andcall_id
added as an element of theJSON extra params list
.Call status mapping is a map (in the “key1: value1, key2: value2” notation) of call status provided by the Verboice and the status which you want to show in CDR log. For example if you want to map status 13 from Verboice to ‘Subscriber not reachable’ you must specify a pair 13: Subscriber not reachable.
Injected services map is a map (in the “key1: value1, key2: value2” notation) of services that can be injected in IVR templates where key is the name used in Velocity and value is the class of the OSGi service, for example to inject org.motechproject.mds.service.EntityService as entityService, use “entityService: org.motechproject.mds.service.EntityService”.
Expect JSON response? defines whether the IVR provider returns a JSON as a response. Verboice does that so we can check this checkbox for some extra data.
JSON extra params list is a list of parameters returned by Verboice. Verboice returns the following parameters as a response:
call_id
andstate
.
Using IVR template as a call flow¶
In order to use an IVR template as a call flow for Verboice you need to define a new call flow on the Verboice side
which will retrieve the call flow from the provided link. To achieve this please login into Verboice through
Verboice Sign in page. Then proceed to the Projects
tab, select the project you want to add a call flow for
and enter the Call Flows
tab. Once there, click the Add Call flow
button and the following form will
show up.
Name is the name of your call flow. It can basically be anything.
Mode defines whether the call flow will be built using the Verboice application or will be fetched from the given URL. Choose the
Use an external application
option here.URL the URL pointing to the IVR template. This URL should have the following format
http://{server}:{port}/module/ivr/template/{config}/{id}?key1=val1&key2=val2&...
, whereserver is the URL of the MOTECH server,
port is the port of the MOTECH server,
config is the name of the IVR module configuration,
id is the ID of the template,
and the query parameters are the values for the keys used in the template.
User is the username of a MOTECH user that will be used for fetching the templates from the MOTECH server.
Password is the password of the MOTECH user that will be used for fetching the templates from the MOTECH server.
Once you have filled the form just press the Save
button.
Building outgoing call URI template¶
Outgoing call URI template is an URI template used for enqueuing calls. The base of this URI is
http://verboice.instedd.org/api/call?
which points to the Verboice call API. Handling query parameters that are
required by the Verboice API can be done in multiple ways.
Verboice requires the following query parameters:
channel is the name of the channel in which to enqueue the call
address is the phone number or sip address to call
call_flow/call_flow_id is the the name/ID of the call flow to execute
schedule/schedule_id is the name/ID of the schedule to use
Verboice also accepts the following optional parameters:
not_before specifies that the call must not be issued before a date (for example: ‘2012-01-02 10:11:12’)
not_after specifies that the call must not be issued after a date (for example: ‘2012-01-02 10:11:12’)
time_zone specifies a time zone for the previous parameter (for example: ‘Buenos Aires’)
For more information about the Verboice API, please visit the Verboice API Wiki page.
Now that we know the supported query parameters, we can build our URI template. The most generic way of creating it is
to provide only the base URI. If you choose this approach you will have to provide all the required query parameters
every time you use the “Initiate Call” action in the Task module or initiateCall
method from the
OutboundCallService
. However, you can choose to create a separate configuration for every channel, address, etc.
just by parameterizing the URI.
Let’s take a look at the following example. We have a channel named testChannel
, the call flow named
testCallFlow
and the schedule named testSchedule
. The only parameter we are going to parameterize is the
phone number. The URI will look like this:
http://verboice.instedd.org/api/call?channel=testChannel&call_flow=testCallFlow&schedule=testSchedule
Using the URI we only need to provide the address
parameter. We can go even further and hide the address
under some other name, which will be more understandable for common user. We can achieve this by using the following URI:
http://verboice.instedd.org/api/call?channel=testChannel&call_flow=testCallFlow&schedule=testSchedule&address=[phoneNumber]
Now we only need to provide the phoneNumber
parameter. Using the [parameterName]
construction will
result in replacing the parameter with the value provided in the parameters map before sending the request to the
Verboice server.
Enqueuing the call¶
You can enqueue the call either by using the service or by using the Task module UI.
Using the OutboundCallService¶
Lets say that we have Verboice account with a channel named testChannel
, the call flow named
testCallFlow
, the schedule named testSchedule
and an IVR configuration named Verboice
that has
the following URI as the Outgoing call URI template
:
http://verboice.instedd.org/api/call?
So we need to provide all the query parameters in order to enqueue the call properly. Here’s a code snippet of how to achieve this.
Map<String, String> params = new HashMap<>();
params.put("channel", "testChannel");
params.put("call_flow", "testCallFlow");
params.put("schedule", "testSchedule");
params.put("address", "90123456789);
outboundCallService.initiateCall("Verboice", params);
This will enqueue a call to the 90123456789 number using the Verboice
configuration.
Using the Task module UI¶
Lets say that we have Verboice account with a channel named testChannel
, the call flow named
testCallFlow
, the schedule named testSchedule
and an IVR configuration named Verboice
that has
the following URI as the Outgoing call URI template
:
http://verboice.instedd.org/api/call?
So we need to provide all the query parameters in order to enqueue the call properly. Here’s a screenshot of how the action should look like.