Make an outbound call

This method allows you to initiate an outbound call. The call can be made to a PSTN number or a SIP endpoint. This method also enables you to make bulk calls (Simultaneous calls).

API Endpoint

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

Arguments

fromRequired

The phone number that needs to be used as the caller ID for the call. The format should be the country code followed by the number. Example: 15677654321 (for United States)

toRequired

The destination that needs to be called. The destination can either be a regular number or a SIP endpoint.

The regular number should be provided with the country code followed by the number to be called. Example: 15677654321

In case you are calling a SIP endpoint, the to field should be a valid SIP URI. Example: sip:john1234@phone.plivo.com

Multiple numbers and endpoints can be initiated at once (bulk calls) by using the delimiter <. For example in case you want to call two numbers and one SIP endpoint, the ‘to’ field can be specified as follows: 15677654321<15673464321<sip:john1234@phone.plivo.com

answer_urlRequired

The URL that will be invoked by Plivo once the call is answered. This URL should return an XML with valid Plivo XML to perform the desired actions once the call is answered

answer_method

The HTTP verb that should be used to invoke the answer_url. This defaults to POST

ring_url

An optional URL to which Plivo will notify once the call starts ringing

ring_method

The HTTP verb that should be used to invoke the ring_url. This defaults to POST

hangup_url

An optional URL to which Plivo will notify once the call is hung up

hangup_method

The HTTP verb that should be used to invoke the hangup_url. This defaults to POST

fallback_url

This is the URL that will be tried in case the answer_url is not reachable. We retry answer_url thrice to fetch a valid XML file. In case all three attempts fail to return a valid XML or after a timeout of 60 seconds whichever is earlier, fallback_url will be invoked

fallback_method

The HTTP verb that should be used to invoke the fallback_url. This defaults to POST

caller_name

Caller name to use with the call

send_digits

This flag allows you to send digits once the call is connected. The common use case is to dial to an extension. Plivo will dial the number, and when the automated system picks up, sends 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.

The duration of the tone when the digit is sent can be configured by appending the duration (in ms) with the @ character. For example setting 123@1000 will send the digits 123 with a tone duration of 1000 milliseconds

send_on_preanswer

This takes boolean values ‘true’ and ‘false’ and is applicable only if send_digits is set. In case it is set to ‘true’ the digits would be sent at preanswer stage. The default value is false.

time_limit

Sets a limit on the maximum duration of a call. The time limit is calculated starting from the time the call is answered. The time_limit is provided in seconds and it needs to be positive integer.

hangup_on_ring

Sets a limit on the maximum duration of the call 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 is also provided in seconds and it needs to be a positive integer.

machine_detection

This parameter is used to detect whether the call has been answered by a machine.

If set to ‘true’, in case 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_detection’ parameter set to true.

In case you want to hangup the call in case machine is detected, you can set this parameter to ‘hangup’. This will hangup the call and POST to the hangup_url with ‘machine_detection’ attribute set as true.

machine_detection_time

This defines the time that is allotted to decide whether machine is detected or not. This is specified in milliseconds and takes a value between 2000 and 10000 both inclusive. The default value is 5000ms

machine_detection_url

The URL which will be 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. This defaults to POST

sip_headers

List of SIP headers in the form of 'key=value' pairs, separated by commas. E.g. head1=val1,head2=val2,head3=val3,...,headN=valN.

The SIP headers specified will be automatically prefixed with “X-PH-” and these headers will be present for all the HTTP requests that are being made

The valid values allowed for SIP header keys and values are integers, uppercase and lowercase alphabets. The only special character allowed is ‘%’

ring_timeout

Defines how long an unanswered call should ring before hanging up. The timeout is provided in seconds and the default value is 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 in case of a conference.

error_if_parent_not_found

Defines the behaviour of how to use parent_call_uuid. If this is set to true, then if parent_call_uuid is not found, the call is not initiated and it returns an error. If it is set to false, then the call will be initiated ignoring any errors with the parent_call_uuid. Default value is false

Asynchronous Machine Detection

You can take any desired action on detecting a machine during a call. This can be done using the following steps.
a. Set machine_detection_url parameter while firing outbound call API.
b. Plivo will detect machine in the background and invoke the machine_detection_url with the a set of parameters which can be used to take desired action.

The request parameters to the machine_detection_url are:

List of parameters sent to machine_detection_url

From string

The from number used to initiate the call

Machine boolean

This will be set to ‘true’ if machine is detected in the call

To string

The destination that is called during the call

RequestUUID string

An identifier that can uniquely identify a call

ALegRequestUUID string

Identifies the first leg of the call in case there are multiple legs

CallUUID string

The identifier used to identify the call

IfMachine string

This parameter can be either ‘continue’ or ‘hangup’ depending on the ‘machine_detection’ parameter set while initiating the call

Direction string

The direction of the call. This will be ‘outbound’ since we currently support Machine detection only on outbound calls

ALegUUID string

An unique identifier for the A Leg of the call

Event string

The event which triggered this notification. This parameter will have the value ‘MachineDetection’

CallStatus string

The status of the call. This will be ‘in-progress’

Returns

If successful this endpoint returns an unique identifier that can be used to identify the call

Response

HTTP Status Code: 200

{
  "message": "call fired",
  "request_uuid": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f",
  "api_id": "97ceeb52-58b6-11e1-86da-77300b68f8bb"
}

Example Request

1
2
3
4
5
6
7
8
9
import plivo

client = plivo.RestClient()
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(
    '3213213213',
    ['1231231231'],
    '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();
    client.calls.create(
        "1231231231", // from
        "3213213213", // 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(
        '3213213213',
        [1231231231],
        '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();
        try {
            CallCreateResponse response = Call.creator("1231231231", Collections.singletonList("3213213213"), "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
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>{"3213213213"},
                    from:"1231231231",
                    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": "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
// Example for Call create
package main

import "fmt"
import "github.com/plivo/plivo-go"
 
func main() {
	client, err := plivo.NewClient("", "", &plivo.ClientOptions{})
	if err != nil {
		panic(err)
	}
	response, err := client.Calls.Create(
		plivo.CallCreateParams{
			From: "1231231231",
			To: "3213213213",
			AnswerURL: "http://s3.amazonaws.com/static.plivo.com/answer.xml",
			AnswerMethod: "GET",
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Response: %#v\n", response)
}