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

    If set to a string, caller name will be set to this string value.

    Allowed values - Any string. Defaults to Caller's caller_name.

    Character limit - 50 characters.

    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. Defaults to 14400 seconds(4 hours)

    Note: If the value set is >=86400 seconds, then calls will be disconnected after 24 hours.
    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’ 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’ parameter 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)
    }