Requirements for VoIP Providers

Introduction

A SIP Trunk provider may be added to the 3CX Phone System by meeting the following technical requirements. These requirements can be divided into 2 categories, mandatory and optional:

Mandatory

1. Registration-based trunks
2. rInstance parameter support
3. Allowed IP address list
4. DTMF support for RFC2833
5. Proxy audio
6. Error codes

Optional

1. E164 number formatting
2. TLS / SRTP
3. T38 Support
4. SMS / MMS Support

We explain each of these technical requirements below.

Mandatory

Registration-based

3CX will only support registration based trunks as those offer greater versatility and features when combined with a 3CX phone system. Registration based trunks are also required for implementing rinstance. More on rinstance later.

When a trunk is added, the 3CX Phone System will initiate a registration request without including authentication details. If then challenged by a “407 proxy authentication” or a “401 Unauthorized” message, the 3CX Phone System will respond with another registration message that includes the appropriate authentication header with all necessary information for registration.

Note: 3-way authentication is also supported.

Initial Registration Example

Provider Challenge Example

Registration with Authorization Example

rInstance Parameter

How is it used by 3CX?

The 3CX Phone System uses this parameter for Call Source Identification to match an incoming call with a SIP trunk. This is only possible for registration-based trunks since there is no registration for IP-based trunks. 3CX Phone System performs Call Source identification as described here. In short, when the 3CX Phone System receives a call, it first tries to match the rInstance value to a trunk. This ensures that calls will always be routed to the correct destination since each rInstance value is unique per SIP Trunk.

This allows for multiple SIP Trunks of the same provider to exist on the same 3CX installation even if all other parameters are the same between the trunks. A 3CX Phone System assumes the role of a UAC (User Agent Client) to register with a UAS (User Agent Server, usually a SIP Trunk provider). While doing so, 3CX includes a parameter called rInstance in the registration message sent to the UAS.

The parameter

This parameter is included in the “Contact” header and is unique for each SIP Trunk the 3CX Phone System is registered to. The parameter must remain unchanged as long as the registration is active. If the registration between the 2 User Agents expires or is terminated from either side, the next time the 3CX Phone System will try to register it will generate a new rInstance value.

Registration Example:

The 3CX Phone System expects to see the same rInstance parameter and value in the 200 OK returned for the registration attempt. This parameter must be included in the “Contact” header.

Registration Reply Example:

The 3CX Phone System expects to see the same rInstance parameter and value during inbound calls so it can match the Invite to the correct SIP trunk. The parameter must be included in the “Request-Line ” header.

If the trunk has multiple DID (Direct Inward Dialing) numbers then the rInstance value must be present regardless of the DID number called.

Invite Example:

Allowed IP address list

To avoid issues with customers not being able to register their Trunks, the Provider will need to make sure of the following:

1. If the Provider needs to add the IPs of 3CX customers in their list of allowed IPs, then this needs to be clearly stated.
2. The Provider should also be able to receive from 3CX a list of IP addresses to add in their allowed IP list at short notice.
3. If possible the Provider should be able to whitelist a system using its FQDN. The TTL of the FQDN must be followed to ensure that any IP changes are updated promptly.
4. The Provider should also specify an email address that will be used by them to receive email updates from 3CX with regards to IPs that they will need to add to their allowed list.
5. If no whitelisting of IP addresses is required by the Provider (no blocking of IPs) then this should be stated as well.

RFC2833 Support

RFC2833 should be the default DTMF method used for delivering and accepting DTMF tones.

This must be indicated by the support of the “telephone-event” media attribute in the SDP of any call. The sample rate can vary depending on the codec used.

Proxy of audio

The Provider must be able to proxy the audio between 2 endpoints and not pass through the SDP to the other end. This prevents issues with audio not being delivered because of some firewalls not supporting hairpin traffic. This also enables transcoding in case the 2 endpoints don’t support common codecs.

Error Codes

If a 3CX Phone System fails to register a trunk due to incorrect credentials the error code sent back to the 3CX Phone System must be either “403 Forbidden”, “404 Not Found” or “603 Declined”. “401 Unauthorized” and “407 Proxy Authentication Required” are also allowed but not preferred. This allows the 3CX Phone System to understand that the credentials sent were wrong and stop the registration attempts until a change is made to the credentials or the user manually decides to retry.

Optional

E164 number format

E164 support is optional for providers unless the same Provider supports SMS / MMS. Then it is mandatory for Providers to support it.

Inbound calls:

Calls arriving at the 3CX Phone System must be in full globalized E164 number format (leading with‘+’). The 3CX Phone System can be set up to read the number format from a number of different SIP headers. The most common however are the “To: UserPart” and the “Request-Line URI: UserPart”.

Outbound calls:

Customers should be able to dial out using E164 number format (with ‘+’) as well. They should also preferably be able to present their caller ID in E164 number format (with ‘+’) too. So the “From” and “To” numbers should be accepted in E164.

TLS / SRTP Support

TLS and SRTP support is nice to have and demand from customers keeps increasing. It is not mandatory to have and it is currently not supported in 3CX StartUP but we are considering adding support for it in the future.

All technical requirements for TLS / SRTP in 3CX can be found here.

T38 Support

Fax support is optional but nice to have as some customers and markets still depend on it.

3CX supports T38 and G711 fax, however T38 is the preferred method.

All technical requirements for Fax can be found here.

SMS/MMS API

Requirements

• E164 support
• Good documentation of the interface

• HTTPs REST API for outbound message delivery
• HTTPs Webhooks for inbound message delivery and status reports

• Ability to generate an API Key and set Webhooks via the Provider Customer Portal
• SIP Trunking (voice) on the same number

Authorization

Providers should provide an API KEY (random, long enough string, unique per user account) to their users. 3CX GenericVoipProvider should be provisioned with this API KEY, so the 3CX Phone System can use it for authorization to the Provider. 3CX Phone System will pass the key in the Authorization header as follows:

This is for the Provider to be able to authenticate and authorize users’ requests that come from 3CX Phone System.

Send SMS/MMS request

The following is an example of sending an SMS from 3CX Phone System to the Provider's phone number.

All fields are required. Fields ‘to’, ‘from’ must be in E.164 format.

The following is an example of sending multiple MMS from 3CX Phone System to the Provider's phone number.

Webhook notifications

The Provider should send incoming SMS/MMS messages and delivery receipts to 3CX Phone System in order to configure webhook using POST method.

The following is an example of sending a new incoming SMS message:

Providers may extend this message with other data if needed. However, these are the required fields to be specified:

• data.id
• data.event_type
• data.payload.from.phone_number
• data.payload.to.phone_number
• data.payload.text
• data.payload.received_at

Field ‘data.id’ is the Provider's message ID (internal). Fields ‘phone_number’, ‘from’ and ‘to’ are phone numbers in E.164 format.

The following is an example of sending a new incoming MMS message:

The following is an example of an SMS delivery report which is sent by 3CX Phone System to the Provider when the SMS message is delivered successfully:

The required fields to specify are:

• data.event_type (value should be ‘message.finalized’ or ‘message.sent’
• data.payload.id (id of delivered message)
• data.payload.to.status (could be ‘delivered’ or ‘sent’)

If the delivery of the message has failed then the ‘data.payload.to.status’ will change to “sending_failed” or “delivery_failed”.

How to Configure your Trunk

1. Go to “Voice & Chat”.
2. Select “Country > Generic” and choose between SIP Trunk and VoIP Provider.
3. Configure your SIP Trunk Provider details.
4. Go to the “SMS” tab and check the “Enable SMS”.
5. Copy and paste the ‘Webhook’ to your provider’s portal.
6. Add the “API Key” and “Provider URL” which can be found in your provider’s portal.

See also

• Application form to become a certified SIP Trunk provider.
• List of supported SIP Trunk providers.
• DNS Resolution - Explains how 3CX resolves FQDN to Registrar and SIP Server.
• Registration / Authentication - How 3CX registers/authenticates to a VoIP Provider.
• 3CX Trunk TLS and SRTP Functionality - Explains the TLS and SRTP functionality.
• SIP Trunk Failover - How 3CX handles multiple SIP Servers.

Last Updated

This document was last updated on 3 March 2023

https://www.3cx.com/docs/supported-sip-trunk-requirements/