Add Custom SIP 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 Helper Libraries 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
11
12
13
14
15
16
17
18
import plivo

auth_id = "Your AUTH_ID"
auth_token = "Your AUTH_TOKEN"

p = plivo.RestAPI(auth_id, auth_token)

params = {
    'to': 'sip:abcd150105094929@phone.plivo.com', # The phone numer to which the all has to be placed. Sip endpoints must be prefixed with sip:
    'from' : '1111111111', # The phone number to be used as the caller id
    'answer_url' : "https://s3.amazonaws.com/static.plivo.com/answer.xml", # The URL invoked by Plivo when the outbound call is answered
    'answer_method' : "GET", # Method to invoke the answer_url
    'sip_headers' : "Test=Sample" # List of SIP headers in the form of 'key=value' pairs, separated by commas.
}

# Make an outbound call
response = p.make_call(params)
print str(response)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
require 'rubygems'
require 'plivo'
include Plivo

AUTH_ID = "Your AUTH_ID"
AUTH_TOKEN = "Your AUTH_TOKEN"


p = RestAPI.new(AUTH_ID, AUTH_TOKEN)

params = {
    'to' => 'sip:abcd150105094929@phone.plivo.com', # The phone numer to which the all has to be placed. Sip endpoints must be prefixed with sip:
    'from' => '1111111111', # The phone number to be used as the caller id
    'answer_url' => 'https://s3.amazonaws.com/static.plivo.com/answer.xml', # The URL invoked by Plivo when the outbound call is answered
    'answer_method' => 'GET', # The method used to call the answer_url
    'sip_headers' => "Test=Sample" # List of SIP headers in the form of 'key=value' pairs, separated by commas.
}

# Make an outbound call
response = p.make_call(params)
print response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
var plivo = require('plivo');
var p = plivo.RestAPI({
    "authId": "auth id comes here",
    "authToken": "auth token comes here",
});
var params = {};
params.from = "1111111111"; // The phone number to be used as the caller id 
params.to = "sip:abcd150105094929@phone.plivo.com"; // The phone numer to which the all has to be placed. Sip endpoints must be prefixed with sip:
params.answer_url = "https://s3.amazonaws.com/static.plivo.com/answer.xml"; // The URL invoked by Plivo when the outbound call is answered
params.answer_method = "GET"; // Method to invoke the answer_url
params.sip_headers = "Test=Sample" // List of SIP headers in the form of 'key=value' pairs, separated by commas.

p.make_call(params, function (status, response) {
    console.log('Status: ', status);
    console.log('API Response:\n', response);
});
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?php
    require 'vendor/autoload.php';
    use Plivo\RestAPI;
    
    $auth_id = "Your AUTH_ID";
    $auth_token = "Your AUTH_TOKEN";
    $p = new RestAPI($auth_id, $auth_token);
    $params = array(
        'to' => 'sip:abcd150105094929@phone.plivo.com', # The phone numer to which the all has to be placed. Sip endpoints must be prefixed with sip:
        'from' => '2222222222', # The phone number to be used as the caller id
        'answer_url' => "https://s3.amazonaws.com/static.plivo.com/answer.xml", # The URL invoked by Plivo when the outbound call is answered
        'answer_method' => "GET", # The method used to call the answer_url
        'sip_headers' => "Test=Sample", # List of SIP headers in the form of 'key=value' pairs, separated by commas.
    );
    
    # Make an outbound call
    $response = $p->make_call($params);
    print_r ($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
package com.plivo.test;

import java.util.LinkedHashMap;

import com.plivo.helper.api.client.*;
import com.plivo.helper.api.response.call.Call;
import com.plivo.helper.exception.PlivoException;

public class App {
    public static void main(String[] args) throws IllegalAccessException {

        String auth_id = "Your AUTH_ID";
        String auth_token = "Your AUTH_TOKEN";
        
        RestAPI api = new RestAPI(auth_id, auth_token, "v1");

        LinkedHashMap<String, String> parameters = new LinkedHashMap<String, String>();
        parameters.put("to","sip:abcd150108095716@phone.plivo.com"); // The phone numer to which the all has to be placed. Sip endpoints must be prefixed with sip:
        parameters.put("from","1111111111"); // The phone number to be used as the caller id
        parameters.put("answer_url","https://s3.amazonaws.com/static.plivo.com/answer.xml"); // The URL invoked by Plivo when the outbound call is answered
        parameters.put("answer_method","GET"); // Method to invoke the answer_url
        parameters.put("sip_headers", "Test=Sample"); // List of SIP headers in the form of 'key=value' pairs, separated by commas.

        try {
            Call resp = api.makeCall(parameters);
            System.out.println(resp);                        
        }catch (PlivoException e){  
            System.out.println(e.getLocalizedMessage());
        }  
    }
}
 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
using System;
using System.Collections.Generic;
using RestSharp;
using Plivo.API;

namespace custom_sip_header
{
    class Program
    {
        static void Main(string[] args)
        {
            RestAPI plivo = new RestAPI("Your AUTH_ID", "Your AUTH_TOKEN");
             
            IRestResponse<Call> resp = plivo.make_call(new Dictionary<string, string>() 
            {
                { "from", "1111111111" }, // The phone number to which the call has to be placed
                { "to", "sip:abcd150105094929@phone.plivo.com" }, // The phone numer to which the all has to be placed. Sip endpoints must be prefixed with sip:
                { "answer_url", "https://s3.amazonaws.com/static.plivo.com/answer.xml" }, // The URL invoked by Plivo when the outbound call is answered
                {"answer_method","GET"}, // The method used to invoke the answer_url
                {"sip_headers","Test=Sample"} // List of SIP Headers in the form of 'key=value' pairs, separated by commas 
            });

            //Prints the response
            Console.Write(resp.Content);

            Console.ReadLine();
        }
    }
}
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

Next Step

Learn how to []()

  1. Make an Outbound Call
  2. Play a Text-to-speech Message
  3. Connect Call to a Second Person
  4. Greet Caller by Name
  5. Play MP3/WAV Audio to Caller
  6. Hangup Using API
  7. Receive Incoming Call
  8. Forward Incoming Call
  9. Record Using API
  10. Screen Incoming Call
  11. Reject incoming call
  12. Get Details of all Calls
  13. Get Details of a single Call
  14. Get Details of Live Calls
  15. Build an IVR Phone Menu
  16. Conference Call
  17. Call Forward
  18. SIP Endpoint (Direct-Dial)
  19. Inbound Trunk
  20. Outbound Trunk