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 and TLSv1.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.
• Secure Media
  • Sending SRTP to Twilio: Twilio supports the following Crypto suites: AES_CM_128_HMAC_SHA1_80 and AES_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
• 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.

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.