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:


_10 /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:


_10sip:michael@example.com

Headers

Pass headers in the To parameter by appending them to the end of the SIP URI. For certain sdks, & will need encoding as %26. The total characters passed in a header must be under 1024. For example:


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

Transport

Set a parameter on your SIP URI to specify what transport protocol you want to use. You may use UDP, TCP or TLS. By default, Twilio sends your SIP INVITE over UDP. Change this by using the transport parameter:


_10sip:jack@example.com;transport=tcp

Also, when using transport=tls, this will only encrypt SIP signaling messages and not RTP. To use SRTP and to encrypt SIP signaling, please add a parameter secure=true to your SIP URI:


_10sip:jack@example.com;secure=true

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.

Create a SIP Dial

Basic SIP dial using the REST API.

Create Basic SIP Dial

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20
_20async function createCall() {
_20  const call = await client.calls.create({
_20    from: "Jack",
_20    to: "sip:kate@example.com",
_20    url: "http://www.example.com/sipdial.xml",
_20  });
_20
_20  console.log(call.sid);
_20}
_20
_20createCall();

Output


_39{
_39  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39  "annotation": null,
_39  "answered_by": null,
_39  "api_version": "2010-04-01",
_39  "caller_name": null,
_39  "date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
_39  "date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
_39  "direction": "inbound",
_39  "duration": "15",
_39  "end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
_39  "forwarded_from": "+141586753093",
_39  "from": "Jack",
_39  "from_formatted": "(415) 867-5308",
_39  "group_sid": null,
_39  "parent_call_sid": null,
_39  "phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39  "price": "-0.03000",
_39  "price_unit": "USD",
_39  "sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39  "start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
_39  "status": "completed",
_39  "subresource_uris": {
_39    "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
_39    "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
_39    "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
_39    "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
_39    "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
_39    "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
_39    "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
_39    "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
_39    "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
_39  },
_39  "to": "sip:kate@example.com",
_39  "to_formatted": "(415) 867-5309",
_39  "trunk_sid": null,
_39  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
_39  "queue_time": "1000"
_39}

Create SIP Dial with Authentication

Pass user and password to your SIP call for authentication.

Create SIP Dial with Authentication

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_22// Download the helper library from https://www.twilio.com/docs/node/install
_22const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_22
_22// Find your Account SID and Auth Token at twilio.com/console
_22// and set the environment variables. See http://twil.io/secure
_22const accountSid = process.env.TWILIO_ACCOUNT_SID;
_22const authToken = process.env.TWILIO_AUTH_TOKEN;
_22const client = twilio(accountSid, authToken);
_22
_22async function createCall() {
_22  const call = await client.calls.create({
_22    from: "Jack",
_22    sipAuthPassword: "secret",
_22    sipAuthUsername: "jack",
_22    to: "sip:kate@example.com",
_22    url: "http://www.example.com/sipdial.xml",
_22  });
_22
_22  console.log(call.sid);
_22}
_22
_22createCall();

Output


_39{
_39  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39  "annotation": null,
_39  "answered_by": null,
_39  "api_version": "2010-04-01",
_39  "caller_name": null,
_39  "date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
_39  "date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
_39  "direction": "inbound",
_39  "duration": "15",
_39  "end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
_39  "forwarded_from": "+141586753093",
_39  "from": "Jack",
_39  "from_formatted": "(415) 867-5308",
_39  "group_sid": null,
_39  "parent_call_sid": null,
_39  "phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39  "price": "-0.03000",
_39  "price_unit": "USD",
_39  "sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39  "start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
_39  "status": "completed",
_39  "subresource_uris": {
_39    "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
_39    "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
_39    "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
_39    "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
_39    "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
_39    "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
_39    "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
_39    "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
_39    "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
_39  },
_39  "to": "sip:kate@example.com",
_39  "to_formatted": "(415) 867-5309",
_39  "trunk_sid": null,
_39  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
_39  "queue_time": "1000"
_39}

Pass Headers in your SIP URI

Pass headers to your SIP Dial as part of the SIP URI.

Create SIP Dial using Pass Headers in the SIP URI

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20
_20async function createCall() {
_20  const call = await client.calls.create({
_20    from: "Jack",
_20    to: "sip:kate@example.com?X-hatchkey=4815162342",
_20    url: "http://www.example.com/sipdial.xml",
_20  });
_20
_20  console.log(call.sid);
_20}
_20
_20createCall();

Output


_39{
_39  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_39  "annotation": null,
_39  "answered_by": null,
_39  "api_version": "2010-04-01",
_39  "caller_name": null,
_39  "date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
_39  "date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
_39  "direction": "inbound",
_39  "duration": "15",
_39  "end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
_39  "forwarded_from": "+141586753093",
_39  "from": "Jack",
_39  "from_formatted": "(415) 867-5308",
_39  "group_sid": null,
_39  "parent_call_sid": null,
_39  "phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39  "price": "-0.03000",
_39  "price_unit": "USD",
_39  "sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_39  "start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
_39  "status": "completed",
_39  "subresource_uris": {
_39    "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
_39    "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
_39    "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
_39    "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
_39    "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
_39    "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
_39    "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
_39    "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
_39    "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
_39  },
_39  "to": "sip:kate@example.com?X-hatchkey=4815162342",
_39  "to_formatted": "(415) 867-5309",
_39  "trunk_sid": null,
_39  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
_39  "queue_time": "1000"
_39}