Make an outbound call

Latest Legacy

This method lets you initiate an outbound call to a PSTN number or a SIP endpoint, and make simultaneous bulk calls.

API Endpoint

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

Arguments

fromRequired	The phone number to be used as the caller ID for the call. The format should be the country code followed by the number. Example: 14157654321 (for the United States)
toRequired	The destination to be called. The destination can be either a regular number or a SIP endpoint. A regular number should be specified with the country code followed by the number. Example: 14157654321 If you’re calling a SIP endpoint, the to field should be a valid SIP URI. Example: sip:john1234@phone.plivo.com You can initiate calls to multiple numbers and endpoints at once (bulk calls) by using the delimiter <. For example, if you want to call two numbers and one SIP endpoint, specify in the to field: 14157654321<14153464321<sip:john1234@phone.plivo.com Note: The maximum number of unique destinations accepted in the "to" field is 1000.
answer_urlRequiredCallback-retry configurable	The URL invoked by Plivo when the call is answered. This URL should return an XML element with valid Plivo XML to perform the desired actions.
answer_method	The HTTP verb that should be used to invoke the answer_url. Defaults to POST.
ring_url Callback-retry configurable	An optional URL that Plivo notifies when the call starts ringing.
ring_method	The HTTP verb that should be used to invoke the ring_url. Defaults to POST.
hangup_url Callback-retry configurable	An optional URL that Plivo notifies when the call is hung up.
hangup_method	The HTTP verb that should be used to invoke the hangup_url. Defaults to POST.
fallback_url Callback-retry configurable	The URL that’s tried if the answer_url is not reachable. We retry answer_url three times to fetch a valid XML file. If all three attempts fail to return a valid XML file, or after a timeout of 60 seconds, whichever is earlier, fallback_url is invoked.
fallback_method	The HTTP verb that should be used to invoke the fallback_url. Defaults to POST.
caller_name	If set to a string, caller name will be set to this string value. Allowed values: Any string. Character limit — 50 characters. Defaults to Caller's caller_name.
send_digits	Flag that lets you send digits once the call is connected. The common use case is to dial to an extension. Plivo can dial a number, and when the automated system picks up, send the DTMF tones to connect to the extension. You can choose how long to wait before sending the digits. Using character w waits for 0.5 seconds and W waits for 1 seconds. For example, setting this parameter to 1w2W3 sends digit 1, waits for 0.5 seconds, sends digit 2, waits for 1 second, and sends digit 3. You can configure the duration of the tone when the digit is sent by appending the duration (in milliseconds) with the @ character. For example, setting 123@1000 will send the digits 123 with a tone duration of 1,000 milliseconds
send_on_preanswer	Applicable only if send_digits is set. If set to true, the digits are sent at the preanswer stage. Defaults to false.
time_limit	Sets a limit on the maximum duration of a call in seconds. The limit is calculated starting from the time the call is answered. The time_limit must be a positive integer. Defaults to 14,400 seconds (4 hours).
Note: If the value set is >=86400 seconds, calls will be disconnected after 24 hours.
hangup_on_ring	Sets a limit on the maximum duration of the call in seconds, similar to time_limit, but instead of calculating the limit from the time call is answered, this parameter calculates the limit from the time call starts ringing. The hangup_on_ring value must be a positive integer.
machine_detection	Detects whether the call has been answered by a machine. Allows values: true, hangup If set to true, then if a machine is detected at the beginning of the call, any URL that is invoked by the call (answer_url, hangup_url, etc.) will be POSTed with the machine parameter set to true. If you want to hang up the call if a machine is detected, set this parameter to hangup. This will hang up the call and POST to the hangup_url with the machine parameter set to machine_detection.
machine_detection_time	Defines the time allotted, in milliseconds, to decide whether a machine is detected. Allowed values: 2000 through 10000 Defaults to 5000.
machine_detection_url Callback-retry configurable	The URL invoked with machine detection parameters. The list of parameters sent with the request are described in asynchronous machine detection section below. These parameters should be used to make machine detection asynchronous.
machine_detection_method	The HTTP verb that should be used to invoke the machine_detection_url. Defaults to POST.
machine_detection_maximum_speech_length	The number of milliseconds used to measure the length of speech activity. Note that machine_detection_maximum_speech_length must be a positive integer. Durations greater than this value will be detected as machine. Default: 5000 Allowed values: Between 1000 to 6000
machine_detection_initial_silence	The duration of initial silence when the call is answered, expressed in milliseconds. Note that machine_detection_initial_silence must be a positive integer. “Unknown” will be returned after the specified value. Default: 4500 Allowed values: Between 2000 to 10000
Machine_detection_maximum_words	The maximum number of sentences detected. Machine_detection_maximum_words must be a positive integer. Values greater than the threshold you set will be classified as a machine. Default: 3 Allowed values: Between 2 to 10
Machine_detection_initial_greeting	Indicates the maximum length of the initial greeting in milliseconds. Machine_detection_initial_greeting must be a positive integer. Duration longer than this value will be detected as a machine. Default: 1500 Allowed values: Between 1000 to 5000
Machine_detection_silence	The silence after the initial greeting, expressed in milliseconds. Machine_detection_silence must be a positive integer. Durations greater than this value will be detected as a human. Default: 800 Allowed values: Between 500 to 5000
sip_headers	List of SIP headers in the form of key=value pairs, separated by commas — for example, head1=val1,head2=val2,head3=val3,...,headN=valN. The SIP headers specified are automatically prefixed with “X-PH-” and these headers will be present for all the HTTP requests that are being made Valid values for SIP header keys and values are integers and uppercase and lowercase letters.
ring_timeout	Defines how long in seconds an unanswered call should ring before hanging up. Defaults to 120.
parent_call_uuid	The call_uuid of the first leg in an ongoing conference. This parameter is helpful in minimizing the delay of adding a new member to a conference.
Note: This parameter is honored only for single calls and not for bulk calls. See this post for more information.
error_if_parent_not_found	Defines the behavior of how to use parent_call_uuid. If set to true, then if parent_call_uuid is not found, the call is not initiated and it returns an error. If set to false, then the call is initiated ignoring any errors with the parent_call_uuid. Defaults to false.

Callbacks

For every single voice call you make and receive, Plivo sends a status update to your URL configured as a callback. You can read and store the information on your server for analysis, and you can change the flow of ongoing calls based on the values received in the callback events.

Callbacks involve URLs such as answer_url, fallback_url, hangup_url, and ring_url.

List of parameters sent to ring_url

Fromstring	The from number used as the caller ID to initiate the call.
Tostring	The destination that’s called.
RequestUUIDstring	An identifier that can uniquely identify a request.
ALegRequestUUIDstring	Identifies the first leg of the call in case there are multiple legs.
CallUUIDstring	The identifier of the call.
Directionstring	The direction of the call. This will have the value “outbound” since this is an outbound API call.
Eventstring	The event that triggered this notification. This will have the value “Ring”.
CallStatusstring	The status of the call. This will have the value “ringing”.
SessionStartstring	A timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
STIRAttestationstring	Gives details about the attestation assigned to the call by Plivo.

List of parameters sent to answer_url and fallback_url

Fromstring	The from number used as the caller ID to initiate the call.
Tostring	The destination that’s called.
RequestUUIDstring	An identifier that can uniquely identify a call.
ALegRequestUUIDstring	Identifies the first leg of the call in case there are multiple legs.
CallUUIDstring	The identifier of the call.
Directionstring	The direction of the call. This will have the value “outbound” since this is an outbound API call.
ALegUUIDstring	An unique identifier for the A leg of the call.
Eventstring	The event that triggered this notification. This will have the value “StartApp”.
stir_verification string	For outbound calls: Gives details about the attestation assigned to the call by Plivo For inbound calls: Gives details about the attestation received on the inbound call to your Plivo phone number. Possible values: Verified means the call is from a verified caller who has authorized access to the customer’s caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A. Not Verified means that, for this call, either the caller is not verified, or it’s uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C. Not Applicable means STIR/SHAKEN doesn’t apply to this call, as would be the case if a call is not addressed to a US number or if it’s a cloud call (WebRTC or SIP). Read more about STIR/SHAKEN.
CallStatusstring	The status of the call. This will have the value “in-progress”.
SessionStartstring	A timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
STIRAttestationstring	Gives details about the attestation assigned to the call by Plivo.

List of parameters sent to hangup_url

Fromstring	The from number used as the caller ID to initiate the call.
Tostring	The destination that’s called.
RequestUUIDstring	An identifier that can uniquely identify a call.
ALegRequestUUIDstring	Identifies the first leg of the call in case there are multiple legs
CallUUIDstring	The identifier of the call.
Directionstring	The direction of the call. This will be “outbound” since this is an outbound API call.
ALegUUIDstring	An unique identifier for the A leg of the call.
Eventstring	The event that triggered this notification. This will have the value “Hangup”.
stir_verification string	For outbound calls: Gives details about the attestation assigned to the call by Plivo For inbound calls: Gives details about the attestation received on the inbound call to your Plivo phone number. Possible values: Verified means the call is from a verified caller who has authorized access to the customer’s caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A. Not Verified means that, for this call, either the caller is not verified, or it’s uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C. Not Applicable means STIR/SHAKEN doesn’t apply to this call, as would be the case if a call is not addressed to a US number or if it’s a cloud call (WebRTC or SIP). Read more about STIR/SHAKEN.
CallStatusstring	The status of the call. This will have the value “completed”.
StartTimestring	A timestamp that indicates when the call was initiated. Timezone: Local timezone as updated in your Plivo Console Format: yyyy-MM-dd HH:mm:ss.
AnswerTimestring	A timestamp that indicates when the call was answered. Timezone: Local timezone as updated in your Plivo Console Format: yyyy-MM-dd HH:mm:ss.
SessionStartstring	A timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
EndTimestring	A timestamp that indicates when the call ended. Timezone: Local timezone as updated in your Plivo Console Format: yyyy-MM-dd HH:mm:ss.
STIRAttestationstring	Gives details about the attestation assigned to the call by Plivo.

Example Request

1
2
3
4
5
6
7
8
9
import plivo

client = plivo.RestClient('<auth_id>','<auth_token>')
response = client.calls.create(
    from_='+12025550000',
    to_='+12025551111',
    answer_url='https://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
require 'rubygems'
require 'plivo'

include Plivo
include Plivo::Exceptions

api = RestClient.new("<auth_id>","<auth_token>")

begin
  response = api.calls.create(
    '+12025550000',
    ['+12025551111'],
    'https://s3.amazonaws.com/static.plivo.com/answer.xml',
     {
            answer_method: "GET",
     },
  )
  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';
    
   // If auth id and auth token are not specified, Plivo will fetch them from the environment variables.
    var client = new plivo.Client("<auth_id>","<auth_token>");
    client.calls.create(
        "+12025550000", // from
        "+12025551111", // to
        "https://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
<?php
/**
 * Example for Call create
 */
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");
try {
    $response = $client->calls->create(
        '+12025550000',
        ['+12025551111'],
        'https://s3.amazonaws.com/static.plivo.com/answer.xml',
        [
            'answer_method' => '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("<auth_id>","<auth_token>");
        try {
            CallCreateResponse response = Call.creator("+12025550000", Collections.singletonList("+12025551111"), "https://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
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("<auth_id>","<auth_token>");
            try
            {
                var response = api.Call.Create(
                    to:new List<String>{"+12025551111"},
                    from:"+12025550000",
                    answerMethod:"GET",
                    answerUrl:"https://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": "+12025551111","from": "+12025550000", "answer_url": "https://s3.amazonaws.com/static.plivo.com/answer.xml", "answer_method": "GET"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/

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
// Example for Call create
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.Calls.Create(
		plivo.CallCreateParams{
			From:         "+12025550000",
			To:           "+12025551111",
			AnswerURL:    "https://s3.amazonaws.com/static.plivo.com/answer.xml",
			AnswerMethod: "GET",
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Example Request

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' => "https://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' => "https://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' : "https://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' => "https://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","https://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","https://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/

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
    // Example for Call create
package main

import (
	"fmt"

	"github.com/plivo/plivo-go/v7"
)

func main() {
	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	response, err := client.Calls.Create(
		plivo.CallCreateParams{
			From:         "+12025550000",
			To:           "+12025551111",
			AnswerURL:    "https://s3.amazonaws.com/static.plivo.com/answer.xml",
			AnswerMethod: "GET",
		},
	)
	if err != nil {
		fmt.Print("Error", err.Error())
		return
	}
	fmt.Printf("Response: %#v\n", response)
}

Rate this page

🥳 Thank you! It means a lot to us!