SIP Registration

What is SIP Registration

SIP offers a discovery capability. If a user wants to make a phone call to another user, then SIP must discover the IP address at which the destination user is reachable. SIP Registration is the process in which a SIP Endpoint sends a SIP REGISTER request to the registrar. The registrar acts as the front end to the location service for a SIP Domain, reading and writing bindings between endpoints and a particular user. Programmable Voice SIP Domains may be optionally configured to support SIP Registration. You may do this by enabling the SIP Registration option in your SIP Domain.

Learn how to:

Register your SIP Endpoint

When you configure your endpoint, you specify the SIP Domain that you want to register with and you must include the Twilio region.

{domain-name}.sip.us1.twilio.com - (North America Virginia)

The SIP Registrar is deployed on a per region basis. The contents of the SIP Registrar are not shared between regions. When you specify a SIP Domain server to register with you must specify the Twilio region.

SIP Registration is only currently supported in our US1 data center - North America Virginia.

SIP Endpoint Registration Authentication

Your REGISTER request will be authenticated against User Credential Lists that have been mapped to this SIP Domain.

The Username that is configured in the SIP Endpoint must exactly match the Username specified in a Credential List mapped to this SIP Domain for successful registration. Some SIP Endpoints refer to this field as the Username while others call it the Authorization ID.

SIP Endpoint REGISTER Refresh Interval

The SIP Endpoint needs to notify the registrar on periodic intervals.
The maximum frequency that a SIP Endpoint can refresh is every 600 seconds (10 minutes).

Limits

Make sure you're aware of the following Programmable Voice SIP Registration limits.

  • 10,000 Active registrations per SIP Domain
  • 20,000 Active registrations per Account
  • 10 Endpoint registrations per Address-of-Record (AOR) - Note that the 11th registration attempt for the same AOR will be rejected
  • 5 REGISTER requests / second / AOR

Making calls with your registered SIP Endpoint

To make outgoing SIP calls from your registered Endpoint, you must send the INVITE to your regionalized SIP domain. No other changes required:

{domain-name}.sip.us1.twilio.com

Note that in the above example, US1 has been added to the domain to specify the region.

Outgoing calls by your registered Endpoint will be treated just like any incoming SIP call received on a Twilio domain. After being authenticated it will invoke the Voice URL configured in your SIP domain. See sending SIP to Twilio for details.

Test your SIP Endpoint Voice connectivity with your SIP Domain

For example, you can configure your SIP Domain Voice URL with the following to verify connectivity with Twilio. It’s a simple app that will say a brief message.

http://twimlets.com/message?Message%5B0%5D=Congratulations!%20You%20just%20made%20your%20first%20call%20with%20Twilio%20SIP.

How to Make Calls from SIP Endpoint to Public Telephone Network

In this section we summarize a few different ways you can bridge calls from you SIP Endpoint to the public telephone network using Programmable Voice.

Using Enhanced TwiML Bin Templates to Call a mobile/landline on the Public Telephone Network

Twilio has Enhanced TwiML Bins Templates which extracts the username from both the From and To SIP URIs in the SIP INVITE of the parent call leg that can be used to construct a dynamic TwiML response.

The example below shows how the To field of the child call leg is populated with the username of the SIP INVITEs To field of the parent call leg.

<Response>
    <Dial callerId="+14087998994">{{#e164}}{{To}}{{/e164}}</Dial>
</Response>

Note 1: When you dial a number using your SIP Endpoint it must be in E.164. (such as +14157012311 or +441562720212) The Twilio Lookup tool is useful for determining international E.164 formats.

Note 2: The callerId must be a number verified on the Twilio Console.

The next example takes it one step further by dynamically setting the callerId based on the SIP endpoint caller. Like in the previous example the caller must be an in E.164 format and must be verified on the Twilio Console.

<Response>
    <Dial callerId="{{#e164}}{{From}}{{/e164}}">{{#e164}}{{To}}{{/e164}}</Dial>
</Response>

The From field above corresponds to the username of the SIP URI found in the From field in the SIP INVITE. This username also corresponds to the username that the SIP Endpoint uses to authenticate itself that must be configured in the SIP Registration Credential List on the Console.

Using APP hosted on Heroku to Call mobile/landline on Public Telephone Network

TwiML bins have limited programming capability. For more advanced call handling apps like building hunt groups or other business logic you can use the following Flask python WebApp, hosted on Heroku, as a starting point.

To allow you to quickly place calls for demonstration purposes ONLY you can configure the SIP Domain Voice REQUEST URL with the following. This URL is subject to being decommissioned at any time.

http://simpledial.herokuapp.com/voice?callerId=+1NXXNXXXXXX

You can fill in the callerId with a telephone number you have purchased or verified on the Twilio Console.

You can deploy your own Webapp for free in under 5 minutes that let's your SIP Endpoint call the Public Telephone Network. If you don't have one already you can sign up for a free Heroku account.

Receiving calls on your registered SIP Endpoint

In order for your SIP Endpoint to receive calls from Twilio, you will use the same TwiML or REST API calls you use today. See receiving SIP from Twilio for REST API & TwiML details.

The only difference is that you will now be using the AOR of your registered SIP Endpoint. Keep in mind that calls need to be initiated by your application, just like Programmable Voice SIP calls.

For example - You could buy a Twilio phone number and when this number is called it will ring your SIP endpoints

Steps:

  1. Buy a Twilio phone number in the country/area-code you want. The number must be provisioned in the same (sub)-account as the SIP Domain enabled for Registration
  2. Create a TwiML Bin with the following. You must change the bold parts.

    <Response>
        <Dial>
            <Sip>
                yourusername@yoursipdomain.sip.us1.twilio.com
            </Sip>
        </Dial>
    </Response>

Note: yourusername in the previous TwiML example MUST match one of the usernames specified in your Console’s SIP Registration Credential Lists.

Note that if you have multiple SIP Endpoints registered under the same AOR, then all devices will ring simultaneously. See Limits.

Things to watch out for

  • Twilio does not support the SIP REFER request. For instance, during a call if a user presses say the TRANSFER button on the phone, Twilio will not pass this information to your TwiML application.
  • Twilio supports standard SIP Registration. The section below includes sample configuration guides to help you get started. There may be SIP Endpoints that don't behave per the standard and those are not supported.

Configure your SIP Endpoint

The following Configuration Guides are intended to help you connect your SIP Endpoints to Twilio.

Be aware, due to the large number of versions, variations, add-ons, and options for many of these systems, the settings you see may differ from those shown in our Configuration Guides. As such, these documents are intended as general guidelines, rather than configuration templates. We assume you're familiar with your network, SIP infrastructure and how they work.

Twilio cannot provide direct support for third-party products; you should contact the manufacturer for your SIP Endpoint for assistance in configuring such products.

If you wish to share your SIP Endpoint configuration guide to help us improve this section for other users, kindly submit them or any corrections to the existing guides to sip.interconnectionguides@twilio.com.

 

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.