# Configure a 3CX PBX to use Twilio SIP Trunking ## Introduction 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. ## Transfer values between systems > \[!NOTE] > > To store values that you need between your 3CX PBX and your Twilio trunk, create a text file in your preferred text editor. [temporary text file]: #transfer-values-between-systems ## Create a 3CX PBX instance 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](https://www.3cx.com/docs/manual/install/) 1. When prompted for **Which 3CX?**, Choose [**3CX Hosted**](https://www.3cx.com/docs/manual/install/#h.u6xz8qsr3mm7). 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](#configure-the-sip-trunk-connection-to-the-3cx-pbx) 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](#configure-inbound-traffic-settings). * **IPv4**. You need this value when you [create an access control list](#secure-your-sip-trunk). 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. ## Create and secure a Twilio SIP trunk ### Create the SIP trunk in the Twilio Console 1. Log in to your [Twilio Console][twilio-console]. 2. Click [**Explore products**](https://console.twilio.com/develop/explore) 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.** [twilio-console]: https://console.twilio.com [Elastic SIP Trunking]: https://console.twilio.com/us1/develop/sip-trunking?frameUrl=%2Fconsole%2Fsip-trunking%2Fdashboard%3Fx-target-region%3Dus1 ### Configure outbound traffic settings 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][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. > \[!NOTE] > > 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 `.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. ### Secure your SIP trunk To secure your SIP trunk, configure an *access control list* (ACL) and credentials. 1. If necessary, log in to your [Twilio Console][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](#create-a-3cx-pbx-instance) 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. ### Configure inbound traffic settings 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][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.` ### Add one or more phone numbers 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][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 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. ## Bulk Add Existing Number The **Bulk Add Numbers** modal displays. 1. Type a list of Twilio phone numbers into the **Phone numbers** field, one on each line. 2. Click **Process Numbers**. This closes the **Search Numbers** modal. ## Buy a Number The **Search Numbers** modal displays. 1. Click **Buy** to the right of any desired number. 2. Click **Close**.\ 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](#configure-emergency-service-calls). ## Configure the SIP trunk connection to the 3CX PBX ### Add the SIP trunk details #### Forgot the values from Twilio Console? If you didn't create the [temporary text file][], retrieve the needed values through these steps. 1. Open your preferred text editor. 2. Create a new text file. 3. If necessary, log in to your [Twilio Console][twilio-console]. 4. From the [Elastic SIP Trunking > Manage > Trunks page][elastic-sip-trunks], copy the **Termination SIP URI** value. 5. Paste this value into your temporary text file. 6. From the [Elastic SIP Trunking > Manage > Credentials list page][elastic-sip-creds], click on the **Friendly Name** for your credential list for your Trunk. 7. Copy the value in the **Credential Name** field. 8. Paste this value into your temporary text file. 9. Copy the value for the **Authentication password** you created when you [created the 3CX PBX instance](#create-a-3cx-pbx-instance). 10. Paste this value into your temporary text file. 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][phone-number] when configuring the SIP trunk on Twilio. 13) Click **Save** at the top of this screen.\ The **Add Outbound Rule** page displays. [phone-number]: #add-one-or-more-phone-numbers [elastic-sip-trunks]: https://console.twilio.com/us1/develop/sip-trunking/manage/trunks?frameUrl=%2Fconsole%2Fsip-trunking%2Ftrunks%3Fx-target-region%3Dus1 [elastic-sip-ip-acl]: https://console.twilio.com/us1/develop/sip-trunking/manage/ip-acls?frameUrl=%2Fconsole%2Fsip-trunking%2Fauthentication%2Fip-acls%3Fx-target-region%3Dus1 [elastic-sip-creds]: https://console.twilio.com/us1/develop/sip-trunking/manage/cls?frameUrl=%2Fconsole%2Fsip-trunking%2Fauthentication%2Fcls%3Fx-target-region%3Dus1 ### Configure dialing routes 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. [E.164]: https://www.twilio.com/docs/glossary/what-e164 #### Add outgoing rules to the PBX 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](https://www.3cx.com/docs/manual/outbound-call-routing/). 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**. #### Example rules for a 3CX PBX 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](#add-the-sip-trunk-details). #### Outgoing rule for all countries | Rule Name | Calls to numbers starting with prefix | Calls to numbers with a length of | Strip digits | Prepend | | --------- | ------------------------------------- | --------------------------------- | ------------ | ------- | | E.164 | `+` | | | | #### Outgoing rules for the US and Canada | Rule Name | Calls to numbers starting with prefix | Calls to numbers with a length of | Strip digits | Prepend | | ------------- | ------------------------------------- | --------------------------------- | ------------ | ------- | | International | `011` | | `3` | `+` | | NANP | | `10` | | `+1` | #### Outgoing rules for the United Kingdom | Rule Name | Calls to numbers starting with prefix | Calls to numbers with a length of | Strip digits | Prepend | | ---------------------- | ------------------------------------- | --------------------------------- | ------------ | ------- | | International | `00` | | `2` | `+` | | Standard Trunk Dialing | `0` | | `1` | `+44` | #### Outgoing rules for the Republic of Ireland | Rule Name | Calls to numbers starting with prefix | Calls to numbers with a length of | Strip digits | Prepend | | ---------------------- | ------------------------------------- | --------------------------------- | ------------ | ------- | | International | `00` | | `2` | `+` | | Standard Trunk Dialing | `0` | | `1` | `+353` | #### Outgoing rules for France | Rule Name | Calls to numbers starting with prefix | Calls to numbers with a length of | Strip digits | Prepend | | ---------------- | ------------------------------------- | --------------------------------- | ------------ | ------- | | International | `00` | | `2` | `+` | | National Dialing | `0` | `10` | `1` | `+33` | #### Outgoing rules for Australia | Rule Name | Calls to numbers starting with prefix | Calls to numbers with a length of | Strip digits | Prepend | | ------------------ | ------------------------------------- | --------------------------------- | ------------ | ------- | | International | `0011` | | `4` | `+` | | National Dialing | `0` | `10` | `1` | `+61` | | Freecall | `1800` | `10` | | `+61` | | Freecall (short) | `180` | `7` | | `+61` | | Local Rate | `1300` | `10` | | `+61` | | Local Rate (short) | `13` | `6` | | `+61` | ## Test calling from the PBX ### Make an outgoing test call 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. ### Troubleshooting failed outgoing calls 1. If necessary, log in to the 3CX PBX console for your PBX. 2. Open the event log for your 3CX PBX: `https:///#/office/event-log`. 3. Click the **Event ID** for the last warning or error. This opens the [Event Log error page](https://www.3cx.com/docs/event-log/). 4. Look up the error and consider the action outlined in the **Tips** column. #### Common issues The following table lists issues that may arise when an outgoing call fails. | Issue | Potential remedy | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | Someone entered the wrong FQDN for your Twilio trunk Termination SIP. | This FQDN maps to your Twilio trunk. [Update the SIP FQDN][trunk-details] in your 3CX PBX instance. | | Credentials in your 3CX PBX don't match those set in the Twilio Console. | [Update the credentials][trunk-details] in your 3CX PBX instance. | | [Twilio IP ACL][ip-acl] doesn't contain the IP address for your 3CX PBX. | [Add 3CX PBX IPv4 address to the IP ACL][secure-trunk] for your Twilio trunk. | | Carrier blocked call due to your Twilio calling number (or caller ID). | Register your trunk phone number with a registry like [Free Caller Registry][]. | [ip-acl]: https://console.twilio.com/us1/develop/sip-trunking/manage/ip-acls?frameUrl=%2Fconsole%2Fsip-trunking%2Fauthentication%2Fip-acls%3Fx-target-region%3Dus1 [Free Caller Registry]: https://www.freecallerregistry.com/ [trunk-details]: #add-the-sip-trunk-details [secure-trunk]: #secure-your-sip-trunk #### Other resources * Review the [Twilio Console error logs](https://console.twilio.com/us1/monitor/logs/debugger/errors). * Troubleshoot Twilio SIP trunking using [these procedures](https://help.twilio.com/articles/360025446533-Troubleshooting-Twilio-Elastic-SIP-Trunking-and-SIP-Domain-Calls). ## Test calling into the PBX ### Make an incoming test call To test inbound calling, you have two options: 1. If necessary, log in to your [Twilio Console][twilio-console]. 2. Go to the [Elastic SIP Trunks page][twilio-sip-trunk]. 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. [twilio-sip-trunk]: https://console.twilio.com/us1/develop/sip-trunking/manage/trunks?frameUrl=%2Fconsole%2Fsip-trunking%2Ftrunks%3Fx-target-region%3Dus1 ### Troubleshooting failed incoming calls 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 and direct inward dialing (DID) 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. ### Link Twilio phone numbers to DID numbers in the 3CX PBX console 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 number 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. ## Import multiple 1. Click **Import**. 2. Select a text file (`.txt`) from your local system.\ This text file has one column: the DID number. It can't have a header row. This text file would resemble the following: ```txt +17777777771 +14477777772 +135377777773 ``` The new numbers should display under the **DID Numbers** tab. To create a contiguous block of numbers, [open a support ticket][twilio-support]. 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. [twilio-support]: https://help.twilio.com ### Configure users and extensions in the 3CX PBX console 1. Click **Users** on the left navigation. 2. Follow the 3CX PBX documentation to [create users and their extensions][3cx-users].\ 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][add-numbers] in the Twilio Console. [add-numbers]: #add-one-or-more-phone-numbers [3cx-users]: https://www.3cx.com/docs/manual/create-extensions/#h.7q90x4ircmop ## Configure emergency service calls > \[!NOTE] > > Before attempting this procedure, check if your territory supports [emergency calling](/docs/sip-trunking/emergency-calling). 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. ### Configure the Twilio SIP trunk for emergency calling 1. If necessary, log in to your [Twilio Console][twilio-console]. 2. Go to the [Elastic SIP Trunks page][twilio-sip-trunk]. 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 addresses 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**. ## Create new address From the **Add Emergency Address** modal, add a new physical address. 1. Enter the address details in the following fields. This form requires values for all fields. | Field | Needed Value | | ------------------ | ------------------------------------------------------------------------------------------------ | | **Friendly name** | Human-readable description associated with this physical address | | **Customer name** | Name of your organization associated with this physical address. | | **Address line 1** | First line of the mailing address associated with this physical address. | | **Address line 2** | Second line of the mailing address associated with this physical address. | | **City** | Locality that contains the mailing address associated with this physical address. | | **State** | Division of the country that contains the mailing address associated with this physical address. | | **Postal Code** | Code used to route post to the mailing address associated with this physical address. | | **Country** | Country that contains the mailing address associated with this physical address. | 2. Click the **I agree to the Terms of Service** checkbox. 3. Click **Create Address**.\ The **Confirm Suggested Address** screen displays. 4. Click **Use Suggested Address**. The **Confirm Suggested Address** screen displays. 5. 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](/docs/sip-trunking/emergency-calling#enable-emergencycalling). ### Turn on emergency calling for the 3CX PBX 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. > \[!NOTE] > > This works like configuring the dial plan. > > To configure emergency calling for the US and Canada, apply these settings. > > | Rule Name | Number | > | -------------- | ------ | > | Emergency Test | `933` | > | Emergency | `911` | 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][link-did-to-address] to that Caller ID and DID number [link-did-to-address]: #configure-the-twilio-sip-trunk-for-emergency-calling 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. ### Turn on security notifications If you need to notify security staff in emergencies, 3CX includes [notification settings](https://www.3cx.com/docs/manual/emergency-numbers/h.urjfz89r0j8u). ### Test your emergency number response US or Canada developers can test their emergency service configuration. 1. Dial `933`.\ If you [configured your emergency numbers](#turn-on-emergency-calling-for-the-3cx-pbx), 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.