Blog Page

API to send voice call via VoIP to multiple recipients

In this post we discuss how to send SIP call to many recipients at a time with only one request and get the result report.

This post continues to discuss API to send voice calls via VoIP and play prerecorded or Text to Speech (TTS) messages. In previous article we discussed sending calls to one recipient. Now, let's say we need to serve single voice message located at this address: http://server.domain.com/voices/hello.wav to multiple users. You can send multiple requests to the API with changing to addresses, but there is a simplest way to o it. It is both faster, and can be reused later if you need to change message to be sent. Here is how we will send the API request:

POST /voice/call/play 

{
  "recipients":
    [
      {
        "to": "sip:123456@192.168.1.1:5060"
      },
      {
        "to": "sip:alice@192.168.1.1:5060"
      },
      {
        "to": "sip:bob@192.168.1.1:5060"
      },
      {
        "to": "sip:charlie@192.168.1.1:5060"
      },
      {
        "to": "sip:999777@192.168.1.1:5060"
      },
  "from": "me",
  "playlist":
    [
      { 
        "play": "http://server.domain.com/voices/hello.wav"
      }
    ]
}

As you can see, the request is similar as in case with one recipient, with the difference that to fields are listed in the recipients field. The API will then reply to us with the response:

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

What happens behind the scene, is that system now took our request, and put all recipients in the queue. Depending on the size of the request and available resources, it might take some time while all users are called. Therefore the status report might not be available immediately. Also, it can be very large if the number of recipients is big. Let's call the status API and see what we get:

GET /voice/call/status/62395c48-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-02 12:15:32",
        "to": "sip:123456@192.168.1.1:5060",
        "from": "me",
        "setup_time": "2018-05-02 12:15:32",	
        "connect_time": "2018-05-02 12:15:45",
        "disconnect_time": "2018-05-02 12:16:02",
        "disconnect_cause_code": "200",
        "disconnect_cause_text": "OK",
        "duration": 17,
        "answered": true
      },
      {
        "type": "voice",
        "id": "7d365d1d-0c29-4438-b66d-26fa9ebebfef",
        "result": "completed",
        "request_time": "2018-05-02 12:15:32",
        "to": "sip:alice192.168.1.1:5060",
        "from": "me",
        "setup_time": "2018-05-02 12:15:32",	
        "connect_time": "2018-05-02 12:15:50",
        "disconnect_time": "2018-05-02 12:16:05",
        "disconnect_cause_code": "200",
        "disconnect_cause_text": "OK",
        "duration": 15,
        "answered": true
      },
........
      {
        "type": "voice",
        "id": "b9e8ea96-8dea-4878-bc2f-3f2014026532",
        "result": "completed",
        "request_time": "2018-05-02 12:15:32",
        "to": "sip:999777@192.168.1.1:5060",
        "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
      }
    ]
}

The API now returns a report with full details of each call as in the case of single call. Note that each record contains an ID which relates to the individual call. And indeed, you can also query each call individually:

GET /voice/call/status/b9e8ea96-8dea-4878-bc2f-3f2014026532

and get the same result:

{
  "code": 0,
  "status": 200,
  "data": "accepted",
  "request_id": "b9e8ea96-8dea-4878-bc2f-3f2014026532",
  "record":
    {
      "type": "voice",
      "result": "completed",
      "request_time": "2018-05-02 12:15:32",
      "to": "sip:999777@192.168.1.1:5060",
      "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
    }
}

Now when we know how to send calls to multiple recipients, we can proceed to next part where we will discuss advanced routing and SIP parameter settings via API.