The following document is intended for VoIP Provider Engineers. It highlights relevant information on how to generate templates for the 3CX Phone System. The templates contain the most common set of parameters as observed during validation and verification testing.
The majority of providers today, when interpreting signals, use a standard set of parameters. If a new provider launches service, the Generic Templates offer a feasible set of configuration options that serve as a cornerstone to a customized template.
As a prerequisite, one must differentiate between “Registration Based VoIP Providers” and “IP Based / SIP Trunk providers”.
- Registration Based VoIP providers – require the PBX to register with the provider using an authentication ID and password. Most of the VoIP providers pre-defined in 3CX Phone System are registration based.
- IP Based / SIP Trunk VoIP providers – IP Based VoIP Providers (also known as SIP Trunks) do not require the PBX to register with the provider. The IP address of the PBX needs to be configured with the provider, so that it knows where calls to your number should be routed.
For additional information refer this link: https://www.3cx.com/blog/voip-howto/nat-stun-network-configuration/
Accessing the Templates
Once the 3CX System has been installed, you will then have access to the templates. By default, all VoIP provider templates, including the generic templates are stored in a folder named ‘Provider’. The path to the templates is highlighted below.
C:\ ProgramData \ 3CX \ Data \ Http \ Templates \ provider
Once in the folder, you will notice two Generic Templates
Depending on the type of provider you are, you may make your selection and proceed with your configuration.
*Note: Once the template is complete, it MUST be stored in the same location so it can be accessed by the 3CX system.
Creating a Custom VoIP Provider Template
All values that are not mentioned should remain untouched from the provided default generic template. Make a copy of the base provider template and rename it to your company’s name with .pv.xml extension (e.g. myprovider.pv.xml).
The Header of the xml file contains informations about the provider name, country of operation, provider logo and the web page link to the provider.
This value is defined by the Vendor. Only numeric values define the version tags. It should start with version 1 and should be incremented on each update the provider is making in regards to the template.
The provider’s url can simply be inserting between the tags to refer to its own web page.
It is important that the company logo is properly formatted. The logo size must be 16×16 in PNG format. The logo’s file name should be the same as the providers company/template name (e.g template file name is myprovider.pv.xml log and must be myprovider.png)
Hostnames and Ports
This section defines where the PBX should registers to and make calls through.
Must reflect an IP Address or FQDN of the voip provider’s SIP server(s). If no ProxyHost/Port will be defined and the field will be provided with an FQDN, the 3CX Phone System will try to resolve the entered FQDN first for SRV records (_sip._udp.myprovider.com). If SRV responds with answers then A records will be used in the defined weight and priority. If the SRV look up will fail, the A record will be used to connect.
Usually this reflects the VoIP provider’s SIP server port on port 5060. If the SIP servers of the provider do not run on the default sip port, it needs to be altered.
Note if the ProxyHost will be set, the 3CX Phone System will only use the A record for the given ProxyHost and disables the SRV lookup feature. Data for the RiegistrarHost domain will be relayed via the given ProxyServer which may or may not be the same as the RegistrarHost itself.
Usually this reflects the voip providers proxy server port on port 5060. If the proxy servers of the provider do not run on the default sip port it needs to be altered there.
This part of the xml sets defines how the phone system should connect to the provider and if authentication data has been used to authorize connection with the VoIP provider.
This variable forces the PBX to re-register after the specified time given in seconds. Note that the smallest allowed value is “60”. The PBX will however listen to the expiration time given by the remote SIP Server. The default value is 600. This value is not used when the provider type is IP based (trunk) but must be set.
This value defines if and if applicable how to connect/register with the VoIP provider. If the provider is IP based (trunk) then it does not require authentication since the security/authentication layer is made over the IP address of the PBX which needs to be set at the provider level. In this case the setting is to be set to 1 = does not require authentication
Commonly the 3CX Phone System must register to the provider with a username and password provided by the provider. In order to send registrations for inbound and outbound calls the value needs to be set to 4 = Authentication. This value is required for inbound and outbound calls before the call can be made/received.
Alternative values are:
2 = Only inbound calls should be challenged by the 3CX Phone System
3 = Only outbound calls will be challenged by the provider
For Trunk Provider only (IP based)
Use the following configuration lines from this section to indicate that no user name and password needs to be entered, since they are not provided to the user.
<field name=”LineAuthenticationPassword” status=”readonly”></field>
<field name=”3wayauthenticationid” status=”readonly”></field>
These settings should be used for all providers as the 3CX Phone System is the proxy host for all internal entities using this provider.
This options defines that all media streams (RTP) will be handled by the 3CX Phone System and not be sent directly to the IP phone behind the host. The available values are Yes=1; and No=0. It is strongly advised to leave this value set to 1.
This value specifies whether the provider supports Re-invites. Toggling this value may assist in cases where hold, resume and transfer of calls is unreliable. The available values are Yes=1; and No=0. It is strongly advice to leave this value set to 0
Specifies whether the VoIP provider supports replaces. Toggling this value may assist in cases where transfer of calls is unreliable. The available values are Yes=1; and No=0. It is strongly advice to leave this value set to 0
This variable allows you to disable the Video description in the outbound SDP information. If the SDP/RTP server have capabilities to handle video, this option can set to 0. The available values are Yes=1; and No=0.
In the section “codecs” the provider can predefine up to 3 codecs which should be activated in the SDP offer where the codec order is from top to bottom. Less than three codecs can be set by just defining 1 or 2 codec lines.
Available common options are: pcmu pcma gsm g729 g722
When the PBX receives an INVITE it will check its source and will be mapped it to the right Voip Provider Account inside the 3CX Phone System. This procedure is called “Source Identification”. The Source Identification can be handled in many ways.
The best option for the end user is to keep transparent, in other words the end user does not need to alter this. In order to achieve this, the invite SHOULD contain a value which identifies the trunk inside the 3CX Phone System and therefore MUST feature a unique value. For registration based providers the best option is to deliver the AuthenticationID in any standard SIP filed. Therefore uncomment the line of the Match Strategy and set it to 1 followed by why the mapping in which SIP fields (e.g in Contact User Part) the used AuthID will be delivered in an invite. In this case end users can have multiple accounts with the same provider and the Source ID is pre-definable.
<field name=”Source” parameter=”ContactUser” custom=””>$AuthID</field>
If the AuthID can not be delivered to the end user, a static value for the provider needs to be chosen. Like the FQDN or IP address where the Invite is originated – which matches the configuration line “RegistrarHost”. In such case the user can only use one trunk from the provider since the data would be duplicated in each trunk and the sourceid no longer unique. A sample configuration would be:
<field name=”Source” parameter=”FromHostPart” custom=””>$GWHostPort</field>
Where by GWHostPort is expected to be send from the provider in the same format as given in the Registrar and the Port.
The Inbound/Outbound Parameters section defines the SIP filed mapping and how the 3CX Phone System should compose an outbound Invite along with inbound Invite requirements from the provider to the Phone System.
The parameter defines the RFC SIP filed where a value is expected in or where a value needs to be placed at, while creating an invite. Note that all possible SIP fields are exposed. Do not add any X or P Headers to the list as it will not be recognized by the 3CX Phone System.
Valid Sip fields are written in a standard SIP format:
Note only Outbound Configured fields are needed to compose a valid SIP Invite (outbound) and not all fields, thats if not required by the SIP Server of the VoIP provider level. (e.g do not set RPID if it is not needed).
Note: At Inbound level, the key fields for the 3CX Phone System is to identify where the Calling Party number and the Called Party number is located plus one identifier of the Providers trunk. This can be as short as the lines displayed below, but may be extended to as many identifiers required.
<field name=”ParameterIn” custom=”” parameter=”ToUserPart”>$CalledNum</field>
<field name=”ParameterIn” custom=”” parameter=”FromUserPart”>$CallerNum</field>
<field name=”ParameterIn” custom=”” parameter=”RequestLineURIHost”>$DevHostPort</field>
The variables are the mapping (located inside the tag “> <”) to the SIP field from the 3CX Phone System SIP engine. For inbound, it is important that the 3CX Phone System variable is only used ONCE and is not allowed to occur multiple times in different sip fields. At the outbound parameters, the values from the 3CX Phone System may occur multiple times in order to formulate a SIP Invite to the provider in the expected way.
Important Note: Every VoIP Provider supporting the option “Clip No Screening” where a 3rd party number can be sent via its own trunks should use the value “Originator Caller ID” rather than “Outbound Caller ID” in the outbound parameters. With such method, forwarded calls to a mobile will display the number of the caller and not the number of the extension forwarding the call to the mobile.
Variables and their Origin
Keep in mind that not all variables can be used/set in any mapping to a SIP filed, if it defies the logic of the content. Check the 3CX Phone System Management Console to validate possible mapping combination’s options.
|§GWHostPort||Provider’s gateway and port set in MNG Console|
|$OutHostPort||Prvider’s proxy gateway and port set in MNG Console|
|§DevHostPort||Provider’s source address / port of message|
|$ContactURI||Content of Contact field|
|$CalledName||Name that has been dialed (default: To → displayed name)|
|$CalledNum||Number that has been dialed (default : To → User)|
|$CallerName||Caller’s name (default : From → display name)|
|$CallerNum||Caller’s number (default :From → User)|
|$LineNumber||External number of Line|
|$LineID||Internal number of line|
|$OrginatorCallerID||Orginal caller number will be sent|
|$OutboundLineId||Outbound line Caller ID taken from Outbound caller ID settings in MNG Console|
|$OutboundCallerID||Outbound caller ID taken from Extension Settings in MNGConsole|
|$CallerDispName||Display name of caller as it is in From Header – provided by the phone settings|
If the 3CX Phone System does not represent a value as variable which is needed to be set in the inbound/outbound or source identification fields, then it can be set statically as a custom value. The example provided bleow indicates that the value mysource.com has been set in the source identification for the To:HostPart as custom field to match the given information.
<field name=”Source” parameter=”ToHostPart” custom=”mysource.com”>$CustomField</field>