Use SIP with Twilio Voice
Before you Begin
Before you can use SIP Interface, you must sign up for a Twilio account (if you don't already have one). To sign up for an account click here.
Overview
Connect your communications infrastructure to Twilio and start building programmable voice applications, such as call centers and IVRs, with Twilio’s powerful and flexible voice capabilities. You can connect to Twilio over the public internet or alternatively via a private connection using Twilio’s Interconnect. Programmable Voice SIP lets you route your voice calls with global reach to any landline phone, mobile phone, browser, mobile app, or any other SIP endpoint.
The following diagram illustrates the position of the Twilio Cloud in the call flows.
What is SIP?
Session Initiation Protocol (SIP) is a standardized communications protocol that has been widely adopted for managing multimedia communication sessions for voice and video calls. SIP may be used to establish connectivity between your communications infrastructures such as an on-premise or virtual PBX and Twilio's communications platform.
Sending SIP to Twilio
Twilio’s Programmable Voice SIP Interface product enables you to use your existing SIP communications infrastructure to initiate SIP sessions with the Twilio Cloud. SIP Interface uses Twilio’s TwiML language and/or Twilio’s REST APIs to create advanced voice applications. Learn how to get started connecting your SIP communications infrastructure to the Twilio Cloud.
Receiving SIP from Twilio
Twilio’s Programmable Voice SIP Interface product enables your advanced voice applications to initiate SIP sessions from the Twilio Cloud towards your existing SIP communications infrastructure using Twilio’s TwiML language and/or Twilio’s REST APIs. Learn how to get started connecting the Twilio Cloud to your SIP communications infrastructure.
Limits
Make sure you are aware of the following Programmable Voice SIP Domain limits.
- 100 SIP Domains per Account or Sub Account
- IP Access Control Lists (ACLs) limits
- Credential Lists limits
- SIP Registration limits
Features
SIP Registration
Twilio allows you to register your SIP Phones or SIP Endpoints with Twilio. SIP Registration is used to identify the location of the SIP Endpoints. Therefore, the user can receive calls irrespective of physical location of the SIP Endpoint.
This feature allows your SIP Endpoints can send REGISTER request to Twilio. For details see here.
Call Transfers using SIP REFER from Twilio
Call transfer enables you to move an active call from one endpoint to another, in SIP this is accomplished using the SIP REFER method.
Twilio supports initiating SIP REFER method from Twilio towards your IP communications infrastructure leveraging the <Refer> verb.
SIP Custom Header
SIP custom header allows you to send customized headers.
UUI (User-to-User Information) Header
UUI header allows you to send contextual information over the SIP call. You can check Sending-sip with UUI and Receiving-sip with UUI for further UUI details.
DTMF
Twilio supports RFC-2833 for sending and receiving DTMF.
Media codec
Twilio supports G.711 μ-law (PCMU) and A-law (PCMA) codecs for media. These are the most popular codecs used by carriers so transcoding is unnecessary.
Securing SIP Traffic using TLS
Encryption ensures that the call signaling remains private during transmission. Transport Layer Security (TLS) provides encryption for SIP signaling.
To enable TLS, ensure that you have imported Twilio's Root CA Certificate. There is no further configuration required for TLS and you can start sending over port 5061 straight away. TLS Functionality/Port 5061 is always active and does not require a manual toggle like Secure Media. To stop using TLS, simply send SIP to Port 5060 or remove the transport=tls parameter.
SIP Interface supports the following configurations for TLS:
- 5060 (no TLS, No Secure Media)
- 5061 (TLS, No Secure Media)
- 5061 (TLS, Secure Media)
For calls where TLS is active this will cause certain functionality to behave differently:
- SIP PCAPs from the console will produce only a blank file.
- Call meta data will continue to be available for example major error codes, start time, end time, to/from.
- SIP Refer will function as expected using TLS.
When sending TLS SIP traffic to Twilio, you will need to ensure that your infrastructure is using next-hop domain as opposed to next-hop ip. This is a common misconfiguration and will cause a 403 error that will not be visible on your Twilio account. Traffic must be sent to the domain {example}.sip.{region}.twilio.com
, rather than an IP address in order to associate the traffic with your Twilio account.
Secure Media
Secure Media uses encryption to ensure that the call media and associated signaling remains private during transmission. Secure Real-Time Protocol (SRTP) provides encryption for media. For details see here.
TLS/SRTP Specifications
- SIP TLS
- Versions: Twilio supports
TLSv1.0
,TLSv1.1
andTLSv1.2
.
PLEASE NOTE: To better comply with security requirements, we have deprecated TLSv1.0 and TLSv1.1 for inbound and outbound SIP calls, as well as SIP registration.
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. - Ciphers:
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
- If you are using TwiML to send SIP from Twilio, to enable encryption you must use the
transport=tls
parameter in your SIP noun in your Dial verb. - By default port 5061 will be used for TLS, however, you may specify the port you wish to use in your URI.
- Versions: Twilio supports
- Secure Media
- Sending SRTP to Twilio: Twilio supports the following Crypto suites:
AES_CM_128_HMAC_SHA1_80
andAES_CM_128_HMAC_SHA1_32
. Both may be included in your order of preference. - Receiving SRTP from Twilio: Only a single crypto suite will be advertised:
AES_CM_128_HMAC_SHA1_80
- Sending SRTP to Twilio: Twilio supports the following Crypto suites:
- Importing Twilio's Root CA Certificate TLS is used to encrypt SIP signaling between SIP endpoints. In order for this to function properly it is required that certain devices in the network import a CA certificate. Twilio uses certificates from a CA (Certificate Authority). It is important that you add the following root certificate to your communications infrastructure to establish its authenticity. Download Twilio's CA certificate.
It is important to note that Twilio uses a wildcard certificate which can be used for multiple subdomains of a domain (*.sip.twilio.com). If your network element does not support wildcarded certificates please disable certificate validation.Twilios Root CA contains a certificate chain signed by multiple Certificate Authorities. You should import the entire PEM file rather than individual certificates.
Twilio does not support importing root certificates from a third party at this point in time. In order to use Twilio Voice with TLS, the Twilio Root CA must be used.
Note: Twilio SIP Interface outbound call 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 SIP Interface 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.
IP addresses
Prepare your communications infrastructure to make sure that your SIP infrastructure has connectivity to the Twilio Cloud and vice versa. To ensure that your communications infrastructure doesn’t block communication, you must update your list of allowed IP addresses. We strongly encourage you to allow all of the following IP address ranges and ports on your firewall for SIP signaling and RTP media traffic.
This is important if you have Numbers in different regions as well as for availability purposes (e.g. if North America Virginia gateways are down, then North America Oregon gateways will be used).
Please see Twilio's SIP IP addresses for the complete list.
Glossary
Communications Infrastructure
A broad term to refer to IP-PBX, SBC, IP-phones, etc...
SIP Endpoint
IP-phone or a soft client with which a user initiates a VoIP call
SIP URI
Equivalent to a SIP phone number and takes the form, sip:username@SIPDomain
Twilio SIP Domain
It takes the form {example}.sip.{region}.twilio.com
where {example}
is specified by the customer and {region}
is the data center where the registrar is located. Initially only us1
.
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.