Bring Your Own Carrier (BYOC) Trunking for Programmable Voice
Twilio Bring Your Own Carrier Trunking, or BYOC Trunking for Voice, allows you to use your existing PSTN Voice Carrier partner(s), keep your phone numbers with that Carrier, and add Twilio Programmable Voice capabilities to those calls/numbers. BYOC Trunking lets you control your voice connectivity, while unlocking the agility, scalability, and global reach Twilio is known for.
- Porting is no longer a barrier; keep your existing carriers, numbers and regulatory compliance
- Continue to use your existing Infrastructure; you decide when to deprecate
- One application, many uses; solve problems anywhere, regardless of your PSTN connection(s)
- Twilio's Super Network keeps you up and running, even if your carriers are not
{example}.sip.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.sip.twilio.com of the higher-level domain b.sip.twilio.com
A sub-domain like a.b.sip.twilio.com can be created under the following requirements:
- The higher-level domain (b.sip.twilio.com) must be created first
- The higher-level domain (b.sip.twilio.com) must be created by the same account or the parent account
Then you or your PSTN carrier would configure a trunk on your/their communications infrastructure (e.g. IP-PBX or SBC), and point it towards {example}.sip.twilio.com for outbound traffic towards Twilio.
Show Localized URIs: If you wish to manually connect to a specific geographic region that is closest to the location of your communications infrastructure, you may do so by pointing your/their communications infrastructure to any of the following localized Termination SIP URIs:
-
{example}.sip.us1.twilio.com(North America Virginia) -
{example}.sip.us2.twilio.com(North America Oregon) -
{example}.sip.ie1.twilio.com(Europe Ireland) -
{example}.sip.de1.twilio.com(Europe Frankfurt) -
{example}.sip.sg1.twilio.com(Asia Pacific Singapore) -
{example}.sip.jp1.twilio.com(Asia Pacific Tokyo) -
{example}.sip.br1.twilio.com(South America São Paulo) -
{example}.sip.au1.twilio.com(Asia Pacific Sydney)
Note: Redundancy with Termination URIs: Twilio's SIP Interfaces use an FQDN ({example}.sip.twilio.com) as a Termination URI that is used by communications infrastructures to direct SIP traffic towards Twilio. As explained in the previous section, localized Termination URIs are available.
For example, {example}.sip.us1.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 region 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 SIP Interfaces service 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 US1 outage, it is recommended that you failover to another region (e.g. If connecting to US1, failover to US2), keeping in mind that that region will in turn resolve to 3-4 different IP addresses for reliability.
Static IP Address (Limited Availability)
Warning
This feature is not currently available when using Twilio Regions Ireland (IE1) or Australia (AU1). This is currently only supported with the default US1 region. A full list of unsupported products and features with Twilio Regions is documented here.
Static IP Addresses: To select one of your already-configured Static IP Addresses, click the "Static IP LIsts" Pull-Down Menu here and choose the one you want to use. If you do not have any Static IP Addresses already configured, or want to add a new one, click the "+" button to the right of the Pull-Down Menu.
NOTE: Static IP Address(es) for your Termination SIP Domain are used only when addressing Twilio via IP Addresses instead of an FQDN. When Static IP Addresses are used, the IP-ACLs listed below will NOT be used for Authentication. Static IP addresses require a Twilio Interconnect connection on your account; the Static IP addresses used here must be a subset from the IP addresses configured on your Twilio Interconnect connections.
Limited Availability: Please contact your Twilio Sales Representative or talk to Twilio Sales if you require a Static IP address for your BYOC Trunk.
Authentication
Configure the authentication details to ensure the security/authenticity of your termination traffic. You must configure a minimum of either an IP Access Control List (ACL) or Credential authentication on your BYOC Trunk's Termination SIP Domain. If you configure both, then both ACLs and Credentials are enforced.
IP Access Control Lists: To select one of your already-configured ACLs, click the "IP Access Control Lists" Pull-Down Menu here and choose the one you want to use. If you do not have any ACLs already configured, or want to add a new one, click the "+" button to the right of the Pull-Down Menu.
Credential Lists: To select one of your already-configured Credential Lists, click the "Credential Lists" Pull-Down Menu here and choose the one you want to use. If you do not have any Credential Lists already configured, or want to add a new one, click the "+" button to the right of the Pull-Down Menu.
Note: It is highly recommended that you configure User Credentials. IP ACLs alone does not protect against certain types of attacks.
Call Control Configuration Configure With: As you are configuring the Domain for a BYOC Trunk, this setting is set to "BYOC Trunk".
SIP Trunk: To select one of your already-configured Credential Lists, click the Pull-Down Menu here and choose the one you want to use.
Secure Media
Enabled/Disabled: Select whether to enable or disable secure communications (TLS/SRTP) for your BYOC Termination traffic.
NOTE: This switch is only effective on Termination (inbound) traffic from your PSTN Carrier; it does not affect Origination traffic on the linked BYOC Trunk.
Configuring your Origination Connection Policy settings will allow you to originate outbound traffic from Twilio, and have it delivered to your PSTN Carrier.
To edit or delete one of your already-configured Origination Connection Policies, click that OCP in the list. If you do not have any OCPs already configured, or want to add a new one, click the "+" button.
Properties
Friendly Name: Provide a friendly name for your Origination Connection Policy.
Origination Connection Policy SID: This is the unique identifier of this OCP, and is assigned automatically once you create the policy.
Origination Target
To edit or delete an already-configured Origination URI, click that URI in the list. If you do not have any Origination URIs already configured, or want to add a new one, click the "+" button.
Origination URI: Configure your origination SIP URI, which identifies the network element entry point into your PSTN Carrier. The host part of the SIP URI may be either an IP address or a Fully Qualified Domain Name (FQDN). You can use multiple origination URIs for failover or load balancing.
Priority: 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. Priority ranks the importance of the URI. Values range from 0 to 65535, where the lowest number represents the highest importance.
Weight: The weight value is relevant only in relation to other SIP URIs with the same priority value. Weight is used to determine the share of load when more than one URI has the same priority. Weight values range from 1 to 65535. The higher the value, the more load a URI is given.
Enabled: Enable/Disable the specific Origination Target.
To edit or delete one of your already-configured ACLs, click that Friendly Name in the list. If you do not have any ACLs already configured, or want to add a new one, click the "+" button.
Properties
Friendly Name: Give the Access Control List a friendly name that is descriptive of that list of IPs. Something like "Dallas Datacenter IPs".
Add an IP Address Range
CIDR Network Address: Add IP addresses or ranges in CIDR notation to your new IP Access Control List (these should be the IP addresses used for outbound SIP traffic by your Communications Infrastructure border elements, e.g. SBC). Friendly Name: Give your IPs a friendly name that is descriptive of what that IP is, for example "Production SBC".
To edit or delete one of your already-configured Credential Lists, click that Friendly Name in the list. If you do not have any Credential Lists already configured, or want to add a new one, click the "+" button.
Properties
Friendly Name: Give the Credential List a friendly name that is descriptive of the user you're authenticating. Something like "Admin, Twilio".
Add Credentials
Username: Enter a username (these should be the username used for digest authentication for outbound SIP traffic by your communications infrastructure border elements, e.g. SBC). Password: Enter the corresponding password for that user.
Note: If you are using User Credentials, a SIP INVITE to your Twilio Termination SIP Domain will be challenged with a 407 Proxy Authentication Required requesting the appropriate user credentials.
You can make calls over your BYOC Trunk to your PSTN Carrier using either TwiML, the Voice API Calls resource, or by adding a participant to an existing Conference.
Dialing via TwiML is done using the byoc parameter of the <Dial> verb's <Number> noun. The syntax is as follows:
<Dial><Number byoc="{Your-BYOC=Trunk_SID}">+14158675309</Number></Dial>
Dialing via the Voice API is done using the Byoc parameter of the Calls resource. The syntax can be gleaned from the following Curl example:
curl 'https://api.twilio.com/2010-04-01/Accounts/{Your Account SID}/Calls.json' -X POST --data-urlencode 'To=+14158675309' --data-urlencode 'From=+14155551212' --data-urlencode 'Url={Your Twilio App URL}' --data-urlencode 'Byoc={Your-BYOC=Trunk_SID}' -u {Your Account SID}:{Your Auth Token}
Adding participants to an existing Conference can be done using the Byoc parameter of the Participant resource. The syntax can be gleaned from the following Curl example:
curl https://api.twilio.com/2010-04-01/Accounts/{Your Account SID}/Conferences/{Your Conference SID}/Participants.json -X POST --data-urlencode "From=+14155551212" --data-urlencode "To=+14158675309" --data-urlencode 'Byoc={Your-BYOC=Trunk_SID} -u {Your Account SID}:{Your Auth Token}
Your PSTN Carrier should point their SIP traffic to a SIP Termination Domain URI that you have associated with your Twilio BYOC Trunk. If anyone makes a SIP request using that domain, (e.g. sip:alice@example.sip.us1.twilio.com), it will be routed over the internet to Twilio. When a SIP request is received on this domain, the BYOC Trunk is used to determine the authentication criteria and subsequently used to look up the configured URL to webhook to your application that will provide instructions on how to handle the incoming SIP call. See how Twilio passes data to your application.