Generic VXML IVR Provider Demo: Receiving Calls

You accept phone calls, prompt for and record a code, and then send the code in an SMS to the caller.

In more details:

  1. You call the IVR provider [1].
  2. The IVR provider calls Motech [2] to request the hello VXML template which will tell it what to do. This demo uses VXML but, depending on the provider, it could also be CCXML or some proprietary language.
  3. Motech returns the requested hello VXML template.
  4. The IVR provider executes the instructions in hello which prompt the caller to type in a number.
  5. The caller (that’s you!) types in a number.
  6. The IVR provider sends the number to Motech along with a request for the thankyou template.
  7. Motech receives the number you typed, sends a Motech Event, and returns the requested thankyou template.
  8. The IVR provider executes the instructions in thankyou: say ‘Thank you’ and hang up.
  9. Meanwhile, on the Motech side, the Tasks module was waiting for a [we received a template request and the value of the callStatus parameter is ANSWERED] [3] Motech Event. When it finally receives it, it extracts the number you typed, creates a ‘You chose x‘ message and sends an SMS [4] to the number that originated the call, which it also receives as a standard parameter from the IVR provider.
  10. You receive ‘You picked x‘ SMS. Nifty, eh?
[1]IVR providers will typically give you a phone number you can use to call your application on their system. They also will require that you give them a publicly accessible URL so they cal request the VXML that you want to be executed when a call is received at this number.
[2]More precisely makes a REST call to the IVR module at the /template HTTP endpoint.
[3]To differentiate it from other template requests.
[4]From the SMS provider you configured.

IVR Provider

For this demo we used Voxeo, a generic VXML/CCXML provider.

IVR Settings

We need to create an IVR Config so the IVR module knows what to do when it receives HTTP requests from IVR providers. Click on Modules / IVR / Settings:

IVR Demo - IVR Provider Config for incoming calls

Note

Because we’re using the Voxeo IVR provider we named our config voxeo. The name isn’t important, but it’s a good idea to use a simple one as it’ll be part of the URL you’ll provide your IVR provider so it knows where to get the VXML.

A little VXML

Here’s the hello VXML template:

<?xml version="1.0" encoding="UTF-8"?>
  <vxml version = "2.1">
  <form id="enterCode">
    <field name="code" type="digits?minlength=1;maxlength=1">
      <prompt>
        Hello! Please pick a number between 0 and 9.
      </prompt>
    </field>
    <filled>
      <prompt>
        You picked <value expr="code" />.
      </prompt>
      <assign name="from" expr="session.callerid" />
      <assign name="providerCallId" expr="session.sessionid" />
      <assign name="callStatus" expr="'ANSWERED'" />
      <submit name="sendCode" next="http://zebra.motechproject.org:8080/motech-platform-server/module/ivr/template/voxeo/thankyou" namelist="code from providerCallId callStatus" method="get" />
    </filled>
  </form>
</vxml>

Note

The selected number is passed as one of query parameters (code) the IVR provider sends along with its request for the thankyou template.

And the thankyou VXML template, which simply says ‘Thank you’ and hangs up:

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1" >
  <form>
    <block>
      <prompt>
        Thank you
      </prompt>
    </block>
  </form>
</vxml>

Creating the Templates

To add these two templates, click Module / IVR / Settings and then + Add Template:

IVR Demo - Templates

Creating the Task

We need to create a task where the trigger is an IVR template request where the call status is ANSWERED and the action is to send an SMS to the original caller with the code she entered in the message:

IVR Demo - Creating a task

Note

code is extracted from the Motech event payload with {{trigger.provider_extra_data.code}}

Note

A +1 is added to the SMS recipient because our sample SMS provider, Plivo, needs it.

Et Voila!

Now call your application at the phone number that your IVR provider gave you, then listen to the “Hello! Please pick a number between 0 and 9.” prompt, type in a number (say 8). The IVR system will say “You picked 8. Thank you”, then the call will disconnect and soon enough you should receive an SMS:

IVR Demo - Receiving an SMS

Did it work?

In addition to the obvious sign that you’re receiving an SMS from your SMS provider, there are other ways you can check your application works.

  • You can look at the Tasks module’s Recent task activity list to see if your task was executed:

    IVR Demo - Recent task activity
  • Or you can look at your task’s history:

    IVR Demo - Task History
  • You can also browse the IVR CallDetailRecord entity in the database using the MDS Data Browser:

    IVR Demo - CallDetailRecord

    Note

    Our simple VXML application did not bother to set the CallDirection nor many other fields in its status callback to Motech.

  • Yet another way to see how your application would be to be to look at the SMS log or, for even more details, the Server Log.