In order to use Twilio Elastic SIP Trunking, you'll need a Twilio account. Sign up for a free Twilio account if you don't already have one.
Connect with your IP communications infrastructure:
REST API documentation:
In order to use Twilio Elastic SIP Trunking, you'll need to ensure that you have the following:
Sufficient Internet bandwidth to support the peak call traffic. The peak bandwidth can be determined by:
The 100 kbps value reflects the necessary bandwidth for the G711 codec plus sufficient room for overhead.
Log into the console and go to the "Elastic SIP Trunking" section. Your Dashboard will be displayed, providing a high level overview of your Trunking usage: Minutes, Calls & Cost.
On the left navigation menu you'll have links to:
Under the "Manage" menu you will have access to all of the configuration aspects of your Trunks. Specifically, you will have links to:
Twilio Elastic SIP Trunking is a cloud based solution that provides connectivity for IP-based communications infrastructure to connect to the PSTN, for making and receiving telephone calls to the 'rest of the world' via any broadband internet connection.
A trunk is composed of the following settings:
From the Trunks navigation bar item you'll be able to view a full list of your Elastic SIP Trunks and click on each one to modify its configuration. You also have the ability to delete a given trunk from this view.
From the Trunks navigation bar click on "Create New Trunk" to create a new trunk. This may also be done from the Getting Started section.
These settings apply to the entire trunk regardless of the direction of your traffic.
Provide a friendly name for your trunk.
This is the unique identifier of this trunk, and is assigned automatically once you create a trunk.
From this drop-down you can enable call recording for this trunk. When enabled, all calls are recorded (both origination and termination traffic), in a pay-as-you-go consumption model. Recording options for a single channel or dual channels can be selected. The default setting of a trunk is Do Not Record. You can select:
Twilio extended the maximum call duration on Elastic SIP Trunking calls from 4 hours to 24 hours. This allows the business to have extended conversations that last longer than 4 hours. You can see details here.
Encryption ensures that the call media and associated signalling remains private during transmission. Transport Layer Security (TLS) provides encryption for SIP signaling and Secure Real-time Transport Protocol (SRTP) provides encryption for call content/media packets. Learn about how to enable and troubleshoot TLS issues from this blog.
The TLS protocol is designed to establish a secure connection between a client and a server communicating over an insecure channel. RFC 5246, the Transport Layer Security (TLS) Protocol, Version 1.2, specifies Version 1.2 of the Transport Layer Security (TLS) protocol.
TLS Specifications:
TLSv1.0
,
TLSv1.1
and
TLSv1.2
.
PLEASE NOTE: To better comply with security requirements, we have deprecated TLSv1.0 and TLSv1.1 for inbound and outbound Elastic SIP trunking calls.
If your SIP infrastructure requires using TLSv1.0 or TLSv1.1, you can configure your Twilio Account to allow these deprecated versions in your console under Voice → Settings → Allow Deprecated SIP/TLS versions. If this setting is enabled, your SIP endpoints can use the deprecated TLSv1.0 and TLSv1.1 versions for SIP signaling sent to or received from Twilio. If disabled, only non-deprecated TLSv1.2+ is allowed.
Twilio strongly recommends the use of TLS version 1.2 when connecting your SIP infrastructure.
ECDHE-ECDSA-AES128-GCM-SHA256
,
ECDHE-RSA-AES128-GCM-SHA256
,
ECDHE-ECDSA-AES128-SHA256
,
ECDHE-RSA-AES128-SHA256
,
ECDHE-ECDSA-AES256-GCM-SHA384
,
ECDHE-RSA-AES256-GCM-SHA384
,
ECDHE-ECDSA-AES256-SHA384
,
ECDHE-RSA-AES256-SHA384
,
AES128-GCM-SHA256
,
AES128-SHA256
,
AES128-SHA
,
AES256-GCM-SHA384
,
AES256-SHA256
,
AES256-SHA
PLEASE NOTE: When TLS is enabled, you will no longer be able to view the SIP signalling packets in the PCAP captures within the Call Logs section.
SRTP provides a framework for the encryption of RTP & RTCP. RFC 4568, Session Description Protocol (SDP) Security Description (SDES) for Media Streams, defines such a protocol specifically designed to exchange cryptographic material using a newly defined SDP crypto attribute.
SRTP Specifications:
AES_CM_128_HMAC_SHA1_80
AES_CM_128_HMAC_SHA1_80
and
AES_CM_128_HMAC_SHA1_32
. Both may be included in an order of preference.
When Secure Trunking is enabled, any non-encrypted calls will be rejected. Please ensure you configure the use of TLS in your
Origination Settings by including the transport=tls
parameter. If the transport parameter is present on any of your URIs specifying a different transport (e.g. transport=udp
), it will be ignored and TLS will be used. By default port 5061 will be used for TLS, however you may specify the port you wish to use in your Origination URI.
TLS is used to encrypt SIP signaling between SIP endpoints. In order for this to function properly, devices in your network that communicate directly with Twilio must be configured to trust Twilio's TLS/SSL Certificate. Twilio uses certificates issued by a CA (Certificate Authority). You may need to add additional root certificates to your communications infrastructure to establish the authenticity of Twilio's certificate on the network. Download Twilio's bundle of trusted CA certificates. (Last updated September 1, 2023).
Note: the current bundle contains the following root certificates:
Please be aware that the Twilio CA bundle may be updated in the future, for example when root certificates expire or are distrusted by the CA. In such cases we will notify you to update your SIP devices. Please ensure that your email address is up to date in your account information to ensure you receive such communication.
Asterisk ships by default with chan_sip
driver and works well with Twilio. However, if you have some reason to run PJSIP
driver with Asterisk, please note the following:
PJSIP 2.5
and it does not work with Twilio for TLS/SRTP purposes. Non-encrypted calls do work
PJSIP
driver, which at this time is 2.5.5. Twilio works well with it despite the following message appearing in your log:
PJSIP 2.5.5
outputs the following error but the call is still shown to work.
1Sep 27 13:03:56] ERROR[10886]: pjproject:0 : tlsc0x7f217c03 RFC 5922 (section 7.2) does not allow TLS wildcard certificates. Advise your SIP provider, please!2
The following link is a guide to installing a non-bundled version of PJSIP
. Change the version to 2.5.5 in the steps.
When Call Transfer is enabled, Twilio will consume an incoming SIP REFER from your communications infrastructure and create an INVITE message to the address in the Refer-To header. Please go here for more details.
In general, your IP communications infrastructure should use your public IP address in the SDP and that will be the ONLY destination where Twilio will send media towards. However, if you're traversing a non-SIP aware NAT, you may not know your public IP and your SDP will include your private IP address, typically leading to one-way audio issues. Twilio is able to resolve this by latching onto the incoming RTP media stream and sending RTP towards that destination by enabling Symmetric RTP.
When Symmetric RTP is enabled Twilio will detect where the remote RTP stream is coming from and start sending RTP to that destination instead of the one negotiated in the SDP. Please note that this setting is more vulnerable to RTP attacks.
When Symmetric RTP is disabled, Twilio will send RTP to the destination negotiated in the SDP. This setting is considered to be more secure and therefore recommended.
Configuring your termination settings will allow you to place outgoing traffic from your communications infrastructure to the PSTN. In order to use a trunk for termination it must have a Termination SIP URI and at least one authentication scheme (IP Access Control Lists and/or Credentials Lists).
Configure a SIP Domain Name to uniquely identify your Termination SIP URI for this trunk. This URI will be used by your communications infrastructure to direct SIP traffic towards Twilio.
{example}.pstn.twilio.com
Twilio recommends that you use a dash instead of a dot to improve readability of your domain. However, in some cases you may prefer a sub-domain like a.b.pstn.twilio.com of the higher-level domain b.pstn.twilio.com
A sub-domain like a.b.pstn.twilio.com can be created under the following requirements:
Configure a trunk on your communications infrastructure and point it towards
{example}.pstn.twilio.com
for outbound traffic towards Twilio.
If you wish to manually connect to a specific geographic edge location that is closest to the location of your communications infrastructure, you may do so by pointing your communications infrastructure to any of the following localized Termination SIP URIs:
{example}.pstn.ashburn.twilio.com
(North America Virginia)
{example}.pstn.umatilla.twilio.com
(North America Oregon)
{example}.pstn.dublin.twilio.com
(Europe Ireland)
{example}.pstn.frankfurt.twilio.com
(Europe Frankfurt)
{example}.pstn.singapore.twilio.com
(Asia Pacific Singapore)
{example}.pstn.tokyo.twilio.com
(Asia Pacific Tokyo)
{example}.pstn.sao-paulo.twilio.com
(South America São Paulo)
{example}.pstn.sydney.twilio.com
(Asia Pacific Sydney)
You can find the legacy localized URIs list here. eg: {example}.pstn.us1.twilio.com
Twilio's Elastic SIP Trunking uses an FQDN ({example}.pstn.twilio.com
) as a Termination URI that is used by your communications infrastructure to direct SIP traffic towards Twilio. As explained in the previous section, localized Termination URIs are available.
For example, {example}.pstn.ashburn.twilio.com
, this specific FQDN resolves in the following DNS A-Record:
Type | IP Address | TTL |
---|---|---|
A | 54.172.60.3 | 10 min |
A | 54.172.60.0 | 10 min |
A | 54.172.60.2 | 10 min |
A | 54.172.60.1 | 10 min |
For each edge location we have 3-4 IP addresses that are used for reliability purposes (see IP addresses. Each of these IP addresses represents a unique public edge for our Elastic SIP Trunking services into the Twilio cloud, distributed across multiple Availability Zones for reliability purposes.
It is highly recommended that you do not peg towards a single IP address but rather utilize all IP addresses and failover in case one IP is not responding.
A common strategy, which we deploy internally and what we have instructed our carriers to do towards us as well, is that if there is no response to an INVITE, go to the next IP after 4 seconds. A single machine behind a single IP will always fail at some point so the overall solution must take that into consideration and guard itself towards these failures.
Furthermore, if there is a complete Ashburn outage, it is recommended that you failover to another edge location (e.g. If connecting to ashburn
, failover to umatilla
), keeping in mind that the Edge Location will in turn resolve to 3-4 different IP addresses for reliability.
Configure the authentication details to ensure the security/authenticity of your termination traffic. You must configure a minimum of either an ACL or credential authentication. If you configure both, then both ACLs and credentials are enforced.
It is highly recommended that you configure User Credentials. IP ACL's alone does not protect against certain types of attacks.
To create a new Access Control List (ACL):
To create a new Credential List:
If you are using User Credentials, your SIP INVITE will be challenged with a
407 Proxy Authentication Required
requesting the appropriate user credentials.
By the end of this step your trunk will be able to process termination calls from your communications infrastructure, via Twilio, to the PSTN.
You must specify a Caller ID Number that either corresponds to a Twilio DID on your account or a Caller ID Number that has been verified on the Console or with the Outgoing Caller ID API.
If a Caller ID Number is not specified in the SIP INVITE's From Field, then the Remote-Party-ID or the P-Asserted-Identity will be used.
For Trial accounts, in addition to using a verified Caller ID, you can only call numbers that are also verified. To remove this restriction, Upgrade your account via the Console.
INVITE sip:+15108675309@{example}.pstn.ashburn.twilio.com SIP/2.0
Make sure that any phone numbers sent via SIP to Twilio are always
E.164-formatted (e.g.+12128675309
). If E.164 format is not used, then the
call will be rejected with a SIP 400 Bad Request
response.
Make sure your E.164 formatted number always includes +
. This plus prefix is a must.
Configuring your origination settings will allow you to receive incoming traffic from the PSTN to a Twilio number, delivered to your communications infrastructure. With phone numbers available in over 100 countries, Twilio gives you a truly global SIP Trunk. A minimum of one Twilio number should be associated with this trunk if you're configuring it for origination.
The origination settings configured in this section will apply to all numbers associated with this trunk.
Configure your origination SIP URI, which identifies the network element entry point into your communications infrastructure (e.g. IP-PBX, SBC). The host part of the SIP URI may be either an IP address or a Fully Qualified Domain Name (FQDN).
sip:172.56.42.132
sip:mysbc.com
Twilio will automatically populate the user part of the SIP URI based on the Twilio number the call from the PSTN is destined towards. For example, if the call from the PSTN is received for Twilio number +14158675309, which is associated with this trunk, the resulting URI sent to your communications infrastructure will be:
sip:+14158675309@172.56.42.132
sip:+14158675309@mysbc.com
Alternatively, you may also configure a specific user-part (e.g. "anniebp") within the origination SIP URI. Note that the same URI will be used for all Numbers associated with this trunk. Hence, if the call from the PSTN is received for Twilio number +14158675309, which is associated with this trunk, the resulting URI towards your communications infrastructure will still be the following for all phone numbers:
sip:anniebp@172.56.42.132
sip:anniebp@mysbc.com
Note: The Twilio number dialed (+14158675309) will always be conveyed in
a SIP Diversion
header for Trunking Origination calls.
It is possible to send any SIP header beginning with the X-
prefix, by
appending them to the origination SIP URI. For example, you could configure:
sip:+14158675309@mysbc.com?X-myheader=foo
to send X-myheader:foo
on all originated calls.
By default, Twilio sends originating SIP requests towards your communications infrastructure over UDP. This may be customized to be sent over TCP rather than UDP. Change this by using the transport parameter in the origination SIP URI:
sip:anniebp@172.56.42.132;transport=tcp
Alternatively, you may customize it to use TLS for SIP signalling. When using TLS, the default port will be 5061, however a different one may be specified. Change this by using the transport parameter in the origination SIP URI, and optionally by specifying a different port number:
sip:anniebp@172.56.42.132:5062;transport=tls
Note: Elastic SIP Trunking Origination URI configurations using the sips
URI scheme in order to enable end-to-end encryption is NOT supported by Twilio. However, we do support sip
URI schemes using transport=tls
for point-to-point encryption.
If you configure your Elastic SIP Trunking Origination URIs to use sips
schemes, these sips
URIs will be handled as if they were sip
URIs using TLS transport. Twilio will effectively adjust the URI internally to instead be routed using the sip
scheme and transport=tls
on the outbound messages, resulting in point-to-point encryption between Twilio and the customer equipment.
Twilio strongly suggests not using sips
schemes in your Twilio SIP configurations, as this could cause possibly unintended behavior, due to how we process such URIs. Instead, we suggest using sip
schemes with TLS transport. This method, along with the security of our voice architecture and Super Network, is an effective way of adding encryption to your Twilio SIP connections.
To specify the geographic edge from which Twilio will send the originating SIP traffic towards your communication infrastructure, you must include the edge
parameter in your Origination SIP URI. For example, if the edge=dublin
parameter is included in your Origination SIP URI, Twilio will send the SIP traffic from the Europe Ireland edge location:
sip:anniebp@172.56.42.132;edge=dublin
If the edge
parameter is not specified or is incorrect, Twilio will send the Originating SIP traffic from the edge location where the incoming PSTN call comes in.
Note: You must make sure you allow the IP addresses of the Twilio edge location for SIP signalling and RTP media traffic.
This parameter was previously named region
and it is still supported. View a list of legacy region identifiers here. eg: sip:anniebp@172.56.42.132;region=ie1
It is possible to configure up to ten (10) Origination SIP URIs with different priority & weight.
The priority field determines the precedence of use of the SIP URI. Twilio will always use the SIP URI with the lowest-numbered priority value first, and fallback to other SIP URIs of equal or higher value if the session to that SIP URI fails.
If a service has multiple origination SIP URIs with the same priority value, Twilio will use the weight field to determine which SIP URI to use. The weight value is relevant only in relation to other SIP URIs with the same priority value.
Priority
ranks the importance of the URI. Values range from 0 to 65535, where the lowest number represents the highest importance. Weight
is used to determine the share of load when more than one URI has the same priority. Its values range from 1 to 65535. The higher the value, the more load a URI is given.
It is possible to enable or disable an origination SIP URI. When an origination SIP URI is enabled, it's active in the route selection. If it is not enabled, then it will not be used for routing traffic towards your communications infrastructure.
In the following example, both the priority and weight fields are used to provide a combination of load balancing and failover services.
Origination SIP URI | Priority | Weight |
---|---|---|
sip:mysbc1.com | 10 | 60 |
sip:mysbc2.com | 10 | 20 |
sip:mysbc3.com | 10 | 20 |
sip:mysbc-backup.com | 20 | 10 |
The first three SIP URIs share a priority of 10, so the weight field's value will be used Twilio to determine which server to contact. The sum of all three values is 100, so sip:mysbc1.com
will be used 60% of the time. The two SIP URIs sip:mysbc2.com
and sip:mysbc3.com
will be used for 20% of requests each. If sip:mysbc1.com
is unavailable, these two remaining machines will share the load equally, since they will each be selected 50% of the time.
If all three servers with priority 10 are unavailable, the record with the next lowest priority value will be chosen, which is sip:mysbc-backup.com
.
Note: If any of the following SIP status codes are returned ("2xx", "400", "404", "405", "410", "416", "482", "484", "486", "6xx"), Twilio will not fail over to the next origination SIP URI. If there is no SIP response from a given server, Twilio will fail over after 4 seconds.
In the case of a disaster preventing your calls from being delivered to your origination SIP URI above, you can configure a Disaster Recovery URL pointing to an application built on Twilio's powerful scripting tool called TwiML. You can use TwiML to build an application that will manage calls as required by your disaster recovery plan, including replicating the functionality of your PBX (e.g. IVR).
http://fallback.mycompany.com/index
For more information on building your TwiML application, please refer to the Twilio QuickStart and TwiML API Guide. Please note that when calls are redirected to your disaster recovery URL, normal Twilio Voice rates apply: see voice pricing.
CNAM is an acronym which stands for Caller ID Name. CNAM is used to display the calling party's name alongside the phone number, to help users easily identify a caller.
When you enable CNAM Lookup, the Caller ID Name is inserted in the SIP INVITE via the "From", and "Contact" and (if applicable) "P-Asserted-Identity" fields for each caller.
Note that CNAM lookups for US/CA numbers are billed per lookup, even if data may not be available. Currently, requesting Caller ID Name Lookup for international numbers will return null values, but will not be billed.
To enable CNAM Lookup using the console, log into the console and go to the "Elastic SIP Trunking" section.
When you have selected a Trunk, navigate to the "Origination" Settings (via the left-hand sub-menu). Here, you will see a switch where you can enable CNAM Lookup. You will know the setting has been enabled when the switch has turned 'blue' and the word 'ENABLED' appears.
Call redirect enables you to redirect a Trunking Origination call. Your communications infrastructure can redirect an incoming INVITE by responding with a SIP 302 (Moved Temporarily). This response contains a contact header field with the new addresses that should be tried.
Contact
header except the first one or multiple SIP
Contact
headers except the first one will be ignored.
*.sip.twilio.com
or
*.pstn.twilio.com
) are not supported
edge
parameter is not supported in a SIP 302 contact URI. The redirected call will use the same egress edge location as the original call
tnx
parameter is not supported in a SIP 302 contact URI. The redirected call will use the same Interconnect Connection as the original call
When Twilio receives incoming traffic on your Twilio numbers from the PSTN to be directed to your communications infrastructure, it will add a SIP Diversion
header noting the Twilio number that was dialed. This header serves as a historical record that indicates that the call was diverted from the dialed number to the Origination SIP URI of your SIP Trunk. An example of what this Diversion
header might look like is shown below.
Diversion: <sip:+14155550000@twilio.com>
When Twilio receives outgoing traffic from your communications infrastructure to the PSTN, your SIP message can sometimes include SIP Diversion
headers if the call was previously forwarded. Twilio will forward SIP Diversion
headers it receives to the carriers.
To combat any malicious addition of Diversion headers, Twilio will check all Diversion headers it receives that contain the Twilio domain. Twilio will verify that the phone number included in the header matches one associated with your Twilio account (either a Twilio number owned by the account or a verified Caller ID). If the header fails this check, Twilio will remove the header.
From this tab you will be able to:
In the "Numbers" section you will be able to view all numbers currently
associated with this trunk. Recall that all of these numbers share the same
origination & general settings.
You may click on a given number to view/modify its configuration.
A minimum of a single Twilio Phone Number is required to be able to receive
incoming calls from the PSTN to your communications infrastructure via your
Twilio Trunk.
Make sure you have all your trunk configuration changes saved, and then from
the "Numbers" section select "Buy a Number".
Select the country code, and search for available numbers matching any patterns
(e.g. +14158675309) you might want to look for in your number.
Once you find the Twilio number you would like to buy, go ahead and purchase it
and continue to set up your number.
This will take you to the number view where you can modify the configuration
for that number.
Under the "Voice" section select the "SIP Trunking" radio button, and from the
dropdown list below select the desired SIP Trunk you would like to associate
this Number with. Don't forget to save your configuration changes.
In the "Numbers" section select "Associate a Number with this Trunk", which
will display a list of all of your existing Twilio numbers. Click on the one
you would like to associate with this trunk.
This will take you to the number view where you can modify that number's
configuration. Under the "Voice" section, select the "SIP Trunking" radio
button, and from the dropdown list below select the desired SIP Trunk you would
like to associate this number with. Don't forget to save your configuration
changes.
You can disassociate a number from a trunk in several ways:
Note that when you do this, the number is disassociated from the trunk but it
is not released from your account.
Twilio phone numbers are billed on a monthly basis. Unless you are actively
using a number, or you want to keep a number reserved for future use, you can
reduce your costs by releasing your unused numbers. In order to release the
number, go to the "Voice and Messaging" section, click on "Numbers" and
release the desired number from that page.
Make your first test call by dialing your trunk's Twilio number, e.g.
+14158675309
, and ensure your corresponding communications infrastructure
extension rings.
You can delete a trunk:
Note that when you do this, all numbers previously associated with this trunk will be disassociated from the trunk, but they will not be released from your account. Twilio phone numbers are billed on a monthly basis. Unless you are actively using a number, or you want to keep a number reserved for future use, you can reduce your costs by releasing your unused numbers. In order to release the number, please go to the "Voice and Messaging" section, click on "Numbers" and release the desired number from that section.
Prepare your communications infrastructure to make sure that your SIP infrastructure has connectivity to Twilio and vice versa.
Max-Forwards
header per RFC 3261 section 8.1.1.6,
to ensure your call is processed successfully.
example.pstn.twilio.com
)); the Twilio platform will respond appropriately. Please maintain the Ping lower than 1 SIP OPTIONS every 10-15 seconds to avoid your requests from being banned by our Platform.
If you're deploying behind a NAT without a Session Border Controller, it's important to keep open the NAT translation binding.
You MUST allow ALL of Twilio's following IP address ranges and ports on your firewall for SIP signalling and RTP media traffic. This is important if you have Numbers in different edge locations and for resiliency purposes (e.g. if North America Virginia gateways are down, then North America Oregon gateways will be used). Twilio does not guarantee which edge location the media will egress from, without using the edge
parameter since it can depend on which PSTN-SIP Gateway delivers the call to which Twilio edge location.
Please see Twilio's Elastic SIP Trunking IP addresses for the complete list.
For further information to help you configure your infrastructure with your Twilio Elastic SIP Trunk, refer to the SIP Trunking configuration guides.