Latest Legacy

Make an outbound call

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