Outgoing Calls

An ‘Outgoing Call’ is a request to send a call or SMS to multiple subscribers, with associated content: a message and/or survey. (The content will be delivered through voice in each subscriber’s language, and/or through SMS, depending on their settings. You can send an outgoing call immediately, or schedule it for the future using multiple scheduling options.

Create An Outgoing Call

Create and send/schedule an outgoing call to one or many subscribers.

Method: POST

Parameters:

  • api_key

  • message_id : ID of the message to send { [eg.47] default:none}

  • survey_id : ID of the survey to send { [eg.432] default:none}

  • tree_id : ID of the tree to send { [eg.42] default:none}

  • sms_sender_id : When sending non-interactive SMS to supported destinations, you can specify an alpha-numeric SMS sender ID that will be displayed as the “From” field for the message. (Example: “VOTO”)

  • voice_sender_id : When sending voice calls to supported destinations, you can specify a numeric phone number that will be displayed as the “From” number (Example: “12065551111”)

  • language_selector_id (optional): The ID of the language selector that will be played to subscribers who do not have a default language set

  • default_language_id (optional): ID of the language ID subscribers without languges set will recieve content in

  • Optional parameters to control which subscribers the call is sent to. If none of these are provided, the call is sent to all subscribers who are set to receive Outgoing Calls (active).

    • send_to_phones: One or more comma-separated phone numbers to send to. If subscribers do not already exist with these phone numbers, anonymous subscribers will be created.

      02xxxxxxxx,057909xxxx,2332xxxxxxxx,0402222xxxx
      
    • send_to_subscribers: A comma-separated list of subscriber ids to send to. The call will be sent to these subscribers specifically, whether or not they are set to receive Outgoing Calls.

      200301,200312,200345
      
    • groups: A comma-separated list of group ids. The call will be sent to all subscribers in these groups that are set to receive Outgoing Calls (active). If a subscriber is in more than one group, they will only receive the call once.

      200653, 200654, 200657
      

Tip

You can only specify one of groups, send_to_phones, or send_to_subscribers.

  • schedule_type (optional). Specify when the call should be sent. schedule_type can be one of ‘now’, ‘fixed’, ‘routine’, or ‘repeating’. Each option has additional parameters that should be provided when using this option. (Default is ‘now’ if not provided).

    • ‘now’ (Send the call immediately)

    • ‘fixed’ (Send the call at a fixed day and time)

      • schedule_date: 2013-09-26
      • schedule_time: 16:15
    • ‘routine’ (Send the call on a schedule linked to the subscriber’s start date)

      • routine_days : 5 (ie: Send this call 5 days after the subscriber’s start date)
      • routine_time : 16:15
    • ‘repeating’ (Send the call on a regular repeating schedule)

      • repeats: ‘daily’, ‘weekly’, ‘monthly’, or ‘yearly’
      • repeats_every (optional): skip this many of the ‘repeats’ interval (Default if not provided: 1)
      • repeat_start_date: date that the first repeating call should go (Example: ‘2015-09-26’)
      • repeat_end_type: ‘0’ (continue indefinitely), ‘1’ (ends after a number of occurrences), or ‘2’ (end on or after a specified date)
      • repeat_end_after_occurences: Number of times this call should repeat if using repeat_end_type = 1. (Example: ‘4’)
      • repeat_end_on: Date that repeating should stop, if using repeat_end_type = 2. (Example: ‘2015-10-31’)
  • retry_attempts_short (optional): VOTO can automatically retry (voice) calls after a delay if not answered. This is the maximum number of attempts made in short succession to deliver the call. (Default: 3)

  • retry_delay_short (optional): Amount of time to delay before retrying within the short retry pattern, in minutes (Default: 1)

  • retry_attempts_long (optional): Optionally, the complete short retry pattern can be repeated at longer intervals, in case a subscriber is away from the phone for a long period of time. This is maximum number of times that the short retry pattern is repeated. (Default: 1, i.e.: no repeated pattern.)

  • retry_delay_long (optional): Amount of time to delay before repeating the complete short retry pattern, in minutes. (Default: 60)

  • detect_voicemail_action: Although the telephone system doesn’t indicate a difference between a call answered by a person, and a call answered by a voicemail system, VOTO can use heuristics to detect when a call has gone to voicemail. This specifies whether voicemail detection should be enabled, and what to do if detected:

    • 0: Voicemail detection not activated
    • 1: If voicemail is detected, hang up the call. (Final delivery status will be “Failed (voicemail).”)
    • 2: If voicemail is detected, play the Response Prompts - Voicemail message and then hang up. (Final delivery status will be “Success (voicemail)”.)
  • open_time (optional) : the time of day in GMT/UTC from which queued calls and retry attempts can be delivered. If not set subscribers would recieve calls any time of day scheduled.

  • close_time (optional) : the time of day in GMT/UTC after which queued calls and retry attempts would cease to be delivered to subscribers. Calls to subscribers would resume at the next open time. If not set subscribers would recieve calls any time of day scheduled.

  • sms_interaction_expiration_hours (optional): number of hours an SMS interaction will remain active for. (Default: 48 Hours)

  • webhook_url (optional): a valid URL to send call status updates via webhooks

  • webhook_method (optional): specify a HTTP method for webhook requests (Default: GET)

  • webhook_secret (optional): specify a secret to verify webhook requests are from our service.

Returns:

ID of the outgoing call
{"status":200,"message":"Outgoing call qeued successfully","data":{id: 2345554}}

List Outgoing Calls

Method: GET

URL: https://go.votomobile.org/api/v1/outgoing_calls

Parameters:

  • api_key

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "outgoing_calls": [
          {
              "id": "236900",
              "schedule_type": "1",
              "send_to_all": "1",
              "has_sms": "1",
              "has_voice": "0",
              "message_id": null,
              "survey_id": "202385",
              "tree_id": null,
              "poll_id": "233077",
              "routine_days": null,
              "scheduled_date": "2014-09-15",
              "queued_on": "2014-09-15 14:02:21",
              "retry_attempts_short": "3",
              "retry_attempts_long": "1",
              "retry_delay_short": "1",
              "retry_delay_long": "60",
              "retry_count_short": "0",
              "retry_count_long": "0",
              "created_at": "2014-09-15 14:02:21",
              "updated_at": "2015-09-15 18:50:36",
              "webhook": {
                        "url": "https://someapi.io/webhooks/requests",
                        "method": "POST",
                        "secret": "my-app-secret"
                      }
          },
          {
              "id": "238749",
              "schedule_type": "1",
              "send_to_all": "1",
              "has_sms": "1",
              "has_voice": "0",
              "message_id": null,
              "survey_id": "202386",
              "tree_id": null,
              "poll_id": "234761",
              "routine_days": null,
              "scheduled_date": "2014-09-20",
              "queued_on": "2014-09-20 00:20:01",
              "retry_attempts_short": "3",
              "retry_attempts_long": "1",
              "retry_delay_short": "1",
              "retry_delay_long": "60",
              "retry_count_short": "0",
              "retry_count_long": "0",
              "created_at": "2014-09-20 00:20:00",
              "updated_at": "2015-09-15 18:50:36",
              "webhook": null
          }
      ]
  },
  "message": "Outgoing Calls Fetched successfully",
  "more_info": ""
}

List Details Of An Outgoing Call

Method: GET

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

Parameters:

  • api_key

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "outgoing_call": {
          "id": "236900",
          "schedule_type": "1",
          "send_to_all": "1",
          "has_sms": "1",
          "has_voice": "0",
          "message_id": null,
          "survey_id": "202385",
          "tree_id": null,
          "poll_id": "233077",
          "routine_days": null,
          "scheduled_date": "2014-09-15",
          "queued_on": "2014-09-15 14:02:21",
          "retry_attempts_short": "3",
          "retry_attempts_long": "1",
          "retry_delay_short": "1",
          "retry_delay_long": "60",
          "retry_count_short": "0",
          "retry_count_long": "0",
          "created_at": "2014-09-15 14:02:21",
          "updated_at": "2015-09-15 18:50:36",
          "webhook": {
                    "url": "https://someapi.io/webhooks/requests",
                    "method": "POST",
                    "secret": "my-app-secret"
                  }
      }
  },
  "message": "Outgoing Call Details Fetched successfully",
  "more_info": ""
}

Count Interactions (Delivery Logs) for an Outgoing Call

Count the number of delivery logs (individual subscriber interactions) associated with an Outgoing Call. You can optionally filter by delivery status and by date/time range.

Method: GET

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

Parameters:

  • api_key
  • 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.

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "outgoing_call_id": "201134",
      "filter_delivery_status": "6",
      "filter_after_date": "2014-02-15",
      "count": 4
  },
  "message": "Fetched Outgoing Call Counts: times accessed.",
  "more_info": "",
  "pagination": null,
  "url": "https://go.votomobile.org/api/v1/outgoing_calls/201134/counts?filter_delivery_status=6&filter_after_date=2014-02-15"
}

Cancel Outgoing Call

Method: DELETE

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

Parameters: Specify outgoing call id to delete

  • api_key

Returns:

{"status":200,"message":"Call Cancelled."}