Make Multiple (Bulk) Outbound Calls

A unique feature of Plivo’s REST APIs is that you can make bulk (multiple) calls using a single API request. To make bulk calls, make an HTTP POST request to the Call API similar to placing a single outbound call, with the additional step of adding multiple ‘to’ destination numbers by separating each phone number with the “<” character. To make a bulk call to phone(s) or SIP endpoint(s), we will be making a POST request to the Plivo Call API:

POST https://api.plivo.com/v1/Account/{auth_id}/Call/

Prerequisites

Sign up for a free Plivo trial account.
Check out our server-side SDKs page and install the right helper based on the programming language you want to use.
Buy a Plivo phone number (optional).
Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to host your web application.

Implementation

Copy the relevant code below into a text file and save it.

Note: Be sure to save it with the appropriate file extension for your language (i.e., `.py` for Python or `.rb` for Ruby, etc.).
Replace Your AUTH_ID and Your AUTH_TOKEN with the AUTH ID and AUTH TOKEN found on your Plivo dashboard.
Add your 'from' (source) phone number. This will show up as your Sender ID. Be sure that all phone numbers include country code, area code, and phone number without spaces or dashes (e.g., 14153336666).
Add your 'to' (destination) phone numbers. These are the phone numbers you wish to call to. To place calls in bulk, separate your destination phone numbers with the “<” character (e.g., 14156667777<14157778888<14158889999). Be sure that all phone numbers include country code, area code, and phone number without spaces or dashes (e.g., 14153336666).

Note: If you are using a trial account, your destination number needs to be verified with Plivo. Phone numbers can be verified at the Sandbox Numbers page.
Edit the 'answer_url' field with your hosted url which is invoked by Plivo when the call is answered.
Edit the 'answer_method' field with either GET or POST.

Code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import plivo, plivoxml
import plivo

auth_id = "Your AUTH_ID"
auth_token = "Your AUTH_TOKEN"

p = plivo.RestAPI(auth_id, auth_token)

params = {
    'to': '2222222222<3333333333', # The phone numers to which the all has to be placed. The numbers are separated by "<" delimiter.
    'from' : '1111111111', # The phone number to be used as the caller id
    'answer_url' : "https://s3.amazonaws.com/static.plivo.com/speak.xml", # The URL invoked by Plivo when the outbound call is answered
    'answer_method' : "GET", # The method used to call the answer_url
}

# Make an outbound call
response = p.make_call(params)

print str(response)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
require 'rubygems'
require 'plivo'
include Plivo

AUTH_ID = "Your AUTH_ID"
AUTH_TOKEN = "Your AUTH_TOKEN"


p = RestAPI.new(AUTH_ID, AUTH_TOKEN)

params = {
    'to' => '2222222222<3333333333', # The phone number to which the call has to be placed separated by "<" delimiter
    'from' => '1111111111', # The phone number to be used as the caller id
    'answer_url' => 'https://s3.amazonaws.com/static.plivo.com/speak.xml', # The URL invoked by Plivo when the outbound call is answered
    'answer_method' => 'GET', # The method used to call the answer_url
}

response = p.make_call(params)
print response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var plivo = require('plivo');
var p = plivo.RestAPI({
    "authId": "auth id comes here",
    "authToken": "auth token comes here",
});
var params = {};
params.from = "1111111111";
params.to = "2222222222<3333333333";
params.answer_url = "https://s3.amazonaws.com/static.plivo.com/speak.xml";

p.make_call(params, function (status, response) {
    console.log('Status: ', status);
    console.log('API Response:\n', response);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php
    require 'vendor/autoload.php';
    use Plivo\RestAPI;
    $auth_id = "Your AUTH_ID";
    $auth_token = "Your AUTH_TOKEN";
    $p = new RestAPI($auth_id, $auth_token);
    $params = array(
        'to' => '2222222222<3333333333', # The phone numer to which the all has to be placed
        'from' => '1111111111', # The phone number to be used as the caller id
        'answer_url' => "https://s3.amazonaws.com/static.plivo.com/answer.xml", # The URL invoked by Plivo when the outbound call is answered
        'answer_method' => "GET", # The method used to call the answer_url
    );
    $response = $p->make_call($params);
    print_r ($response);

?>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
package com.plivo.test;

import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
import java.util.LinkedHashMap;

import com.plivo.helper.api.client.*;
import com.plivo.helper.api.response.call.BulkCall;
import com.plivo.helper.exception.PlivoException;

public class App {
    public static void main(String[] args) throws IllegalAccessException {

        String auth_id = "Your AUTH_ID";
        String auth_token = "Your AUTH_TOKEN";

        RestAPI api = new RestAPI(auth_id, auth_token, "v1");


        LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
        parameters.put("to","2222222222<3333333333"); // The phone numer to which the all has to be placed
        parameters.put("from","1111111111"); // The phone number to be used as the caller id
        parameters.put("answer_url","https://s3.amazonaws.com/static.plivo.com/speak.xml"); // The URL invoked by Plivo when the outbound call is answered
        parameters.put("answer_method","GET"); // method to invoke the answer_url

        try {
            // Make outbound calls
           BulkCall resp = api.makeBulkCall(parameters);
           System.out.println(resp);  
        }catch (PlivoException e){  
           System.out.println(e.getLocalizedMessage());
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
using System;
using System.Collections.Generic;
using RestSharp;
using Plivo.API;

namespace bulk_calls
{
    class Program
    {
        static void Main(string[] args)
        {
            RestAPI plivo = new RestAPI("Your AUTH_ID", "Your AUTH_TOKEN");

            IRestResponse&lt;Call&gt; resp = plivo.make_call(new Dictionary&lt;string, string&gt;()
            {
                { "from", "1111111111" }, // The phone number to which the call has to be placed
                { "to", "2222222222<3333333333" }, // The phone number to be used as the caller Id
                { "answer_url", "https://s3.amazonaws.com/static.plivo.com/speak.xml" }, // The URL invoked by Plivo when the outbound call is answered
                { "answer_method","GET"}, // The method used to invoke the answer_url
            });

            //Prints the response
            Console.Write(resp.Content);

            Console.ReadLine();
        }
    }
}

1
2
3
4
5
curl -i --user AUTH_ID:AUTH_TOKEN
    -H "Content-Type: application/json"
    -d '{"to": "2222222222<3333333333","from": "1111111111", "answer_url": "https://s3.amazonaws.com/static.plivo.com/speak.xml", "answer_method": "GET"}'
    https://api.plivo.com/v1/Account/{auth_id}/Call/

Test it Out

To make a bulk call, make an HTTP POST request to Plivo. If successful, Plivo will queue your call to your recipients at a base rate of 1 call per second.

Advanced hack: Check out our full Call API docs to see all the parameters you can use.

Sample Response

(202, {
        u'message': u'call fired',
        u'request_uuid': [
            u'd7fa180c-9501-11e4-a4d0-3f7813869e0a',
            u'd7fa180c-9501-11e4-a4d0-3f7813869e1a'
        ],
        u'api_id': u'be50302a-9502-11e4-a0ec-fd067af138be'
    }
)

Asynchronous Request

All requests to Plivo API can be made asynchronous by adding the parameters listed below. When an asynchronous call is made, Plivo will return a generic response with the api_id and the API responses will be sent to the callback URL

To send asynchronous request, uncomment 'callback_url' and 'callback_method' in the code snippet above.
Edit the 'callback_url' field with your hosted url which is notified by the API, when the response is available and to which the response is sent.
Edit the 'callback_method' field with either GET or POST.

Next Step

Learn how to Pass Custom SIP Headers