Delivery Logs

Delivery Logs represent detailed call records of individual phone calls or SMS conversations with a subscriber. When you push an Outgoing Call to many subscribers, one Delivery Log will be created for each subscriber. When you setup an Incoming Call to receive calls/SMS within the VOTO app on specific phone number, a Delivery Log is created every time a subscriber calls in (or sends an SMS to initiate a conversation).

Delivery Status Codes

Every delivery log has a delivery status that shows the state of an individual engagement over Voice, SMS or USSD.

Code Status Details
1 Queued  
2 Ringing  
3 In Progress  
4 Waiting to retry Call not connected on previous attempt, will retry
5 Failed (No Answer) Call was not answered
6 Finished (Complete) Call was answered, and subscriber hung up after completing the content
7 Finished (Incomplete) Call was answered, but subscriber hung up without completing the content
8 Failed (No VOTO Credit) Insufficient credit to complete call
9 Failed (Network) Call failed due to network conditions beyond VOTO
10 Failed (Cancelled) Account user cancelled the call
11 Sent Only relevant for SMS: sent to gateway, with no delivery report yet
12 Finished (Voicemail) Reached voicemail; Played the prompt message into voicemail
13 Failed (Voicemail) Call hung up on reaching voicemail
14 Failed (Error) Call failed, unexpected error (Should never happen)

Get Delivery Logs for a Subscriber

Get Delivery Logs (call records) of all Outgoing and Incoming Calls sent to/received from a Subscriber.

Method: GET

URL: https://go.votomobile.org/api/v1/subscribers/[subscriber_id]/delivery_logs

Parameters:

  • api_key
  • outgoing_only (optional): specify ‘1’ to include only delivery logs for outgoing calls.
  • incoming_only (optional): specify ‘1’ to include only delivery logs for incoming calls.
  • message_id (optional): include only delivery logs for calls with this message_id.
  • survey_id (optional): include only delivery logs for calls with this survey_id.
  • tree_id (optional): include only delivery logs for calls with this tree_id.
  • outgoing_call_id (optional): include only delivery logs for this outgoing_call_id
  • incoming_call_id (optional): include only delivery logs for this incoming_call_id
  • filter_delivery_status (optional): Include only interactions with this delivery_status (e.g.: ‘6’ for Finished (Completed); ‘5’ for Failed (No Answer), etc.)
  • filter_after_date (optional): Include only interactions that ended after this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • filter_before_date (optional): Include only interactions that ended before this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • limit (optional): Specify the pagination limit for number of results to return on one page [max: 500]. You can follow the URLs given for nextURL and previousURL in the ‘pagination’ section of the response to navigate through pages.

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "subscriber_call_log": [
          {
              "id": "402996",
              "incoming_call_id": null,
              "outgoing_call_id": "200949",
              "seconds_completed": "7",
              "message_seconds_total": "6.78",
              "retried_times": null,
              "start_timestamp": "2014-03-09 15:11:18",
              "end_timestamp": "2014-03-09 15:11:25",
              "message_start_timestamp": "2014-03-09 15:11:18",
              "message_end_timestamp": "2014-03-09 15:11:25",
              "message_percent_listened": "100",
              "survey_questions_answered": "0",
              "survey_questions_total": null,
              "total_call_attempts": "1",
              "last_call_attempt": "2014-03-09 15:11:45",
              "survey_id": null,
              "message_id": "200250",
              "tree_id": null,
              "subscriber_id": "373648",
              "language_id": "200247",
              "phone": "233264164182",
              "survey": null,
              "message": {
                  "id": "200250",
                  "message_results": "https://go.votomobile.org/api/v1/messages/200250/stats",
                  "percent_listened": "100",
                  "listened_seconds": "7"
              },
              "subscriber": {
                  "id": "373648",
                  "phone": "233264164182",
                  "language_id": "200247",
                  "delivery_logs": "https://go.votomobile.org/api/v1/subscribers/373648/delivery_logs"
              }
          },
          {
              "id": "406078",
              "incoming_call_id": null,
              "outgoing_call_id": "201134",
              "seconds_completed": null,
              "message_seconds_total": null,
              "retried_times": null,
              "start_timestamp": null,
              "end_timestamp": "2014-03-16 00:42:27",
              "message_start_timestamp": null,
              "message_end_timestamp": null,
              "message_percent_listened": null,
              "survey_questions_answered": "3",
              "survey_questions_total": "3",
              "total_call_attempts": "0",
              "last_call_attempt": null,
              "survey_id": "200255",
              "message_id": null,
              "tree_id": null,
              "subscriber_id": "373648",
              "language_id": "200247",
              "phone": "233264164182",
              "survey": {
                  "id": "200255",
                  "survey_results": "https://go.votomobile.org/api/v1/surveys/200255/results",
                  "individual_results": "https://go.votomobile.org/api/v1/surveys/200255/delivery_logs/406078"
              },
              "message": null,
              "subscriber": {
                  "id": "373648",
                  "phone": "233264164182",
                  "language_id": "200247",
                  "delivery_logs": "https://go.votomobile.org/api/v1/subscribers/373648/delivery_logs"
              }
          }
      ]
  },
  "message": "Delivery logs fetched successfully.",
  "more_info": "",
  "pagination": {
      "nextURL": "https://go.votomobile.org/api/v1/subscribers/373648/delivery_logs?limit=2&page_after=406078",
      "previousURL": null
  },
  "url": "https://go.votomobile.org/api/v1/subscribers/373648/delivery_logs?limit=2"
}

Get Delivery Logs for an Incoming Call

Get all Delivery Logs (call records) for an Incoming Call. (Optionally filter by subscriber, delivery status, and date range.)

Method: GET

URL: https://go.votomobile.org/api/v1/incoming_calls/[incoming_call_id]/delivery_logs

Parameters:

  • api_key
  • subscriber_id (optional): Include only calls from this subscriber_id
  • filter_delivery_status (optional): Include only interactions with this delivery_status (e.g.: ‘6’ for Finished (Completed); ‘5’ for Failed (No Answer), etc.)
  • filter_after_date (optional): Include only interactions that ended after this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • filter_before_date (optional): Include only interactions that ended before this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • limit (optional): Specify the pagination limit for number of results to return on one page [max: 500]. You can follow the URLs given for nextURL and previousURL in the ‘pagination’ section of the response to navigate through pages.

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "delivery_logs": [
          {
              "id": "1775696",
              "incoming_call_id": "200147",
              "outgoing_call_id": null,
              "seconds_completed": "12",
              "message_seconds_total": null,
              "retried_times": null,
              "start_timestamp": "2014-09-25 18:47:05",
              "end_timestamp": "2014-09-25 18:47:19",
              "message_start_timestamp": null,
              "message_end_timestamp": null,
              "message_percent_listened": null,
              "survey_questions_answered": "0",
              "survey_questions_total": "3",
              "total_call_attempts": "0",
              "last_call_attempt": "2014-09-25 18:47:19",
              "survey_id": "200568",
              "message_id": null,
              "tree_id": null,
              "subscriber_id": "373648",
              "language_id": "200247",
              "phone": "233264164182",
              "survey": {
                  "id": "200568",
                  "survey_results": "https://go.votomobile.org/api/v1/surveys/200568/results",
                  "individual_results": "https://go.votomobile.org/api/v1/surveys/200568/delivery_logs/1775696"
              },
              "message": null,
              "subscriber": {
                  "id": "373648",
                  "phone": "233264164182",
                  "language_id": "200247",
                  "delivery_logs": "https://go.votomobile.org/api/v1/subscribers/373648/delivery_logs"
              }
          },
          {
              "id": "1775698",
              "incoming_call_id": "200147",
              "outgoing_call_id": null,
              "seconds_completed": "14.18",
              "message_seconds_total": null,
              "retried_times": null,
              "start_timestamp": "2014-09-25 18:48:32",
              "end_timestamp": "2014-09-25 18:48:49",
              "message_start_timestamp": null,
              "message_end_timestamp": null,
              "message_percent_listened": null,
              "survey_questions_answered": "0",
              "survey_questions_total": "3",
              "total_call_attempts": "0",
              "last_call_attempt": "2014-09-25 18:48:49",
              "survey_id": "200568",
              "message_id": null,
              "tree_id": null,
              "subscriber_id": "373648",
              "language_id": "200247",
              "phone": "233264164182",
              "survey": {
                  "id": "200568",
                  "survey_results": "https://go.votomobile.org/api/v1/surveys/200568/results",
                  "individual_results": "https://go.votomobile.org/api/v1/surveys/200568/delivery_logs/1775698"
              },
              "message": null,
              "subscriber": {
                  "id": "373648",
                  "phone": "233264164182",
                  "language_id": "200247",
                  "delivery_logs": "https://go.votomobile.org/api/v1/subscribers/373648/delivery_logs"
              }
          }
      ]
  },
  "message": "Delivery logs fetched successfully.",
  "more_info": "",
  "pagination": {
      "nextURL": "https://go.votomobile.org/api/v1/incoming_calls/200147/delivery_logs?limit=2&page_after=1775698",
      "previousURL": null
  },
  "url": "https://go.votomobile.org/api/v1/incoming_calls/200147/delivery_logs?limit=2"
}

Get Delivery Logs for an Outgoing Call

Get all Delivery Logs (call records) for an Outgoing Call. (Optionally filter by subscriber, delivery status, and date range.)

Method: GET

URL: https://go.votomobile.org/api/v1/outgoing_calls/[outgoing_call_id]/delivery_logs

Parameters:

  • api_key
  • subscriber_id (optional): Include only calls to this subscriber_id.
  • filter_delivery_status (optional): Include only interactions with this delivery_status (e.g.: ‘6’ for Finished (Completed); ‘5’ for Failed (No Answer), etc.)
  • filter_after_date (optional): Include only interactions that ended after this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • filter_before_date (optional): Include only interactions that ended before this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • limit (optional): Specify the pagination limit for number of results to return on one page [max: 500]. You can follow the URLs given for nextURL and previousURL in the ‘pagination’ section of the response to navigate through pages.

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "delivery_logs": [
          {
              "id": "407821",
              "incoming_call_id": null,
              "outgoing_call_id": "201160",
              "seconds_completed": "111",
              "message_seconds_total": null,
              "retried_times": null,
              "start_timestamp": "2014-03-17 09:29:42",
              "end_timestamp": "2014-03-17 09:31:33",
              "message_start_timestamp": null,
              "message_end_timestamp": null,
              "message_percent_listened": null,
              "survey_questions_answered": "3",
              "survey_questions_total": "3",
              "total_call_attempts": "3",
              "last_call_attempt": "2014-03-17 09:29:28",
              "survey_id": "200568",
              "message_id": null,
              "tree_id": null,
              "subscriber_id": "376089",
              "language_id": "200247",
              "phone": "233230762734",
              "survey": {
                  "id": "200568",
                  "survey_results": "https://go.votomobile.org/api/v1/surveys/200568/results",
                  "individual_results": "https://go.votomobile.org/api/v1/surveys/200568/delivery_logs/407821"
              },
              "message": null,
              "subscriber": {
                  "id": "376089",
                  "phone": "233230762734",
                  "language_id": "200247",
                  "delivery_logs": "https://go.votomobile.org/api/v1/subscribers/376089/delivery_logs"
              }
          },
          {
              "id": "407822",
              "incoming_call_id": null,
              "outgoing_call_id": "201160",
              "seconds_completed": "75",
              "message_seconds_total": null,
              "retried_times": null,
              "start_timestamp": "2014-03-17 09:28:13",
              "end_timestamp": "2014-03-17 09:29:28",
              "message_start_timestamp": null,
              "message_end_timestamp": null,
              "message_percent_listened": null,
              "survey_questions_answered": "2",
              "survey_questions_total": "3",
              "total_call_attempts": "2",
              "last_call_attempt": "2014-03-17 09:27:40",
              "survey_id": "200568",
              "message_id": null,
              "tree_id": null,
              "subscriber_id": "376090",
              "language_id": "200247",
              "phone": "233230762731",
              "survey": {
                  "id": "200568",
                  "survey_results": "https://go.votomobile.org/api/v1/surveys/200568/results",
                  "individual_results": "https://go.votomobile.org/api/v1/surveys/200568/delivery_logs/407822"
              },
              "message": null,
              "subscriber": {
                  "id": "376090",
                  "phone": "233230762731",
                  "language_id": "200247",
                  "delivery_logs": "https://go.votomobile.org/api/v1/subscribers/376090/delivery_logs"
              }
          }
      ]
  },
  "message": "Delivery logs fetched successfully.",
  "more_info": "",
  "pagination": {
      "nextURL": "https://go.votomobile.org/api/v1/outgoing_calls/201160/delivery_logs?limit=2&page_after=407822",
      "previousURL": null
  },
  "url": "https://go.votomobile.org/api/v1/outgoing_calls/201160/delivery_logs?limit=2"
}

Call Summary For An Outgoing Call

Retrieve aggregate statistics for an Outgoing Call

Method: GET

URL: https://go.votomobile.org/api/v1/outgoing_calls/[outgoing_call_id]/summary

Parameters:

  • api_key

Returns:

{
 "status":200,
 "message":"Outgoing Call Summary",
 "data":
    {
      totalVoiceAirtime: null,
      totalMsgAirtime: 190,
      averageListeningTime: 80,
      averagePercentListened: 70,
      questionsIntended: 4,
      questionsAnswered: null,
      questionsNoResponse: "1",
      questionsIncompleteResponse: "2"
     }
}

Get Delivery Logs for a Survey

Get all Delivery Logs (call records) related to a specific Survey. (Optionally filter by subscriber, delivery status, and date range.)

Method: GET

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/delivery_logs

Parameters:

  • api_key
  • subscriber_id (optional): Include only calls to this subscriber_id.
  • filter_delivery_status (optional): Include only interactions with this delivery_status (e.g.: ‘6’ for Finished (Completed); ‘5’ for Failed (No Answer), etc.)
  • filter_after_date (optional): Include only interactions that ended after this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • filter_before_date (optional): Include only interactions that ended before this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • limit (optional): Specify the pagination limit for number of results to return on one page [max: 500]. You can follow the URLs given for nextURL and previousURL in the ‘pagination’ section of the response to navigate through pages.

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "delivery_logs": [
          {
              "id": "407819",
              "incoming_call_id": null,
              "outgoing_call_id": "201159",
              "seconds_completed": "137",
              "message_seconds_total": null,
              "retried_times": null,
              "start_timestamp": "2014-03-17 09:11:17",
              "end_timestamp": "2014-03-17 09:13:34",
              "message_start_timestamp": null,
              "message_end_timestamp": null,
              "message_percent_listened": null,
              "survey_questions_answered": "3",
              "survey_questions_total": "3",
              "total_call_attempts": "1",
              "last_call_attempt": "2014-03-17 09:10:57",
              "survey_id": "200568",
              "message_id": null,
              "tree_id": null,
              "subscriber_id": "373648",
              "language_id": "200247",
              "phone": "233264164182",
              "survey": {
                  "id": "200568",
                  "survey_results": "https://go.votomobile.org/api/v1/surveys/200568/results",
                  "individual_results": "https://go.votomobile.org/api/v1/surveys/200568/delivery_logs/407819"
              },
              "message": null,
              "subscriber": {
                  "id": "373648",
                  "phone": "233264164182",
                  "language_id": "200247",
                  "delivery_logs": "https://go.votomobile.org/api/v1/subscribers/373648/delivery_logs"
              }
          },
          {
              "id": "407821",
              "incoming_call_id": null,
              "outgoing_call_id": "201160",
              "seconds_completed": "111",
              "message_seconds_total": null,
              "retried_times": null,
              "start_timestamp": "2014-03-17 09:29:42",
              "end_timestamp": "2014-03-17 09:31:33",
              "message_start_timestamp": null,
              "message_end_timestamp": null,
              "message_percent_listened": null,
              "survey_questions_answered": "3",
              "survey_questions_total": "3",
              "total_call_attempts": "3",
              "last_call_attempt": "2014-03-17 09:29:28",
              "survey_id": "200568",
              "message_id": null,
              "tree_id": null,
              "subscriber_id": "376089",
              "language_id": "200247",
              "phone": "233230762734",
              "survey": {
                  "id": "200568",
                  "survey_results": "https://go.votomobile.org/api/v1/surveys/200568/results",
                  "individual_results": "https://go.votomobile.org/api/v1/surveys/200568/delivery_logs/407821"
              },
              "message": null,
              "subscriber": {
                  "id": "376089",
                  "phone": "233230762734",
                  "language_id": "200247",
                  "delivery_logs": "https://go.votomobile.org/api/v1/subscribers/376089/delivery_logs"
              }
          }
      ]
  },
  "message": "Delivery logs fetched successfully.",
  "more_info": "",
  "pagination": {
      "nextURL": "https://go.votomobile.org/api/v1/surveys/200568/delivery_logs?limit=2&page_after=407821",
      "previousURL": null
  },
  "url": "https://go.votomobile.org/api/v1/surveys/200568/delivery_logs?limit=2"
}