Configure a 3CX PBX to use Twilio SIP Trunking

This guide explains how to connect a 3CX Private Branch Exchange (PBX) instance and Twilio Elastic Session Initiation Protocol (SIP) Trunking. This includes setting up emergency calling.

To create a 3CX PBX instance, log in to 3CX and create a 3CX-hosted PBX.

1. If you have an account, click login.
2. If you don't have an account, click create an account.
   • Sign up with a Google account or your own email.
   • If you use your email, provide your first and last name, company, phone number, country, region or state, language, and the number of users that might use your 3CX PBX.
3. Click Next.
4. After logging in, click Add System.
5. Follow the Installing 3CX guide
   1. When prompted for Which 3CX?, Choose 3CX Hosted.
   2. When finished with the 3CX steps, the page displays Creating your system along with a nine-minute countdown.
   3. When system creation succeeds, the 3CX admin site displays:
      • Login: URI where you access your 3CX PBX.
      • Username/Extension: A username you need to access your 3CX PBX.
      • Password: A hidden generated password you need to access your 3CX PBX.
        • To copy the password, click the Copy icon.
        • To view the password, click the Eye icon.
   4. Copy all of these values.
   5. Paste these into the temporary text file. You need these values in the Configure the SIP Trunk on 3CX section later in this guide.
6. Log in to your new 3CX PBX instance.
   A modal displays to encourage you to install the 3CX app. You can close this modal or click OK.
   The Dashboard for your 3CX PBX displays.
7. Copy two values from this screen. Both have a Copy icon to the left of them.
   • 3CX FQDN. You need this value when you configure the SIP trunk inbound traffic settings.
   • IPv4. You need this value when you create an access control list.
8. Paste these values into the temporary text file.
   To preserve these values in case of outage, save this text file to your local system.

1. Log in to your Twilio Console.
2. Click Explore products in the left side navigation.
3. Scroll to Super Network.
4. Click Elastic SIP Trunking.
5. Click Get Started.
6. Click Create a SIP Trunk.
7. Enter a human-readable name for your trunk in the Friendly Name field.
8. Click Create.
   The General Settings page displays for your new trunk. Ignore any settings on this page for the purposes of this guide.
9. Toggle Secure Trunking to Enabled.
10. If all settings look correct, click Save to preserve your settings.
    At the top of the page, a banner should appear that displays You have successfully updated your Trunk.

These settings configure how your trunk sends outgoing traffic to the PSTN and then the call recipient. This is also known as PSTN Termination.

1. If necessary, log in to your Twilio Console.

2. Click the link with your trunk name.
   The General Settings page displays.

3. Click Termination in the left side navigation.
   The Termination page displays.

4. Click Show Localized URIs.
   A list of URIs for Twilio's various Edge Regions around the world appears.

5. Type a unique hostname for your SIP trunk in the Termination SIP URI field. The list of localized URIs update with your SIP trunk hostname prepended to their domain.

   (information)

   Example of a regional SIP URI

   If you type mypbx into the Termination SIP URI field, the North America Virginia localized SIP URI displays mypbx.pstn.ashburn.twilio.com.

   If you use the default SIP URI, traffic to your PBX routes to <SIP_HOSTNAME>.pstn.ashburn.twilio.com.

6. To minimize latency, choose the SIP URI nearest to your physical PBX location.

7. Select the appropriate URI and copy this value.

8. Paste this value into the temporary text file.

Before you can save any settings on the Termination page, you must secure your SIP trunk. As you turned on Secure Trunking in the Create the SIP trunk in the Twilio Console section, Twilio can't continue until you configure an ACL and credentials for your trunk.

To secure your SIP trunk, configure an access control list (ACL) and credentials.

1. If necessary, log in to your Twilio Console.
2. Click the link with your trunk name.
   The General Settings page displays.
3. Click Termination in the left side navigation.
   The Termination page displays.
4. Scroll to the Authentication section of the Termination page.
5. Click + at the right of the IP Access Control Lists field. The New Access Control List modal displays.
6. Enter a human-readable description of this ACL in the Friendly Name field. This field has a limit of 64 characters.
7. Enter the IP address of the 3CX PBX you created in the CIDR Network Access field.
   CIDR stands for Classless Inter Domain Routing which defines a range of IP addresses.
   You can also copy the FQDN value from the temporary text file and paste it into this field.
8. Change the value of the dropdown menu to the right of that field to 32.
   • This sets the range to the single IP address.
   • Under the CIDR Network Address field, the modal should display a line that starts IP Address of ....
   • If it displays A range of IPs from..., you need to change the dropdown menu value to 32.
9. If this ACL appears correct, click Create new ACL.
   • This closes the Create new Access Control List modal and displays the [ACL Friendly Name] page. It should display:
     • The Friendly Name of the ACL you created
     • The CIDR Network Address with the [IP range friendly name] you created under the IP Address Range section
   • To add another IP range, click + Create new IP Address Range.
     This shouldn't be necessary for this setup.
10. Click + at the right of the Credential Lists.
    The New Credential List modal displays.
11. Enter a human-readable description for this Credential List in the Friendly Name field. This field has a limit of 64 characters.
12. In the Username field, Enter the username that passes to Twilio when authenticating SIP requests. This gets sent in response to Twilio's challenge of the initial INVITE. It can be up to 32 characters long.
13. In the Password field, enter the password that the username should use when authenticating SIP requests. The password requirements include:
    • 12 characters or more
    • one or more digits
    • both upper and lower case
14. If these credentials appear correct, click Create. This closes the New Credential List modal.

The Twilio Console saves these settings without prompting on creation. When you change these settings, click Save to preserve the changes.

These settings configure how your trunk receives incoming traffic from a caller to the PSTN. This is also known as PSTN Origination.

1. If necessary, log in to your Twilio Console.
2. Click Origination in the left side navigation.
   The Origination page displays.
3. Click Add new Origination URI.
   The Add Origination URL modal displays.
4. Copy the FQDN value from the temporary text file.
5. Type sip: into the Origination SIP URI field.
6. Paste the FQDN value into the temporary text file into the Origination SIP URI field.
7. You can ignore the other fields at this time. You can change their values when you have additional URIs.
8. Click Add.
   This closes the Add Origination URL modal.
9. If successful, a green banner displays that states Origination url added.
10. Toggle CNAM Lookup to On.
11. If all settings look correct, click Save in the bottom navigation bar. This preserves the Origination settings.
12. If successful, a green banner displays that states Trunk updated.

Each SIP requires at least one phone number. This number directs calls from the Public Switched Telephone Network (PSTN) to your trunk and acts as the caller ID for outbound calls.

1. If necessary, log in to your Twilio Console.

2. Click Numbers in the left side navigation.
   The Numbers page displays.

3. Click Add a number.

4. Choose from one of the following dropdown menu options:

   Add an Existing NumberBulk Add Existing NumberBuy a Number

   The Add a number modal displays.

   1. Check the box to the left of the desired number.
   2. Click Add Selected. This closes the Search Numbers modal.

5. All added numbers display in the Numbers page.

Ignore the Emergency calling button at this time. This procedure appears later in this guide.

1. If necessary, log in to the 3CX PBX console for your PBX.
2. Click Voice & Chat on the left navigation.
3. Click Add Trunk.
4. Type a human-readable description in the Name field.
5. Under Voip Provider, select your country (or Worldwide) from the Country dropdown menu.
6. Select Twilio from the Provider dropdown menu.
7. Copy the Termination SIP URI value from the temporary text file. This value should contain .pstn.*.twilio.com.
8. Paste this Twilio Termination SIP URI value into the Registrar/Server field.
9. Copy the Credential Name value from the temporary text file.
10. Paste the Credential Name value into the Authentication ID (SIP User ID) field.
11. Type or paste from the temporary text file the password for this credential name into the Authentication password field.
12. Type the phone number you selected when configuring the SIP trunk on Twilio.
13. Click Save at the top of this screen.
    The Add Outbound Rule page displays.

When calls route from the PBX to the Trunk, you may need to refine how the PBX passes call data. Think of this as how you dial different types of phone numbers. Twilio expects phone numbers written in the E.164 international format.

1. If necessary, log in to the 3CX PBX console for your PBX.

2. Click Outbound Rules on the left navigation. The Add Outbound Rule page displays.

3. Follow the 3CX documentation on Outbound rules.

   The Outbound rules page lets you transform numbers from one format to the E.164 format. This requires the following changes to phone numbers:

   • Remove any national or international dialing prefixes used in your location
   • Prepend + then the recipient's country code

4. Click Save at the top of this screen.
   The Outbound Rule page displays.
   To create additional rules, click + Add.

The following tables provide examples of dialing rules for certain countries. To create your outgoing rules in the 3CX PBX, use this data.

The Route # fields should be set to the value you gave your Twilio trunk in the Name field.

Verify that you can make calls using the phone number, PBX, and trunk you configured.

1. If necessary, log in to the 3CX PBX console for your PBX.
2. Click the Phone icon at the top right of the 3CX PBX console.
3. Type a number into the keypad.
4. Click Phone icon.
   • The call succeeds if the phone rings more than once.
   • The call fails if you hear a system message.

1. If necessary, log in to the 3CX PBX console for your PBX.
2. Open the event log for your 3CX PBX: https://<YOUR-PBX-HOST>/#/office/event-log.
3. Click the Event ID for the last warning or error. This opens the Event Log error page.
4. Look up the error and consider the action outlined in the Tips column.

The following table lists issues that may arise when an outgoing call fails.

• Review the Twilio Console error logs.
• Troubleshoot Twilio SIP trunking using these procedures.

To test inbound calling, you have two options:

1. If necessary, log in to your Twilio Console.
2. Go to the Elastic SIP Trunks page.
3. Click the link for your desired trunk.
4. Click Origination on the left navigation rail.
   The Origination page displays.
5. Scroll to the Make a Test Call section.
6. From the dropdown menu, choose the Twilio phone number you assigned to the trunk.
7. Click Make a test call.
   This calls your PBX and verifies that voice traffic gets through any firewalls.

If you inbound test call fails, review the following settings.

• Verify that the 3CX SIP address. It must include the leading sip:.
• Verify that you registered the called phone number on the PBX.
  If not, the 3CX Event Log shows an entry with Unidentified Incoming Call.

Extensions in your PBX can dial out to other callers. They can't receive calls without a Direct Inward Dialing (DID) phone number. To assign DID phone numbers to extensions, perform the following tasks.

To assign extensions, you need to create phone numbers in the Twilio Console, then create DID numbers and users in your 3CX PBX console. Extensions get assigned to a user when you create the user.

1. If necessary, log in to the 3CX PBX console for your PBX.

2. Click Voice & Chat on the left navigation.

3. Click your Twilio trunk.

4. Click the DID Numbers tab.

5. Add DID numbers in one of two ways:

   Add one numberImport multiple

   1. Click Add.
   2. Type the phone number in the E.164 format.
   3. To accept this number, click the Disk icon.
      If reject this number, click the x icon.
      The new number should display under the DID Numbers tab.

   To create a contiguous block of numbers, open a support ticket. Ask if a suitable range exists in your desired area code.

6. To preserve the added DID numbers, click Save in the top navigation bar.
   The Voice & Chat page displays with the first three numbers listed in the Information column of your Twilio trunk.

1. Click Users on the left navigation.

2. Follow the 3CX PBX documentation to create users and their extensions.
   You can't assign DID numbers to non-existent extensions.
   During this process, include the following steps:

   1. Set the Assigned DID number(s) field to one of the Twilio phone numbers that you created.
   2. Set the Outbound Caller ID to their assigned DID number.

3. Click Save at the top of this screen.
   The Users page displays.

If you didn't create enough DID phone numbers, create more in the Twilio Console.

To allow emergency calls, you need to add and assign a physical address to each direct inward dial phone number. This directs first responders where they're needed when you need them.

1. If necessary, log in to your Twilio Console.

2. Go to the Elastic SIP Trunks page.

3. Click the link for your desired trunk.

4. Click Numbers on the left navigation rail.
   The Numbers page displays.

5. To assign an emergency address, click the checkbox to the left of each phone number.

6. With phone numbers checked, click Configure Emergency Address then Add Emergency Address.

7. Review the Twilio Inc. Emergency Services Addendum on Accept Terms of Service modal.

8. Click Accept.
   The Add Emergency Address displays.

9. Click + Create New Address.
   If you have an existing address, click Select from my Addresses.

   Select from my addressesCreate new address

   From the Select an Address modal, choose a physical address.

   1. Click Select to the right of the desired address.
      The Confirm Suggested Address screen displays.
   2. Click Use Suggested Address.
      This closes the modal.
   3. If this address appears correct, click Add Emergency Address.
      If you need to change this address, click Change Address.

   The Numbers page displays. The selected address should display Pending registration in the Emergency Address Status. Activate emergency calling takes a few minutes. After 10 to 15 minutes, refresh this page until Registered displays next to the desired phone number.

   To learn more, consult the Emergency Calling guide.

Emergency calling requires setting up the emergency numbers in the 3CX PBX. Your PBX needs to call the correct service in the correct locality. The following steps outline how to add emergency numbers.

1. If necessary, log in to your 3CX PBX instance console.
2. Go to System > Emergency.
   The Emergency Numbers page displays.
3. Click + Add.
   The Add emergency number page displays.
4. Type a human-readable description of this emergency number into the Rule Name field.
5. Type an emergency number into the Number field.
6. Leave the Call from extension(s) field blank.
7. Check that Route 1 in the Make outbounds calls on section includes your Twilio trunk.
8. Click Save at the top of this screen.
   The Emergency Numbers page displays.

Every extension that might call emergency services must have a linked DID number. This DID number must have:

• Activated emergency calling
• Set an outbound Caller ID value
• Registered a physical address to that Caller ID and DID number

If you succeeded in configuring emergency calling, the expected workflow follows these steps:

1. The public safety dispatcher calls back.
2. The dispatcher reaches the person who made the emergency call.
   If that doesn't happen, the dispatcher reaches the receptionist or security desk.

If you need to notify security staff in emergencies, 3CX includes notification settings.

US or Canada developers can test their emergency service configuration.

1. Dial 933.
   If you configured your emergency numbers, the call routes to the emergency test service.
2. The test service reads back the registered physical address.
   This should confirm that you set up emergency calling.