REST API: Making SIP Calls

Use Twilio's REST API to connect to your SIP-enabled endpoints. With this feature, you can set up a VoIP session using SIP. If you are unfamiliar with SIP, or want more information on how Twilio works with your SIP endpoint, please see the SIP overview.

HTTP POST to Calls

Initiate SIP sessions via the REST API by POSTing to the same calls resource used to initiate traditional phone calls (see making calls for more information). Once the call is connected, Twilio will then fetch the TwiML you specify for the call. For example, make a SIP call by POSTing to your account's calls list resource URI:

 /2010-04-01/Accounts/{AccountSid}/Calls 

POST Parameters

All outgoing call features and parameters are supported -- the only difference
is that you pass different values in the "To" and "From" parameters. In the “To” parameter, put the SIP URI you are trying to connect to. In the “From” parameter, specify the user you want to show up in the From header in the SIP request.

Required Parameters

You must POST the following parameters:

Parameter Description
To The SIP URI to which you want to connect

The 'To' parameter specifies a SIP address for Twilio to connect to. The body of the URI element should be a valid SIP URI under 255 characters. For example:

sip:michael@example.com
Headers

Pass headers in the To parameter by appending them to the end of the SIP URI. The total characters passed in a header must be under 1024. For example:

sip:michael@example.com?mycustomheader=foo&myotherheader=bar 
Transport

Set a parameter on your SIP URI to specify what transport protocol you want to use. Currently, this is limited to TCP and UDP. By default, Twilio sends your SIP INVITE over UDP. Change this by using the transport parameter:

sip:jack@example.com;transport=tcp

Optional Parameters

You may POST the following parameters:

Parameter Description
From This value is used to populate the username portion of the From header that is passed to the SIP endpoint. This may be any alphanumeric character, as well as the plus, minus, underscore, and period characters (+-_.). No spaces or other characters are allowed.
SipAuthUsername Your authentication username.
SipAuthPassword The password for the user.

Examples

Example 1

Basic SIP dial using the REST API.

Create Basic SIP Dial
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new CallOptions();
    options.Url = "http://www.example.com/sipdial.xml";
    options.To = "sip:kate@example.com";
    options.From = "Jack";
    var call = twilio.InitiateOutboundCall(options);
    
    Console.WriteLine(call.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://www.example.com/sipdial.xml"));
    params.add(new BasicNameValuePair("To", "sip:kate@example.com"));
    params.add(new BasicNameValuePair("From", "Jack"));
    
    
    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.calls.create({
    url: "http://www.example.com/sipdial.xml",
    to: "sip:kate@example.com",
    from: "Jack"
}, function(err, call) {
    process.stdout.write(call.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

$call = $client->account->calls->create("Jack", "sip:kate@example.com", "http://www.example.com/sipdial.xml", array());
echo $call->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

call = client.calls.create(url="http://www.example.com/sipdial.xml",
    to="sip:kate@example.com",
    from_="Jack")
print call.sid
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

call = @client.account.calls.create(:url => "http://www.example.com/sipdial.xml",
    :to => "sip:kate@example.com",
    :from => "Jack")
puts call.direction
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls \
    -d "Url=http://www.example.com/sipdial.xml" \
    -d "To=sip:kate%40example.com" \
    -d "From=Jack" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
    -d "Url=http://www.example.com/sipdial.xml" \
    -d "To=sip:kate%40example.com" \
    -d "From=Jack" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Example 2

Pass user and password for authentication.

Create SIP Dial with Authentication
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new CallOptions();
    options.Url = "http://www.example.com/sipdial.xml";
    options.To = "sip:kate@example.com";
    options.From = "Jack";
    options.SipAuthPassword = "secret";
    options.SipAuthUsername = "jack";
    var call = twilio.InitiateOutboundCall(options);
    
    Console.WriteLine(call.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://www.example.com/sipdial.xml"));
    params.add(new BasicNameValuePair("To", "sip:kate@example.com"));
    params.add(new BasicNameValuePair("From", "Jack"));
    params.add(new BasicNameValuePair("SipAuthPassword", "secret"));
    params.add(new BasicNameValuePair("SipAuthUsername", "jack"));
    
    
    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.calls.create({
    url: "http://www.example.com/sipdial.xml",
    to: "sip:kate@example.com",
    from: "Jack",
    sipAuthPassword: "secret",
    sipAuthUsername: "jack"
}, function(err, call) {
    process.stdout.write(call.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

$call = $client->account->calls->create("Jack", "sip:kate@example.com", "http://www.example.com/sipdial.xml", array(
        "SipAuthPassword" => "secret",
    "SipAuthUsername" => "jack"
    ));
echo $call->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

call = client.calls.create(url="http://www.example.com/sipdial.xml",
    to="sip:kate@example.com",
    from_="Jack",
    sip_auth_password="secret",
    sip_auth_username="jack")
print call.sid
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

call = @client.account.calls.create(:url => "http://www.example.com/sipdial.xml",
    :to => "sip:kate@example.com",
    :from => "Jack",
    :sip_auth_password => "secret",
    :sip_auth_username => "jack")
puts call.to
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls \
    -d "Url=http://www.example.com/sipdial.xml" \
    -d "To=sip:kate%40example.com" \
    -d "From=Jack" \
    -d "SipAuthPassword=secret" \
    -d "SipAuthUsername=jack" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
    -d "Url=http://www.example.com/sipdial.xml" \
    -d "To=sip:kate%40example.com" \
    -d "From=Jack" \
    -d "SipAuthPassword=secret" \
    -d "SipAuthUsername=jack" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Example 3

Pass headers as part of the SIP URI.

Create SIP Dial using Pass Headers in the SIP URI
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new CallOptions();
    options.Url = "http://www.example.com/sipdial.xml";
    options.To = "sip:kate@example.com?hatchkey=4815162342";
    options.From = "Jack";
    var call = twilio.InitiateOutboundCall(options);
    
    Console.WriteLine(call.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.CallFactory;
import com.twilio.sdk.resource.instance.Call;
import com.twilio.sdk.resource.list.CallList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the CallList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("Url", "http://www.example.com/sipdial.xml"));
    params.add(new BasicNameValuePair("To", "sip:kate@example.com?hatchkey=4815162342"));
    params.add(new BasicNameValuePair("From", "Jack"));
    
    
    CallFactory callFactory = client.getAccount().getCallFactory();
    Call call = callFactory.create(params);
    System.out.println(call.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.calls.create({
    url: "http://www.example.com/sipdial.xml",
    to: "sip:kate@example.com?hatchkey=4815162342",
    from: "Jack"
}, function(err, call) {
    process.stdout.write(call.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

$call = $client->account->calls->create("Jack", "sip:kate@example.com?hatchkey=4815162342", "http://www.example.com/sipdial.xml", array());
echo $call->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

call = client.calls.create(url="http://www.example.com/sipdial.xml",
    to="sip:kate@example.com?hatchkey=4815162342",
    from_="Jack")
print call.sid
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

call = @client.account.calls.create(:url => "http://www.example.com/sipdial.xml",
    :to => "sip:kate@example.com?hatchkey=4815162342",
    :from => "Jack")
puts call.direction
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls \
    -d "Url=http://www.example.com/sipdial.xml" \
    -d "To=sip:kate%40example.com%3Fhatchkey%3D4815162342" \
    -d "From=Jack" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
    -d "Url=http://www.example.com/sipdial.xml" \
    -d "To=sip:kate%40example.com%3Fhatchkey%3D4815162342" \
    -d "From=Jack" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'