Making an Outbound Call

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.

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:

You will make an HTTP POST request to the call API: https://api.plivo.com/v1/Account/{auth_id}/Call/

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.

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

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

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.

Unlike other tutorials, making simple outbound calls does not require a web server.

Implementation

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

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

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

importplivo,plivoxmlauth_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)printstr(response)

require'rubygems'require'plivo'includePlivoAUTH_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 responseresponse=p.make_call(params)printresponse

varplivo=require('plivo');varp=plivo.RestAPI({authId:'Your AUTH_ID',authToken:'Your AUTH_TOKEN'});varparams={'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 responsep.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
26

<?phprequire'vendor/autoload.php';usePlivo\RestAPI;$auth_id="Your AUTH_ID";$auth_token="Your AUTH_TOKEN";$p=newRestAPI($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);?>

packagecom.plivo.test;importjava.lang.reflect.Field;importjava.lang.reflect.Modifier;importjava.util.LinkedHashMap;importcom.plivo.helper.api.client.*;importcom.plivo.helper.api.response.call.Call;importcom.plivo.helper.exception.PlivoException;publicclassApp{publicstaticvoidmain(String[]args)throwsIllegalAccessException{Stringauth_id="Your AUTH_ID";Stringauth_token="Your AUTH_TOKEN";RestAPIapi=newRestAPI(auth_id,auth_token,"v1");LinkedHashMap<String,String>parameters=newLinkedHashMap<String,String>();parameters.put("to","2222222222");// The phone numer to which the all has to be placedparameters.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 callparameters.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 responseCallresp=api.makeCall(parameters);System.out.println(resp);}catch(PlivoExceptione){System.out.println(e.getLocalizedMessage());}}}

usingSystem;usingSystem.Collections.Generic;usingRestSharp;usingPlivo.API;namespacemake_calls{classProgram{staticvoidMain(string[]args){RestAPIplivo=newRestAPI("Your AUTH_ID","Your AUTH_TOKEN");// Make an outbound callIRestResponse&lt;Call&gt;resp=plivo.make_call(newDictionary&lt;string,string&gt;(){{"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 responseConsole.Write(resp.Content);Console.ReadLine();}}}

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

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.

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.