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

    1. Sign up for a free Plivo trial account.
    2. Check out our server-side SDKs page and install the right helper based on the programming language you want to use.
    3. Buy a Plivo phone number (optional).
    4. 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

    1. 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.).
    2. Replace Your AUTH_ID and Your AUTH_TOKEN with the AUTH ID and AUTH TOKEN found on your Plivo dashboard.
    3. 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).
    4. 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.
    5. Edit the 'answer_url' field with your hosted url which is invoked by Plivo when the call is answered.
    6. Edit the 'answer_method' field with either GET or POST.

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    import plivo
    
    client = plivo.RestClient()
    response = client.calls.create(
        from_='+14151234567',
        to_='+15671234567<+15671234863',
        answer_url='http://s3.amazonaws.com/static.plivo.com/answer.xml',
        answer_method='GET', )
    print(response)
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    
    #
    # Example for Call Create
    #
    require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN")
    
    begin
      response = api.calls.create(
        '+14151234567',
        ['+15671234567','+15671234863'],
        'http://s3.amazonaws.com/static.plivo.com/answer.xml'
      )
      puts response
    rescue PlivoRESTError => e
      puts 'Exception: ' + e.message
    end
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
    // Example for Call create
    
    var plivo = require('plivo');
    
    (function main() {
        'use strict';
        
        // As the auth_id and auth_token are unspecified, Plivo will fetch them from the PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN environment variables.
        var client = new plivo.Client();
        client.calls.create(
            "+14151234567", // from
            "+15671234567<+15671234863", // to
            "http://s3.amazonaws.com/static.plivo.com/answer.xml", // answer url
            {
                answerMethod: "GET",
            },
        ).then(function (response) {
            console.log(response);
        }, function (err) {
            console.error(err);
        });
    })();
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    <?php
    /**
     * Example for Call create
     */
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    $client = new RestClient("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN");
    try {
        $response = $client->calls->create(
            '+14151234567',
            ['+15671234567<+15671234863'],
            'http://s3.amazonaws.com/static.plivo.com/answer.xml',
            'GET',
        );
        print_r($response);
    }
    catch (PlivoRestException $ex) {
        print_r($ex);
    }
    
    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
    
    package com.plivo.api.samples.call;
    
    import java.io.IOException;
    import java.util.Collections;
    
    import com.plivo.api.Plivo;
    import com.plivo.api.exceptions.PlivoRestException;
    import com.plivo.api.models.call.Call;
    import com.plivo.api.models.call.CallCreateResponse;
    
    /**
    * Example for Call create
    */
    class CallCreate {
        public static void main(String [] args) {
            Plivo.init();
            try {
                CallCreateResponse response = Call.creator("+14151234567", Collections.singletonList("+15671234567<+15671234863"), "http://s3.amazonaws.com/static.plivo.com/answer.xml")
                    .answerMethod("GET")
                    .create();
    
                System.out.println(response);
            } catch (PlivoRestException | IOException e) {
                e.printStackTrace();
            }
        }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    
    // Example for Call create
    package main
    
    import "fmt"
    import "github.com/plivo/plivo-go"
     
    func main() {
    	client, err := plivo.NewClient("", "", &plivo.ClientOptions{})
    	if err != nil {
    		panic(err)
    	}
    	response, err := client.Calls.Create(
    		plivo.CallCreateParams{
    			From: "+14151234567",
    			To: "+15671234567<+15671234863",
    			AnswerURL: "http://s3.amazonaws.com/static.plivo.com/answer.xml",
    			AnswerMethod: "GET",
    		},
    	)
    	if err != nil {
    		panic(err)
    	}
    	fmt.Printf("Response: %#v\n", 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
    
    /**
     * Example for Call Create
     */
    using System;
    using System.Collections.Generic;
    using Plivo;
    using Plivo.Exception;
    
    namespace PlivoExamples
    {
        internal class Program
        {
            public static void Main(string[] args)
            {
                var api = new PlivoApi("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN");
                try
                {
                    var response = api.Call.Create(
                        to:new List<String>{"+15671234567","+15671234863"},
                        from:"+14151234567",
                        answerMethod:"GET",
                        answerUrl:"http://s3.amazonaws.com/static.plivo.com/answer.xml"
                    );
                    Console.WriteLine(response);
                }
                catch (PlivoRestException e)
                {
                    Console.WriteLine("Exception: " + e.Message);
                }
            }
        }
    }
    
    1
    2
    3
    4
    
    curl -i --user AUTH_ID:AUTH_TOKEN \
        -H "Content-Type: application/json" \
        -d '{"to": "+15671234567<+15671234863","from": "+14151234567", "answer_url": "https://s3.amazonaws.com/static.plivo.com/answer.xml", "answer_method": "GET"}' \
        https://api.plivo.com/v1/Account/{auth_id}/Call/
    

    Test and validate

    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

    1. To send asynchronous request, uncomment 'callback_url' and 'callback_method' in the code snippet above.
    2. 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.
    3. Edit the 'callback_method' field with either GET or POST.