Transfer a call

    This API enables an in-progress or ongoing call to fetch and execute XML from a different URL. If the call (the A leg) is in a Dial, you can also transfer the other party (the B leg) at the same time, or only transfer the B leg to a URL. This is useful for applications where you want to asynchronously change the behavior of a live call. For example, you can play music while a call is on hold, queue calls, or transfer calls.

    API Endpoint

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

    Arguments

    legs

    Valid values are aleg, bleg, or both. aleg transfers call_uuid. bleg transfers the bridged leg of call_uuid. both transfers both legs.

    aleg_url Callback-retry configurable

    The URL to fetch XML from for the A leg. This argument needs to be specified if the legs parameter is either aleg or both.

    aleg_method

    The HTTP verb to invoke the aleg_url.

    Defaults to POST.

    bleg_url Callback-retry configurable

    The URL to fetch XML from for the B leg. This need to be specified if the legs parameter is either bleg or both.

    bleg_method

    The HTTP verb to invoke the bleg_url.

    Defaults to POST.

    Returns

    Returns an acknowledgement that the call is transferred.

    Response

    HTTP Status Code: 202

    {
    "message": "call transferred",
    "api_id": "08c94608-58bd-11e1-86da-adf28403fe48"
    }
    

    Example Request

    1
    2
    3
    4
    5
    6
    7
    8
    9
    
    import plivo
    
    client = plivo.RestClient('<auth_id>','<auth_token>')
    
    response = client.calls.transfer(
        legs='aleg',
        aleg_url='https://aleg.url',
        call_uuid='1ed7fd89-df77-4ebf-8196-d5cf7222c918', )
    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 Update
    #
    require 'rubygems'
    require 'plivo'
    
    include Plivo
    include Plivo::Exceptions
    
    api = RestClient.new("<auth_id>","<auth_token>")
    
    begin
      response = api.calls.update(
        'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
        legs: 'aleg',
        aleg_url: 'https://aleg.url'
      )
      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
    
    // Example for Call update
    
    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.transfer(
            "eba53b9e-8fbd-45c1-9444-696d2172fbc8", // call uuid
            {
                legs: "aleg",
                alegUrl: "https://aleg.url",
            },
        ).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 update
     */
    require 'vendor/autoload.php';
    use Plivo\RestClient;
    use Plivo\Exceptions\PlivoRestException;
    $client = new RestClient("<auth_id>","<auth_token>");
    
    try {
        $response = $client->calls->transfer(
            'eba53b9e-8fbd-45c1-9444-696d2172fbc8',
            [
            	'legs' => 'aleg',
            	'aleg_url' => 'https://ALEG.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 com.plivo.api.Plivo;
    import com.plivo.api.exceptions.PlivoRestException;
    import com.plivo.api.models.call.Call;
    import com.plivo.api.models.call.CallUpdateResponse;
    import com.plivo.api.models.call.LegSpecifier;
    
    /**
    * Example for Call update
    */
    class CallUpdate {
        public static void main(String [] args) {
            Plivo.init("<auth_id>","<auth_token>");
            try {
                CallUpdateResponse response = Call.updater("eba53b9e-8fbd-45c1-9444-696d2172fbc8")
                    .legs(LegSpecifier.ALEG)
                    .alegUrl("https://aleg.url")
                    .update();
    
                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
    
    /**
     * Example for Call Update
     */
    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.Transfer(
                        alegUrl:"https://aleg.url",
                        callUuid:"eba53b9e-8fbd-45c1-9444-696d2172fbc8",
                        legs:"aleg"
                    );
                    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 '{"legs": "optional_param"}' \
        https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/
    
    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
    
    // Example for Call update
    package main
    
    import (
    	"fmt"
    
    	"github.com/plivo/plivo-go"
    )
    
    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.Update(
    		"eba53b9e-8fbd-45c1-9444-696d2172fbc8",
    		plivo.CallUpdateParams{
    			Legs:    "aleg",
    			AlegURL: "https://aleg.url",
    		},
    	)
    	if err != nil {
    			fmt.Print("Error", err.Error())
    			return
    		}
    	fmt.Printf("Response: %#v\n", response)
    }