Make an Outbound Phone Call

You can make outbound phone calls to landlines, mobiles, and SIP endpoints (e.g., softphones), in any of our 200+ coverage countries.

To make a single outbound call or bulk outbound calls, make an HTTP POST request to the Call API:

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

In the tutorial below, you will make an outgoing call that will say “Congratulations! You’ve made your first outbound call!” when the call is answered. This process can be described in 4 steps:

  1. You will make an HTTP POST request to the call API: https://api.plivo.com/v1/Account/{auth_id}/Call/
  2. A call will be initiated from the 'from' parameter to the 'to' parameter as indicated by your app. These parameters will be edited in the implementation section.
  3. Plivo will request a valid XML from the answer_url. In this tutorial, when the call is answered, Plivo will play the message “Congratulations! You’ve made your first outbound call!” from a simple text-to-speech app. To simplify a few steps, we already hosted the text-to-speech app at https://s3.amazonaws.com/static.plivo.com/answer.xml. In future tutorials, we will show you how to create your own call and routing logics (e.g., playing a pre-recorded mp3 upon answering).
  4. Plivo will automatically hang up after the message is played.
    Advanced Hack: Each API has many parameters built into it that do specific things. Head to the Parameters section to see how you can get Plivo to return more details regarding the call.

Prerequisites

  1. Sign up for a free Plivo trial account.
  2. Check out our Helper Libraries page and install the right helper based on the programming language you want to use.
  3. Buy a Plivo phone number (optional).
    Note: A phone number is required only for receiving calls. However, country-specific carrier conditions may still apply. You can buy a phone number through the Buy Numbers tab on your Plivo account UI.
  4. Unlike other tutorials, making simple outbound calls does not require a web server.

Implementation

  1. Copy the relevant code below into a text file and save it. Let’s call it make_calls.
    Note: Make sure to use the appropriate file extention for your code (e.g., make_calls.py for Python).
  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, which will show up as your Caller ID.
    Note: Be sure that all phone numbers are formatted to 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).
    Note: If you are using a Plivo Trial account, you can only make calls to phone numbers that have been verified with Plivo. Phone numbers can be verified through the Sandbox Numbers page in your Plivo account.

Code

 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
import plivo, plivoxml

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

p = plivo.RestAPI(auth_id, auth_token)

params = {
    'to': '2222222222',    # The phone numer to which the call will be placed
    'from' : '1111111111', # The phone number to be used as the caller id

    # answer_url is the URL invoked by Plivo when the outbound call is answered
    # and contains instructions telling Plivo what to do with the call
    'answer_url' : "https://s3.amazonaws.com/static.plivo.com/answer.xml",
    'answer_method' : "GET", # The method used to call the answer_url

    # Example for asynchronous request
    # callback_url is the URL to which the API response is sent.
    #'callback_url' => "http://myvoiceapp.com/callback/",
    #'callback_method' => "GET" # The method used to notify the callback_url.
}

# Make an outbound call and print the response
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
21
22
23
24
25
26
27
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',   # The phone numer to which the call will be placed
    'from' => '1111111111', # The phone number to be used as the caller id

    # answer_url is the URL invoked by Plivo when the outbound call is answered
    # and contains instructions telling Plivo what to do with the call
    'answer_url' => 'https://s3.amazonaws.com/static.plivo.com/answer.xml',
    'answer_method' => 'GET', # The method used to call the answer_url

    # Example for asynchronous request
    # callback_url is the URL to which the API response is sent.
    #'callback_url' => "http://myvoiceapp.com/callback/",
    #'callback_method' => "GET" # The method used to notify the callback_url.
}

# Make an outbound call and print the response
response = p.make_call(params)
print 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
var plivo = require('plivo');
var p = plivo.RestAPI({
  authId: 'Your AUTH_ID',
  authToken: 'Your AUTH_TOKEN'
});

var params = {
    'to': '2222222222',    // The phone numer to which the call will be placed
    'from' : '1111111111', // The phone number to be used as the caller id

    // answer_url is the URL invoked by Plivo when the outbound call is answered
    // and contains instructions telling Plivo what to do with the call
    'answer_url' : "https://s3.amazonaws.com/static.plivo.com/answer.xml",
    'answer_method' : "GET", // The method used to call the answer_url

    // Example for asynchronous request
    // callback_url is the URL to which the API response is sent.
    // 'callback_url' : "http://myvoiceapp.com/callback/",
    // 'callback_method' : "GET" // The method used to notify the callback_url.
};

// Make an outbound call and print the response
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
18
19
20
21
22
23
24
25
<?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',   # The phone numer to which the call will be placed
        'from' => '1111111111', # The phone number to be used as the caller id

        # answer_url is the URL invoked by Plivo when the outbound call is answered
        # and contains instructions telling Plivo what to do with the call
        'answer_url' => "https://s3.amazonaws.com/static.plivo.com/answer.xml",
        'answer_method' => "GET", # The method used to call the answer_url

        # Example for asynchronous request
        # callback_url is the URL to which the API response is sent.
        #'callback_url' => "http://myvoiceapp.com/callback/",
        #'callback_method' => "GET" # The method used to notify the callback_url.
    );

    # Make an outbound call and print the response
    $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
36
37
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.Call;
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"); // 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

        // answer_url is the URL invoked by Plivo when the outbound call is answered
        // and contains instructions telling Plivo what to do with the call
        parameters.put("answer_url","https://s3.amazonaws.com/static.plivo.com/answer.xml");
        parameters.put("answer_method","GET"); // method to invoke the answer_url

        // Example for asynchronous request
        // callback_url is the URL to which the API response is sent.
        // parameters.put("callback_url","http://myvoiceapp.com/callback/");
        // parameters.put("callback_method","GET"); // The method used to notify the callback_url.
        try {
            // Make an outbound call and print the response
            Call resp = api.makeCall(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
30
31
32
33
34
35
36
using System;
using System.Collections.Generic;
using RestSharp;
using Plivo.API;

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

            // Make an outbound call
            IRestResponse<Call> resp = plivo.make_call(new Dictionary<string, string>()
            {
                { "from", "1111111111" }, // The phone numer to which the call will be placed
                { "to", "2222222222" }, // The phone number to be used as the caller id
                // answer_url is the URL invoked by Plivo when the outbound call is answered
                // and contains instructions telling Plivo what to do with the call
                { "answer_url", "https://s3.amazonaws.com/static.plivo.com/answer.xml" },
                { "answer_method","GET"}, // The method used to invoke the answer_url

                // Example for asynchronous request
                // callback_url is the URL to which the API response is sent.
                // {"callback_url","http://myvoiceapp.com/callback/"},
                // {"callback_method","GET"}
            });

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

            Console.ReadLine();
        }
    }
}
1
2
3
4
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"to": "2222222222","from": "1111111111", "answer_url": "https://s3.amazonaws.com/static.plivo.com/answer.xml", "answer_method": "GET"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/

Sample Response

Sample output - Synchronous Request
(201, {
       u'message': u'call fired',
       u'request_uuid': u'85b1d45d-bc12-47f5-89c7-ae4a2c5d5713',
       u'api_id': u'ad0e27a8-9008-11e4-b932-22000ac50fac'
   }
)

Sample output - Asynchronous Request
(201, {
       u'message': u'async api spawned',
       u'api_id': u'ad0e27a8-9008-11e4-b932-22000ac50fac'
   }
)

Call Logs in your Plivo Account

After the call is completed, you may login to your Plivo account and see all the call details (e.g., when the call was initiated, answered, and ended). The Plivo Call API also allows you to retrieve all live and completed call details through our APIs. This powerful API has allowed our customers to add call analytics dashboards in their own applications.

Parameters sent to the answer_url

Once the call is initiated, Plivo will request a valid XML from the answer_url. The following parameters are sent to the answer_url. You can add any of them to the parameters list to have Plivo respond with specific outputs. For example, adding the CallStatus will show whether the call is completed, busy, failed, timeout or no-answer (i.e., not answered).

Parameter Description
CallUUID A unique identifier for this call.
From This is the phone number you specified as the caller ID.
To This is the phone number you specified as the caller ID.
CallStatus Indicates the status of the call. The value is set to either completed,busy, failed, timeout or no-answer.
Direction Indicates the direction of the call. The direction will be outbound
ALegUUID This contains a unique identifier which identifies the first leg of the call.
ALegRequestUUID Contains a unique request identifier which is returned by Plivo.

Asynchronous Requests

All requests to Plivo APIs 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 requests, add the callback_url and callback_method to the parameter list in the code above. For simplicity, we’ve already added this to the code. Just uncomment the appropriate lines to initiate asynchronous calls.
  2. 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.

Next Step

Learn how to greet a caller with a customized Text-to-Speech message.

  1. Make an Outbound Call
  2. Play a Text-to-speech Message
  3. Connect Call to a Second Person
  4. Greet Caller by Name
  5. Play MP3/WAV Audio to Caller
  6. Hangup Using API
  7. Receive Incoming Call
  8. Forward Incoming Call
  9. Record Using API
  10. Screen Incoming Call
  11. Reject incoming call
  12. Get Details of all Calls
  13. Get Details of a single Call
  14. Get Details of Live Calls
  15. Build an IVR Phone Menu
  16. Conference Call
  17. Call Forward
  18. SIP Endpoint (Direct-Dial)
  19. Inbound Trunk
  20. Outbound Trunk