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.

    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

    FromstringThe from number used as the caller ID to initiate the call.
    TostringThe destination that’s called.
    RequestUUIDstringAn identifier that can uniquely identify a request.
    ALegRequestUUIDstringIdentifies the first leg of the call in case there are multiple legs.
    CallUUIDstringThe identifier of the call.
    DirectionstringThe direction of the call. This will have the value “outbound” since this is an outbound API call.
    EventstringThe event that triggered this notification. This will have the value “Ring”.
    CallStatusstringThe status of the call. This will have the value “ringing”.
    SessionStartstringA timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC

    List of parameters sent to answer_url and fallback_url

    FromstringThe from number used as the caller ID to initiate the call.
    TostringThe destination that’s called.
    RequestUUIDstringAn identifier that can uniquely identify a call.
    ALegRequestUUIDstringIdentifies the first leg of the call in case there are multiple legs.
    CallUUIDstringThe identifier of the call.
    DirectionstringThe direction of the call. This will have the value “outbound” since this is an outbound API call.
    ALegUUIDstringAn unique identifier for the A leg of the call.
    EventstringThe 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 here.

    CallStatusstringThe status of the call. This will have the value “in-progress”.
    SessionStartstringA timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC

    List of parameters sent to hangup_url

    FromstringThe from number used as the caller ID to initiate the call.
    TostringThe destination that’s called.
    RequestUUIDstringAn identifier that can uniquely identify a call.
    ALegRequestUUIDstringIdentifies the first leg of the call in case there are multiple legs
    CallUUIDstringThe identifier of the call.
    DirectionstringThe direction of the call. This will be “outbound” since this is an outbound API call.
    ALegUUIDstringAn unique identifier for the A leg of the call.
    EventstringThe 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 here.

    CallStatusstringThe status of the call. This will have the value “completed”.
    StartTimestringA timestamp that indicates when the call was initiated. Timezone: Local timezone as updated in your Plivo Console Format: yyyy-MM-dd HH:mm:ss.
    AnswerTimestringA timestamp that indicates when the call was answered. Timezone: Local timezone as updated in your Plivo Console Format: yyyy-MM-dd HH:mm:ss.
    SessionStartstringA timestamp that indicates when early media started. Format: YYYY-MM-DD HH:mm:ss.sssss Timezone: UTC
    EndTimestringA timestamp that indicates when the call ended. Timezone: Local timezone as updated in your Plivo Console Format: yyyy-MM-dd HH:mm:ss.

    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_='from_number',
        to_='to_number',
        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
    
    #
    # Example for Call Create
    #
    require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.calls.create(
        '+14151234567',
        ['+15671234567'],
        'https://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';
        
       // 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(
            "+14151234567", // from
            "+15671234567", // 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
    23
    
    <?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(
            '+14151234567',
            ['+15671234567'],
            'https://s3.amazonaws.com/static.plivo.com/answer.xml',
            'GET',
            [
            	'ring_url' => 'https://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("YOUR_AUTH_ID","YOUR_AUTH_TOKEN");
            try {
                CallCreateResponse response = Call.creator("+14151234567", Collections.singletonList("+15671234567"), "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>{"+15671234567"},
                        from:"+14151234567",
                        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": "+15671234567","from": "+14151234567", "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
    
    // Example for Call create
    package main
    
    import (
    	"fmt"
    
    	"github.com/plivo/plivo-go"
    )
    
    func main() {
    	client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    	if err != nil {
    		panic(err)
    	}
    	response, err := client.Calls.Create(
    		plivo.CallCreateParams{
    			From:         "+14151234567",
    			To:           "+15671234567",
    			AnswerURL:    "https://s3.amazonaws.com/static.plivo.com/answer.xml",
    			AnswerMethod: "GET",
    		},
    	)
    	if err != nil {
    		panic(err)
    	}
    	fmt.Printf("Response: %#v\n", response)
    }