Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Outbound - Receiving SIP from Twilio

Overview

Twilio’s Programmable Voice SIP product enables your advanced voice applications to initiate SIP sessions from the Twilio cloud towards your existing SIP communications infrastructure using TwiML and/or the REST APIs.

Programmable Voice SIP Diagram

How it works

With Programmable Voice SIP, there are a couple of ways to connect your Twilio application to your SIP communications infrastructure.

  1. Your application can use Twilio’s REST APIs to initiate a new SIP call towards your SIP communications infrastructure
  2. An inbound PSTN or SIP call can invoke your application which can respond using the <Sip> noun of the <Dial> verb, to establish a call with your SIP endpoint.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Sip>sip:jack@example.com</Sip>
  </Dial>
</Response>

Getting Started

To start receiving SIP from Twilio towards your communications infrastructure, there is one major step you need to follow:

Whitelist Twilio’s SIP IP addresses and media ports in your system

To ensure that your communications infrastructure doesn’t block communication, you must update your whitelist. See here for details.

Now that Twilio’s IPs are whitelisted in your system, your Twilio app can begin sending SIP traffic to your SIP communications infrastructure. If you are new to Twilio, it’s best to start out with <Sip> noun of the <Dial> for your first app. See here for details.

Advanced Features

SIP Custom Headers

Twilio allows you to send custom SIP headers as part of the outgoing initial INVITE request.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:jack@example.com?x-myotherheader=bar</Sip>
    </Dial>
</Response>

You can also send multiple param & value pairs as part of the same header. For example,

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:+14158675309@your.domain?X-customName=Bob%2CShield%2BTitle%2DManager&amp;X-otherHeader=true</Sip>
    </Dial>
</Response>

Twilio allows you to pass the custom header as part of Dial action URL or the call screening URL. On a successful call setup (when a 200 OK SIP response is returned) any X-headers in the 200 OK message are posted to the call screening URL in the format SipHeader_X-headername=headervalue and in the final SIP response message (any 4xx or 5xx message or the final BYE/200) are posted to the Dial action URL in the format DialSipHeader_X-headername=headervalue.

UUI (User-to-User Information) Header

In order to pass the contextual information of the caller, customers use UUI (User-to-User Information) header in SIP request messages. Twilio allows you to pass UUI header as part of <Sip> request.

Note: For non X-headers like UUI, action and call screening URL are not supported.

UUI headers is the only header that can be sent without "X-" prefix. See below...

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:jack@example.com?User-to-User=123456789%3Bencoding%3Dhex&amp;x-myotherheader=bar</Sip>
    </Dial>
</Response>

UUI headers can also send with "X-" prefix. See below... ```xml <?xml version="1.0" encoding="UTF-8"?> sip:jack@example.com?X-User-to-User=123456789%3Bencoding%3Dhex&x-myotherheader=bar

The region parameter

To specify the geographic region from which Twilio will send SIP-out traffic towards your communication infrastructure, you must include the region parameter in your SIP URI. For example, if the region=ie1 parameter is included in your SIP URI, Twilio will send the SIP traffic from the Europe Ireland region:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:alice@example.com;region=ie1</Sip>
    </Dial>
</Response>
Region Location
us1 North America Virginia
us2 North America Oregon
ie1 Europe Ireland
de1 Europe Frankfurt
sg1 Asia Pacific Singapore
jp1 Asia Pacific Tokyo
br1 South America São Paulo
au1 Asia Pacific Sydney

If the region parameter is not specified, Twilio will send SIP-out traffic from the North America Virginia region.

Notes:

  • You must make sure you whitelist the IP addresses of the Twilio region for SIP signaling and RTP media traffic.
  • The region parameter is not supported when calling SIP registered endpoints, the parameter will be ignored if present. SIP-out traffic will always be sent from the Twilio region the SIP endpoint registered with.
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.