Twilio BYOC

Use Twilio Bring Your Own Carrier (BYOC) with DIDWW SIP Trunking to receive calls on your DIDWW numbers in Twilio and to place outbound calls from Twilio through DIDWW. DIDWW delivers incoming calls to a Twilio SIP domain, and Twilio sends outbound calls to DIDWW through an origination connection policy.

• Receive calls on your DIDWW numbers in a Twilio application.

• Build incoming call flows with TwiML, Functions, or Studio.

• Connect incoming calls to your own application through a webhook.

• Start outbound calls through DIDWW using Twilio’s Calls API.

• Connect an active Twilio call to a phone number through DIDWW using TwiML.

• Use your DIDWW numbers as caller ID without porting them to Twilio.

---

1. Route Incoming Calls to Twilio

Create a SIP domain and a BYOC trunk in Twilio, then point a DIDWW Inbound SIP Trunk at the SIP domain. Calls to your DIDWW numbers reach the SIP domain, and the BYOC trunk tells Twilio how to handle them.

Before You Begin

• An active DIDWW account is required. Sign in to DIDWW or Create DIDWW account.

• At least one active DID number with capacity to receive incoming calls is required. Buy Numbers.

• An upgraded Twilio account is required. Twilio trial accounts can’t use BYOC trunks or SIP domains. Sign in to Twilio.

Step 1: Create an IP Access Control List

The IP access control list (ACL) allows the Twilio SIP domain to accept calls from DIDWW signaling IP addresses only.

1. In the Twilio Console, go to Communications > Voice > SIP domains.

2. Open the IP access control lists tab.

3. Click Create IP access control list.

Fig. 1. Opening the IP access control lists

4. In List friendly name, enter a name for the list (e.g., DIDWW).

5. In IP Address Range friendly name, enter a name for the first DIDWW IP address (e.g., New York).

6. In CIDR network address, enter 46.19.209.14.

7. Click Create.

Fig. 2. Creating the IP access control list

8. On the list page, click Create IP Address and add each remaining DIDWW signaling IP address with range 32:

   • Frankfurt: 46.19.210.14

   • Los Angeles: 46.19.212.14

   • Miami: 46.19.213.14

   • Singapore: 46.19.214.14

   • Hong Kong: 46.19.215.14

   • Amsterdam: 185.238.173.14

For the full list of DIDWW signaling addresses, see SIP connectivity reference.

Fig. 3. DIDWW signaling IP addresses added to the list

Step 2: Create a BYOC Trunk

1. In the Twilio Console, go to Communications > Voice > Bring your own carrier.

2. On the Trunks tab, click Create BYOC Trunk.

Fig. 4. Opening the BYOC trunks

3. In Trunk friendly name, enter a name for the trunk (e.g., DIDWW).

4. Click Create. The trunk page opens.

Fig. 5. Creating the BYOC trunk

Step 3: Configure How Twilio Handles Incoming Calls

1. On the BYOC trunk page, in Application configuration, click Edit configuration.

Fig. 6. Opening the application configuration

2. In Configure method, select how Twilio handles incoming calls: Webhook, TwiML Bin, Function, or Studio Flow.

3. Enter the URL of your application in Webhook URL, or select the TwiML Bin, Function, or Flow.

4. Click Save.

Note

Primary handler fails and Call status changes are optional. Use them to set a fallback handler and to receive call status callbacks. For examples of handling incoming calls, see the Twilio Voice documentation.

Fig. 7. Configuring the incoming call handler

Step 4: Create a SIP Domain

1. In the Twilio Console, go to Communications > Voice > SIP domains.

2. On the SIP domains tab, click Create SIP Domain.

Fig. 8. Opening the SIP domains

3. In SIP domain friendly name, enter a name for the domain (e.g., DIDWW).

4. In SIP URI, enter a unique name for the domain (e.g., didww-example). Twilio adds .sip.twilio.com to it.

5. In IP access control lists, select the list you created in Step 1.

6. Click Create.

Note

Copy the full SIP URI (e.g., didww-example.sip.twilio.com). You will enter it as the Host of the DIDWW Inbound SIP Trunk.

Fig. 9. Creating the SIP domain

7. On the SIP domain page, in Call control configuration, click Edit configuration.

8. In Configure method, select BYOC Trunk.

9. In BYOC trunk, select the trunk you created in Step 2.

10. Click Save.

Fig. 10. Sending SIP domain calls to the BYOC trunk

Step 5: Create a DIDWW Inbound SIP Trunk

1. In the DIDWW User Panel, go to Voice > Inbound Trunks.

2. Click Create New > SIP Trunk.

Fig. 11. Creating a new inbound SIP trunk

3. Enter a descriptive Name for the trunk (e.g., Twilio).

4. Select Static Endpoint.

5. In User Part of R-URI, enter {DID} to send the called number.

6. In Host, enter the Twilio SIP URI from Step 4 (e.g., didww-example.sip.twilio.com).

7. Click Create.

Note

For advanced SIP trunk configuration, see Create a SIP trunk.

Fig. 12. Configuring the inbound SIP trunk for Twilio

Step 6: Assign the Inbound SIP Trunk to Your DID Numbers

1. In the DIDWW User Panel, go to Phone Numbers > My Numbers.

2. Select the DID number(s) that will deliver calls to Twilio.

3. At the bottom of the page, click Batch Actions > Update Trunks.

Fig. 13. Selecting Update Trunks from the Batch Actions menu

4. In Voice IN trunk, select the Twilio SIP trunk you created earlier.

5. Click Confirm to apply the changes.

Fig. 14. Assigning the Twilio SIP trunk to the selected DID(s)

---

2. Enable Outbound Calling from Twilio through DIDWW

Create a DIDWW Outbound Trunk that authenticates calls by your Twilio Account SID, then add DIDWW as the origination target of your BYOC trunk.

Before You Begin

• Access to DIDWW Outbound Trunks is required for making outbound calls. See Get Access to DIDWW Outbound Termination.

• The BYOC trunk from Step 2: Create a BYOC Trunk is required.

Step 1: Copy Your Twilio Account SID

1. In the Twilio Console, go to Home.

2. In My Account, copy the Account SID.

Fig. 15. Copying the Twilio Account SID

Step 2: Create a DIDWW Outbound Trunk

1. In the DIDWW User Panel, go to Voice > Outbound Trunks.

2. Click Create New.

Fig. 16. Creating a new outbound trunk

3. Update the Friendly name (e.g., Twilio).

4. In Authentication method, select Twilio Account SID.

5. In Account SID, paste the Account SID you copied in Step 1.

6. Click Create.

Important

Each Twilio Account SID can be used by only one DIDWW Outbound Trunk. If DIDWW shows has already been taken, the SID is already in use on another outbound trunk. If that trunk is in your DIDWW account, use it instead of creating a new one. Otherwise, set up the integration in a Twilio subaccount and use the subaccount’s Account SID. The BYOC trunk, origination connection policy, Verified Caller IDs, and API requests must all belong to the same subaccount.

For advanced outbound trunk configuration, see Create an outbound trunk.

Fig. 17. Configuring the outbound trunk for Twilio

Step 3: Create an Origination Connection Policy

1. In the Twilio Console, go to Communications > Voice > Bring your own carrier.

2. Open the Origination connection policies tab.

3. Click Create Connection Policy.

Fig. 18. Opening the origination connection policies

4. In Policy Friendly name, enter a name for the policy (e.g., DIDWW).

5. Click Create. The policy page opens.

Fig. 19. Creating the origination connection policy

Step 4: Add DIDWW as the Origination Target

1. On the policy page, click Create Origination Target.

Fig. 20. Opening the origination target settings

2. In Origination SIP URI, enter sip:out.didww.com. To send calls to a specific DIDWW region, use one of the DIDWW outbound signaling endpoints instead.

3. Click Create.

Fig. 21. Adding the DIDWW origination target

Step 5: Attach the Policy to the BYOC Trunk

1. Go to Communications > Voice > Bring your own carrier.

2. On the Trunks tab, click the BYOC trunk you created for DIDWW.

Fig. 22. Opening the BYOC trunk

3. In Origination connection policy (to your carrier), click Edit origination policy.

Fig. 23. Opening the origination policy settings

4. In Destination, select the policy you created in Step 3.

5. Click Save.

The From domain setting on the BYOC trunk page is optional. DIDWW identifies Twilio calls by your Account SID, so outbound calls work without it.

Fig. 24. Attaching the DIDWW policy to the BYOC trunk

3. Verify Your DIDWW Number as a Caller ID

Verify your DIDWW number in Twilio to use it as the caller ID of outbound calls. Twilio requires a Twilio number or a Verified Caller ID as the From number of calls created with the Calls REST API, and as the callerId of TwiML <Dial> for calls that arrive over SIP.

Before You Begin

During verification, Twilio displays a 6-digit code and calls your DIDWW number. The number must reach a phone where you can answer the call and enter the code. For example, temporarily assign the number to a PSTN trunk that forwards calls to your mobile phone.

Step 1: Add a New Caller ID

1. In the Twilio Console, go to Communications > Numbers & senders > Overview.

2. Open the Verified Caller IDs tab.

3. Click Add a new Caller ID.

Fig. 25. Opening the Verified Caller IDs

4. In Country, select the country of your DIDWW number.

5. In Number, enter your DIDWW number without the country code.

6. In Send verification code via, select Call.

7. Click Verify number.

Fig. 26. Adding the DIDWW number as a caller ID

Step 2: Enter the Verification Code

1. Twilio shows a 6-digit code and calls your DIDWW number.

2. Answer the call and enter the code on the keypad.

3. When the verification is complete, the number appears on the Verified Caller IDs tab.

If you assigned the number to a temporary trunk for verification, assign it back to the Twilio inbound trunk. See Step 6: Assign the Inbound SIP Trunk to Your DID Numbers.

---

4. Test the Configuration

Step 1: Test Inbound Calling

Place a test call to your DIDWW DID number and check that Twilio handles it with the application you configured in Step 3: Configure How Twilio Handles Incoming Calls.

Step 2: Test Outbound Calling

To send a call through DIDWW, add the BYOC trunk SID to the call. The SID starts with BY and is shown on the BYOC trunk page. In the examples below, replace +12125550100 with your verified DIDWW number, +12125550199 with the destination number, and BYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with your BYOC trunk SID.

Option 1: TwiML. Add the byoc attribute to the <Number> noun of <Dial>. For example, save the TwiML below in a TwiML Bin and select the bin as the incoming call handler in Step 3: Configure How Twilio Handles Incoming Calls. When you call your DIDWW number, Twilio answers and connects you to the destination through DIDWW.

<Response>
  <Dial callerId="+12125550100">
    <Number byoc="BYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">+12125550199</Number>
  </Dial>
</Response>

Option 2: Calls REST API. Add the Byoc parameter to a Calls REST API request. Before you run the command, set the TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN environment variables to your Account SID and Auth Token. Replace https://example.com/voice with a publicly reachable URL that returns TwiML. Twilio requests it when the destination answers.

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \
  --data-urlencode "To=+12125550199" \
  --data-urlencode "From=+12125550100" \
  --data-urlencode "Byoc=BYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "Url=https://example.com/voice" \
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

Important

For calls created with the Calls REST API, Twilio accepts only a From number that is a Twilio number or a Verified Caller ID, even when the call goes through BYOC. Otherwise, Twilio rejects the call with error 21210. To use your DIDWW number as the From number, verify it as described in 3. Verify Your DIDWW Number as a Caller ID.

Place a test call using either method above. Check that the destination answers and that audio works in both directions. Confirm that the call appears in the DIDWW Outbound Call Logs to verify that it went through DIDWW.

Troubleshooting

DIDWW shows has already been taken for the Account SID

The Account SID is already used by another DIDWW Outbound Trunk. Use that trunk if it’s in your DIDWW account, or set up the integration in a Twilio subaccount. See Step 2: Create a DIDWW Outbound Trunk.

Twilio rejects a REST API call with error 21210

The From number isn’t a Twilio number or a Verified Caller ID. Verify your DIDWW number as described in 3. Verify Your DIDWW Number as a Caller ID.

Inbound calls do not reach Twilio

Check that:

• The SIP domain uses the IP access control list with all DIDWW signaling IP addresses.

• The Host of the DIDWW Inbound SIP Trunk matches the SIP domain URI.

• The SIP domain call control configuration uses the BYOC trunk.

Outbound calls do not go through DIDWW

Check that:

• The BYOC trunk uses the DIDWW origination connection policy.

• The call includes the BYOC trunk SID in the byoc attribute or the Byoc parameter.

• The DIDWW Outbound Trunk uses the Account SID of the Twilio account that places the call.

For Twilio diagnostics, see the Twilio BYOC documentation and the Twilio error 21210 reference.

Related resources

• Outbound SIP information — Look up DIDWW outbound signaling endpoints, transport ports, and the digest realm.

• SIP connectivity reference — Look up the DIDWW SIP IP addresses used for inbound calls.

• Inbound Call Logs — Review inbound call status and error codes.

• Outbound Call Logs — Review outbound call status and error codes.