Blog Page

Post Author

By: Aivis Olsteins

In News

2018-05-25

Use case: automated voice call with users response on multiple choices

API can do more than just to play a voice file to the user. Here is an example of interactive voice menu with results collection.

API can perform some more complex tasks as just speaking a prerecorded or text-to-speech message to the user. It can be used also for asking user to present a voice menu, i. e. to play some kind of message and collect user's feedback by key press. The application cases of such systems are for example, automated appointment confirmation systems, voting and polling, and similar. The work-flow of the system follows this sequence:

an external application makes an API call to make a voice call or calls to one or several users.
The system calls user/users and plays predefined message (either recorded or text-to-speech) once the call is connected.
System waits user to make their choice, by pressing keys and capturing DTMF signals.
Once keypress is received, system will play final message and hangup.
The result is stored in a report and can be retrieved by application later when all calls are completed.

Here is a practical example of how it works.

Let's say we want to call users with these phone numbers:

100123
100124
100125

and when connected, to play a greeting message which we store here: http://server.domain.com/voices/greeting.wav

After that we will play message which will tell them to press keys 1 to 5 according to their choice which is located here: http://server.domain.com/voices/press-1-to-5.wav. Once they they have made their choice, we will play good-bye message: http://server.domain.com/voices/goodbye.wav and hangup.

So here is an example API call which will do the above required task:

POST /voice/call/menu
 {
"recipients":
    [
{ "to": "100123" },
      { "to": "100124" },
      { "to": "100125" }
    ]
  "from": "me",
  "playlist_1":
    [
{ "play": "http://server.domain.com/voices/greeting.wav" },
{ "play": "http://server.domain.com/voices/press-1-to-5.wav" }
    ],
  "dtmf":
    {
"max_digits": 1,
"allow": "[1-5]"
},
  "playlist_2":
    [
{ "play": "http://server.domain.com/voices/goodbye.wav" }
    ],
}

The above example is pretty much self-explanatory. Some things to note:

playlist_1 and playlist_2 are played before and after DTMF collection, respectively;
dtmf attribute max_digits mean that system will only accept single-digit choices, i. e. as long as first digit is pressed, it is accepted and no more digits are expected;
dtmf attribute allow is essentially a regular expression. In this case it tells to accept digits in a range 1-5 only.

As a response API will return something like this:

{
  "code": 0,
  "status": 200,
  "data": "accepted",
  "request_id": "62395c84-5ebf-48f4-8cce-fa6e22d76577"
}

This response actually contains a reference to the request ID which we can query to find where the result report can be found:

GET /voice/call/status/62395c84-5ebf-48f4-8cce-fa6e22d76577

And the system replies with something like this:

{
  "code": 0,
  "status": 200,
  "data": "accepted",
  "request_id": "5182ebda-4a5f-4a0d-9725-5eaa06cddea4",
  "report":
    {
      "id": "55d9c8c5-e86f-40e7-a902-a07e176f5511",
      "location": "/reports",
      "status": "ready",
    }
}

Instead of call information we now got a reference to report which will be generated after calls are completed. This is due to fact that these reports might take longer time to be created, and can be very large in terms of size, again because it is possible to call many users at the same time. The status field shows if report is ready. When it it ready, we send new API call to get the report itself:

GET /report/55d9c8c5-e86f-40e7-a902-a07e176f5511

The system will now send us full call report with all details of the calls made:

{
  "code": 0,
  "status": 200,
  "data": "accepted",
  "request_id": "55d9c8c5-e86f-40e7-a902-a07e176f5511",
  "records":
    [
      {
        "type": "voice",
        "id": "838a8fb3-3146-4c57-8964-05d95ac768e6",
        "result": "completed",
        "request_time": "2018-05-22 12:15:32",
        "to": "100123",
        "from": "me",
        "setup_time": "2018-05-22 12:15:32",    
        "connect_time": "2018-05-22 12:15:45",
        "disconnect_time": "2018-05-22 12:16:02",
        "disconnect_cause_code": "200",
        "disconnect_cause_text": "OK",
        "duration": 17,
        "answered": true,
        "dtmf_data": [
          {"key": "1"}
        ]
      },
      {
        "type": "voice",
        "id": "7d365d1d-0c29-4438-b66d-26fa9ebebfef",
        "result": "completed",
        "request_time": "2018-05-22 12:15:32",
        "to": "100124",
        "from": "me",
        "setup_time": "2018-05-22 12:15:32",    
        "connect_time": "2018-05-22 12:15:50",
        "disconnect_time": "2018-05-22 12:16:05",
        "disconnect_cause_code": "200",
        "disconnect_cause_text": "OK",
        "duration": 15,
        "answered": true,
        "dtmf_data": [
          {"key": "4"}
        ]
      },
      {
        "type": "voice",
        "id": "b9e8ea96-8dea-4878-bc2f-3f2014026532",
        "result": "completed",
        "request_time": "2018-05-02 12:15:32",
        "to": "100125",
        "from": "me",
        "setup_time": "2018-05-02 12:15:32",    
        "disconnect_time": "2018-05-02 12:16:42",
        "disconnect_cause_code": "486",
        "disconnect_cause_text": "User Busy",
        "duration": 0,
        "answered": false
      }
    ]
}