Pass Custom Headers

    SIP headers (also called SIP fields) is a function of SIP. These headers help convey message attributes to ensure that information packets travel along the correct path when communicating between devices existing on separate networks. SIP headers are present for every HTTP request made by an outbound call and can be categorized into four main types: record route headers, route headers, via headers, and contact headers. Simply put, SIP headers are similar to HTTP header fields and always have the following format:

    <header_name>:<value>
    

    SIP headers are always prefixed with X-PH-. Only [A-Z], [a-z] and [0-9] characters are allowed for the SIP header key. Only [A-Z], [a-z], [0-9] and ‘%’ characters are allowed for the SIP header value to ensure that you can encode this value in a URL. You may add multiple header fields by entering the value as a comma-separated list. For example:

    head1=val1,head2=val2,head3=val3,...,headN=valN
    

    If you are using a SIP endpoint and have configured your SIP phone to send custom SIP headers, then Plivo will send these SIP headers with your HTTP Request.

    The following API enables you to make a single call or bulk outbound calls to real phone(s) or SIP endpoint(s). The following tutorial will show you how to add custome SIP headers.

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

    Prerequisites

    1. Sign up for a free Plivo trial account.
    2. Check out our server-side SDKs page and install the right helper based on the programming language you want to use.
    3. Buy a Plivo phone number (optional).
    4. Use a web hosting service to host your web application. There are many inexpensive cloud hosting providers that you can use for just a few dollars a month. Follow the instructions of your hosting provider to host your web application.

    Implementation

    1. Copy the relevant code below into a text file and save it.
      Note: Be sure to save it with the appropriate file extension for your language (i.e., .py for Python or .rb for Ruby, etc.).
    2. Replace 'Your AUTH_ID' and 'Your AUTH_TOKEN' with the AUTH ID and AUTH TOKEN found on your Plivo dashboard.
    3. Add your 'from' (source) phone number. This will show up as your Sender ID. Be sure that all phone numbers include country code, area code, and phone number without spaces or dashes (e.g., 14153336666).
    4. Add your 'to' (destination) sip endpoint. Sip endpoints must be prefixed with sip: E.g., sip:john1234@phone.plivo.com.
      Note: If you are using a trial account, your destination number needs to be verified with Plivo. Phone numbers can be verified at the Sandbox Numbers page.
    5. Edit the 'answer_url' field with your hosted url which is invoked by Plivo when the call is answered.
    6. Edit the 'answer_method' field with either GET or POST.
    7. Add your Sip Headers to 'sip_headers' field. List of SIP headers are in the form of ‘key=value’ pairs, separated by commas. E.g. head1=val1,head2=val2,head3=val3,…,headN=valN. The SIP headers are always prefixed with X-PH-. The SIP headers are present for every HTTP request made by the outbound call. Only [A-Z], [a-z] and [0-9] characters are allowed for the SIP headers key and value. Additionally, the ‘%’ character is also allowed for the SIP headers value so that you can encode this value in the URL.

    Code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    
    import plivo
    
    client = plivo.RestClient('YOUR_AUTH_ID','YOUR_AUTH_TOKEN')
    response = client.calls.create(
        from_='from_number',
        to_='to_number',
        answer_url='http://s3.amazonaws.com/static.plivo.com/answer.xml',
        answer_method='GET', 
        sip_headers='Test=Sample')
    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(
        '+14151234567',
        ['+15671234567'],
        'http://s3.amazonaws.com/static.plivo.com/answer.xml',
        sip_headers: 'Test=Sample',)
      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
    23
    
    // 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("YOUR_AUTH_ID","YOUR_AUTH_TOKEN");
        client.calls.create(
            "+14151234567", // from
            "+15671234567", // to
            "http://s3.amazonaws.com/static.plivo.com/answer.xml", // answer url
            {
                answerMethod: "GET",
                sipHeaders: "Test=Sample"
            },
        ).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
    24
    
    <?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(
            '+14151234567',
            ['+15671234567'],
            'http://s3.amazonaws.com/static.plivo.com/answer.xml',
            'GET',
            [
                'ring_url' => 'http://WWW.RING.URL',
                'sip_headers' => 'Test=Sample',
            ]
        );
        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
    28
    
    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"), "http://s3.amazonaws.com/static.plivo.com/answer.xml")
                        .answerMethod("GET")
                        .sipHeaders(new HashMap<String, String>() )
                        .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
    
    // Example for Call create
    package main
    
    import "fmt"
    import "github.com/plivo/plivo-go"
     
    func main() {
    	client, err := plivo.NewClient("YOUR_AUTH_ID", "YOUR_AUTH_TOKEN", &plivo.ClientOptions{})
    	if err != nil {
    		panic(err)
    	}
    	response, err := client.Calls.Create(
    		plivo.CallCreateParams{
    			From: "+14151234567",
    			To: "+15671234567",
    			AnswerURL: "http://s3.amazonaws.com/static.plivo.com/answer.xml",
    			AnswerMethod: "GET",
    			SipHeader: "Test=Sample"
    		},
    	)
    	if err != nil {
    		panic(err)
    	}
    	fmt.Printf("Response: %#v\n", response)
    }
    
    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
    33
    
    /**
     * 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>{"+15671234567"},
                        from:"+14151234567",
                        answerMethod:"GET",
                        answerUrl:"http://s3.amazonaws.com/static.plivo.com/answer.xml",
                        sipHeaders: "Test=Sample"
                    );
                    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": "sip:abcd150108095716@phone.plivo.com","from": "1111111111", "answer_url": "https://s3.amazonaws.com/static.plivo.com/answer.xml", "answer_method": "GET", "sip_headers": "Test=Sample"}' 
        https://api.plivo.com/v1/Account/{auth_id}/Call/
    

    Sample Response

    (201, {
           u'message': u'call fired',
           u'request_uuid': u'85b1d45d-bc12-47f5-89c7-ae4a2c5d5713',
           u'api_id': u'ad0e27a8-9008-11e4-b932-22000ac50fac'
       }
    )
    The SIP header can be seen as a query parameter in the answer_url
    
    /answer.xml?Direction=outbound&From=1111111111&ALegUUID=5260e820-958c-11e4-b6bf-498d468c930b&BillRate=0.00300&
    To=sip%3Aabcd150105094929%40phone.plivo.com&<mark>X-PH-Test=Sample</mark>&CallUUID=5260e820-958c-11e4-b6bf-498d468c930b&ALegRequestUUID=2202d0ab-a890-4199-8582-e7a2615cb23b&
    RequestUUID=2202d0ab-a890-4199-8582-e7a2615cb23b&SIP-H-To=%3Csip%3Aabcd150105094929%40phone.plivo.com%3E%3Btag%3D6U9J4.uVHI7KyEKSgD8vrPnAKQoR2QXc&
    CallStatus=in-progress&Event=StartApp