Make Outbound Calls

    This guide helps you implement your first outgoing call with Plivo. This example shows you how to make an outgoing call to a phone number of your choice and greet the user once they answer the call.

    Voice call flow

    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 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).
      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
    
    import plivo
    
    client = plivo.RestClient('YOUR_AUTH_ID','YOUR_AUTH_TOKEN')
    response = client.calls.create(
        from_='from_number',
        to_='to_number',
        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'],
        '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("YOUR_AUTH_ID","YOUR_AUTH_TOKEN");
        client.calls.create(
            "+14151234567", // from
            "+15671234567", // 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
    21
    22
    23
    
    <?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'],
            'http://s3.amazonaws.com/static.plivo.com/answer.xml',
            'GET',
            [
            	'ring_url' => 'http://WWW.RING.URL',
            ]
        );
        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("YOUR_AUTH_ID","YOUR_AUTH_TOKEN");
            try {
                CallCreateResponse response = Call.creator("+14151234567", Collections.singletonList("+15671234567"), "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("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN", &plivo.ClientOptions{})
    	if err != nil {
    		panic(err)
    	}
    	response, err := client.Calls.Create(
    		plivo.CallCreateParams{
    			From: "+14151234567",
    			To: "+15671234567",
    			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"},
                        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","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/
    

    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).

    ParameterDescription
    CallUUIDA unique identifier for this call.
    FromThis is the phone number you specified as the caller ID.
    ToThis is the phone number you specified as the caller ID.
    CallStatusIndicates the status of the call. The value is set to either completed,busy, failed, timeout or no-answer.
    DirectionIndicates the direction of the call. The direction will be outbound
    ALegUUIDThis contains a unique identifier which identifies the first leg of the call.
    ALegRequestUUIDContains 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.