Creating a VoIP Provider Template in 3CX Phone System
- Tutorial
In this article, intended for engineers of VoIP operators, we will talk about how to create a VoIP operator template for 3CX Phone System. The template contains basic connection parameters, greatly simplifying the connection of the operator line to the system.
Most VoIP operators today use a more or less standard set of parameters, which is described in the Generic universal VoIP provider template. We will take the Generic template as the basis for creating an individual custom template. First of all, we explain the difference between the two types of VoIP operators used in 3CX:
VoIP Provider - A VoIP operator that uses authorization by username and password. Most VoIP provider patterns in 3CX are designed for this type of connection.
SIP Trunk - VoIP operator that uses authorization for the public IP address of the 3CX server. The public IP address of the server must be indicated with the operator as the address to which the operator routes calls, and from which he expects calls.
After installing the system, the VoIP operator template files are located in the c: \ ProgramData \ 3CX \ Data \ Http \ Templates \ provider \ folder . Universal templates are called:
GenericVoIPProvider.pv.xml - VoIP operator with authorization by username and password
GenericSIPTrunk.pv.xml - VoIP operator with authorization by IP address (SIP Trunk)
Choose a template depending on the type of authorization that you support!
First of all, make a copy of the universal template and name the file by the name of your operator (for example, myprovider.pv.xml ).
The file contains the following sections:
The header of the XML file for the template indicates the name of the VoIP operator, country, the name of the logo icon file and the website.
This parameter is determined by the template provider (usually a VoIP operator) and can only contain a number. Starts with 1 and increases each time the template is updated. An update may be required when a new version of 3CX is released or when changing operator settings.
Link to the operator’s website, which, for example, may contain tariffs or other important information.
It is important to follow the simple rules for creating a provider logo:
The logo must be in PNG format 16 × 16
The name of the image file must match the name of the provider file (without extension), i.e. myprovider.pv.xml> myprovider.png
This section shows the addresses and ports of the SIP servers of the VoIP operator to which the 3CX Phone System will connect.
The IP address or FQDN of the operator’s VoIP server is indicated here. If the ProxyHost / Port parameter is not specified, and RegistrarHost is specified as FQDN, 3CX will try to determine the IP address of the SIP server of the VoIP operator via the SRV record (_sip._udp.myprovider.com) DNS server:
If a response with SRV records is received, 3CX will use the servers with the specified priority.
If SRV records do not exist, 3CX will use a DNS server record.
Usually, the SIP port of the operator VoIP server 5060 is indicated here. If the operator server runs on a non-standard port, specify the port number in the template.
If the ProxyHost parameter is specified, 3CX Phone System does not search for SRV records, but uses A ProxyHost record. The registration request from 3CX Phone System will be sent to RegistrarHost through the proxy server ProxyHost. Often SIP proxy server and SIP registration server are combined in one server
Usually, the SIP port of the proxy operator VoIP server 5060 is indicated here. If the operator proxy server runs on a non-standard port, specify the port number in the template.
This part of the template indicates the type and authorization parameters of 3CX Phone System on the VoIP provider server.
This parameter indicates the period of confirmation of registration of 3CX Phone System on the provider's SIP server. The minimum value is 60 seconds. However, 3CX assumes the value transmitted by the operator’s VoIP server, i.e. VoIP carrier time always takes precedence. The default time in the 3CX template is 600 seconds. If the connection type is SIP Trunk, this parameter is not applied, but should still be present in the template.
This parameter indicates whether authentication of the connection to the VoIP operator is required. As mentioned, if the operator uses authorization by IP address, authentication is not required. A value of 1 means that authentication is not required . As a rule, however, authentication is required for both outgoing and incoming calls . In this case, the value should be 4 . Value 2 - authentication of incoming calls only. Value 3 - authentication of outgoing calls only.
Authentication parameters should not be entered by the user if 3CX Phone System uses authorization by IP address. Therefore, they should be given a read-only status.
<field name = ”LineAuthenticationPassword” status = ” readonly ”> </field>
<field name = ”3wayauthenticationid” status = ” readonly ”> </field>
These parameters must be defined for all VoIP operators, since 3CX Phone System also acts as a proxy server for its internal users.
This parameter determines whether the RTP media stream from the VoIP operator passes through the 3CX server or is sent directly to the final SIP device within the network (i.e. to the user's IP phone). It is strongly recommended that you leave the default value of 1 (pass through a 3CX server).
A parameter that determines whether the VoIP operator supports the SIP Re-invite method . Enabling or disabling this option helps if holding, retrieving, or transferring a call from the provider is unstable. The possible values are Yes = 1 and No = 0 , but it is recommended to leave the default value of 0 .
A parameter that determines whether the VoIP operator supports the SIP Replaces header . Enabling or disabling this option helps if holding, retrieving, or transferring a call from the provider is unstable. The possible values are Yes = 1 and No = 0 , but it is recommended to leave the default value of 0 .
This option allows you to remove the SDP description of the video in the media stream. If the VoIP server supports video transmission in the RTP media stream, you can explicitly disable this feature. Possible values are Yes = 1 and No = 0
This section defines voice codecs and their priority in the SDP stream description. The priority of codecs is determined by the location of the corresponding lines. You can define up to three codecs, but if less is needed, just delete the extra lines. Available options: pcmu, pcma, gsm, g729, g722 .
Upon receipt of an incoming INVITE request, 3CX attempts to identify the source of the call and match it with the corresponding VoIP trunk. The source identification procedure is carried out in various ways.
It is best to keep the source identification settings unchanged. Typically, an INVITE request includes a field that identifies the trunk for which this request is directed. This field must be unique. For VoIP providers using a username and password, the AuthenticationID parameter is usually used in one of the standard SIP fields. Therefore, it is recommended to uncomment the Match Strategy parameter and set it to 1 . Next, indicate in which SIP field (for example, Contact User Part), the VoIP operator sends AuthID.
If a VoIP operator passes AuthID to the Contact User Part field, you can create several VoIP connections to the same operator with different registration parameters (i.e. several independent VoIP lines), and 3CX will correctly determine the source of the call.
<field name = ”MatchStrategy”> 1 </field>
<field name = ”Source” parameter = ”ContactUser” custom = ””> $ AuthID </field>
If registration is not made on the VoIP operator (i.e., the connection is used type Trunk), you have to choose a static source identification parameter, for example, IP address or FQDN name of the host that sent the INVITE request. In the template, it corresponds to the RegistrarHost parameter described above .
In this case, the 3CX user can use only one VoIP connection to this operator, since the source identifier will be duplicated for several connections of the same type.
field name = ”MatchStrategy”> 1 </field>
<field name = ”Source” parameter = ”FromHostPart” custom = ””> $ GWHostPort </field>
Here the GWHostPort parameter must come from the VoIP provider in the same format as it is specified in the RegistrarHost and RegistrarPort parameters of the template.
The Incoming and Outgoing SIP Parameters section defines how the 3CX Phone System generates an outgoing INVITE request to a VoIP provider or processes an incoming INVITE request from a VoIP provider.
SIP parameters are RFC SIP fields in which a specific value is expected from the VoIP operator, or where 3CX should put the SIP value when creating an INVITE request. All available fields are included in the template , so do not add any X or P headers - 3CX will simply ignore them.
All SIP fields are presented in standard SIP format.
An Invite: RequestLineURIUser @ RequestLineURIHost
ContactUser @ ContactHost
ToDisplayName: ToUserPart @ ToHostPart
FromDisplayName: FromUserPart @ FromHostPart
RemotePartyIDCalledPartyDisplayName: RemotePartyIDCalledPartyUserPart @ RemotePartyIDCalledPartyHostPart
RemotePartyIDCallingPartyDisplayName: RemotePartyIDCallingPartyUserPart @ RemotePartyIDCallingPartyHostPart
P-AssertedIdentityDisplayName: P-AssertedIdentityUserPart @ P-AssertedIdentityHostPart
ProxyAuthID @ ProxyAuthRealm
Use only necessary and sufficient (for your VoIP operator) SIP fields to form the outgoing INVITE request. For example, do not specify an RPID field if it is not used by the operator.
In incoming INVITE requests, the most important fields for 3CX Phone System are the location of the CallerNum caller number and the VoIP trunk identifier of the operator. An example of such fields is given below, however, for various VoIP operators it can be expanded.
<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 XML variables of the VoIP operator template are enclosed in >> tags . Instead, the 3CX core substitutes the actual SIP values, or reads the necessary values from them. To parse incoming SIP messages, it is necessary that the variable be used only once, i.e. not found in several SIP fields. When generating outgoing SIP messages, the variable can be indicated in various parts of the INVITE request, in accordance with the requirements of the VoIP operator.
Important! Some VoIP operators support Clip No Screening.at which it is possible to transmit the original subscriber number, and not the VoIP line number of the operator. For example, an external subscriber called your extension 3CX, you weren’t there, and the call went to your mobile. In this case, you will see not the line number of the VoIP operator through which the call was issued, but the initial Caller ID of the caller. In this case, in the Outgoing parameters, use the Originator Caller ID , not the Outbound Caller ID .
Keep in mind that not all variables can be combined in SIP requests. We recommend checking the possibility of sharing these or those variables in the corresponding section of the VoIP operator settings in the 3CX interface.
If 3CX does not offer value substitution for a variable in the control interface (used in incoming and outgoing parameters, as well as for source identification), you can set the value manually (Custom value). In the example below, manually set mysource.com to identify the source. To: HostPart is a custom value set in accordance with the requirements of the VoIP operator.
<field name = ”Source” parameter = ”ToHostPart” custom = ”mysource.com”> $ CustomField </field>
Obviously, the information presented will be useful not only to the engineers of the operator organizing the connection of 3CX Phone System systems, but also to 3CX administrators, since it helps to understand the purpose of the various options in the configuration interface of the new external connection.
After editing the operator file, place the xml file of the template and png logo file in the same directory in which the rest of the templates are stored. You can also put these files on your website, accompanied by instructions for users. If you want to include the VoIP operator files in the system distribution so that the user can immediately choose you as the recommended operator , contact your 3CX representative in your area.
Introduction
Most VoIP operators today use a more or less standard set of parameters, which is described in the Generic universal VoIP provider template. We will take the Generic template as the basis for creating an individual custom template. First of all, we explain the difference between the two types of VoIP operators used in 3CX:
VoIP Provider - A VoIP operator that uses authorization by username and password. Most VoIP provider patterns in 3CX are designed for this type of connection.
SIP Trunk - VoIP operator that uses authorization for the public IP address of the 3CX server. The public IP address of the server must be indicated with the operator as the address to which the operator routes calls, and from which he expects calls.
After installing the system, the VoIP operator template files are located in the c: \ ProgramData \ 3CX \ Data \ Http \ Templates \ provider \ folder . Universal templates are called:
GenericVoIPProvider.pv.xml - VoIP operator with authorization by username and password
GenericSIPTrunk.pv.xml - VoIP operator with authorization by IP address (SIP Trunk)
Choose a template depending on the type of authorization that you support!
Creating a custom template
First of all, make a copy of the universal template and name the file by the name of your operator (for example, myprovider.pv.xml ).
The file contains the following sections:
Operator File Header
The header of the XML file for the template indicates the name of the VoIP operator, country, the name of the logo icon file and the website.
Version
This parameter is determined by the template provider (usually a VoIP operator) and can only contain a number. Starts with 1 and increases each time the template is updated. An update may be required when a new version of 3CX is released or when changing operator settings.
URL
Link to the operator’s website, which, for example, may contain tariffs or other important information.
Logo (Image)
It is important to follow the simple rules for creating a provider logo:
The logo must be in PNG format 16 × 16
The name of the image file must match the name of the provider file (without extension), i.e. myprovider.pv.xml> myprovider.png
Addresses and Ports of VoIP Provider Servers (Hostmames and Port Numbers)
This section shows the addresses and ports of the SIP servers of the VoIP operator to which the 3CX Phone System will connect.
RegistrarHost
The IP address or FQDN of the operator’s VoIP server is indicated here. If the ProxyHost / Port parameter is not specified, and RegistrarHost is specified as FQDN, 3CX will try to determine the IP address of the SIP server of the VoIP operator via the SRV record (_sip._udp.myprovider.com) DNS server:
If a response with SRV records is received, 3CX will use the servers with the specified priority.
If SRV records do not exist, 3CX will use a DNS server record.
RegistrarPort
Usually, the SIP port of the operator VoIP server 5060 is indicated here. If the operator server runs on a non-standard port, specify the port number in the template.
ProxyHost (optional)
If the ProxyHost parameter is specified, 3CX Phone System does not search for SRV records, but uses A ProxyHost record. The registration request from 3CX Phone System will be sent to RegistrarHost through the proxy server ProxyHost. Often SIP proxy server and SIP registration server are combined in one server
ProxyPort (optional)
Usually, the SIP port of the proxy operator VoIP server 5060 is indicated here. If the operator proxy server runs on a non-standard port, specify the port number in the template.
Registration Settings
This part of the template indicates the type and authorization parameters of 3CX Phone System on the VoIP provider server.
RegistrationExpiry
This parameter indicates the period of confirmation of registration of 3CX Phone System on the provider's SIP server. The minimum value is 60 seconds. However, 3CX assumes the value transmitted by the operator’s VoIP server, i.e. VoIP carrier time always takes precedence. The default time in the 3CX template is 600 seconds. If the connection type is SIP Trunk, this parameter is not applied, but should still be present in the template.
RequiredAuthFor
This parameter indicates whether authentication of the connection to the VoIP operator is required. As mentioned, if the operator uses authorization by IP address, authentication is not required. A value of 1 means that authentication is not required . As a rule, however, authentication is required for both outgoing and incoming calls . In this case, the value should be 4 . Value 2 - authentication of incoming calls only. Value 3 - authentication of outgoing calls only.
Trunk connections (authorization by IP address)
Authentication parameters should not be entered by the user if 3CX Phone System uses authorization by IP address. Therefore, they should be given a read-only status.
<field name = ”LineAuthenticationPassword” status = ” readonly ”> </field>
<field name = ”3wayauthenticationid” status = ” readonly ”> </field>
Provider Capabilities
These parameters must be defined for all VoIP operators, since 3CX Phone System also acts as a proxy server for its internal users.
IsBindToMS
This parameter determines whether the RTP media stream from the VoIP operator passes through the 3CX server or is sent directly to the final SIP device within the network (i.e. to the user's IP phone). It is strongly recommended that you leave the default value of 1 (pass through a 3CX server).
IsSupportReinvite
A parameter that determines whether the VoIP operator supports the SIP Re-invite method . Enabling or disabling this option helps if holding, retrieving, or transferring a call from the provider is unstable. The possible values are Yes = 1 and No = 0 , but it is recommended to leave the default value of 0 .
IsSupportReplaces
A parameter that determines whether the VoIP operator supports the SIP Replaces header . Enabling or disabling this option helps if holding, retrieving, or transferring a call from the provider is unstable. The possible values are Yes = 1 and No = 0 , but it is recommended to leave the default value of 0 .
Disable Video
This option allows you to remove the SDP description of the video in the media stream. If the VoIP server supports video transmission in the RTP media stream, you can explicitly disable this feature. Possible values are Yes = 1 and No = 0
Available Codecs
This section defines voice codecs and their priority in the SDP stream description. The priority of codecs is determined by the location of the corresponding lines. You can define up to three codecs, but if less is needed, just delete the extra lines. Available options: pcmu, pcma, gsm, g729, g722 .
Source Identification
Upon receipt of an incoming INVITE request, 3CX attempts to identify the source of the call and match it with the corresponding VoIP trunk. The source identification procedure is carried out in various ways.
Recommendations
It is best to keep the source identification settings unchanged. Typically, an INVITE request includes a field that identifies the trunk for which this request is directed. This field must be unique. For VoIP providers using a username and password, the AuthenticationID parameter is usually used in one of the standard SIP fields. Therefore, it is recommended to uncomment the Match Strategy parameter and set it to 1 . Next, indicate in which SIP field (for example, Contact User Part), the VoIP operator sends AuthID.
If a VoIP operator passes AuthID to the Contact User Part field, you can create several VoIP connections to the same operator with different registration parameters (i.e. several independent VoIP lines), and 3CX will correctly determine the source of the call.
<field name = ”MatchStrategy”> 1 </field>
<field name = ”Source” parameter = ”ContactUser” custom = ””> $ AuthID </field>
If registration is not made on the VoIP operator (i.e., the connection is used type Trunk), you have to choose a static source identification parameter, for example, IP address or FQDN name of the host that sent the INVITE request. In the template, it corresponds to the RegistrarHost parameter described above .
In this case, the 3CX user can use only one VoIP connection to this operator, since the source identifier will be duplicated for several connections of the same type.
field name = ”MatchStrategy”> 1 </field>
<field name = ”Source” parameter = ”FromHostPart” custom = ””> $ GWHostPort </field>
Here the GWHostPort parameter must come from the VoIP provider in the same format as it is specified in the RegistrarHost and RegistrarPort parameters of the template.
Inbound / Outbound Parameters
The Incoming and Outgoing SIP Parameters section defines how the 3CX Phone System generates an outgoing INVITE request to a VoIP provider or processes an incoming INVITE request from a VoIP provider.
SIP parameters (Parameter)
SIP parameters are RFC SIP fields in which a specific value is expected from the VoIP operator, or where 3CX should put the SIP value when creating an INVITE request. All available fields are included in the template , so do not add any X or P headers - 3CX will simply ignore them.
All SIP fields are presented in standard SIP format.
An Invite: RequestLineURIUser @ RequestLineURIHost
ContactUser @ ContactHost
ToDisplayName: ToUserPart @ ToHostPart
FromDisplayName: FromUserPart @ FromHostPart
RemotePartyIDCalledPartyDisplayName: RemotePartyIDCalledPartyUserPart @ RemotePartyIDCalledPartyHostPart
RemotePartyIDCallingPartyDisplayName: RemotePartyIDCallingPartyUserPart @ RemotePartyIDCallingPartyHostPart
P-AssertedIdentityDisplayName: P-AssertedIdentityUserPart @ P-AssertedIdentityHostPart
ProxyAuthID @ ProxyAuthRealm
Use only necessary and sufficient (for your VoIP operator) SIP fields to form the outgoing INVITE request. For example, do not specify an RPID field if it is not used by the operator.
In incoming INVITE requests, the most important fields for 3CX Phone System are the location of the CallerNum caller number and the VoIP trunk identifier of the operator. An example of such fields is given below, however, for various VoIP operators it can be expanded.
<field name = ”ParameterIn” custom = ”” parameter = ”ToUserPart”> $ CalledNum </field>
<field name = ”ParameterIn” custom = ”” parameter = ”FromUserPart”> $ CallerNum </field>
<field name = ”ParameterIn” custom = ”” parameter = ”RequestLineURIHost”> $ DevHostPort </field>
XML Variables
The XML variables of the VoIP operator template are enclosed in >> tags . Instead, the 3CX core substitutes the actual SIP values, or reads the necessary values from them. To parse incoming SIP messages, it is necessary that the variable be used only once, i.e. not found in several SIP fields. When generating outgoing SIP messages, the variable can be indicated in various parts of the INVITE request, in accordance with the requirements of the VoIP operator.
Important! Some VoIP operators support Clip No Screening.at which it is possible to transmit the original subscriber number, and not the VoIP line number of the operator. For example, an external subscriber called your extension 3CX, you weren’t there, and the call went to your mobile. In this case, you will see not the line number of the VoIP operator through which the call was issued, but the initial Caller ID of the caller. In this case, in the Outgoing parameters, use the Originator Caller ID , not the Outbound Caller ID .
Variable matching
Keep in mind that not all variables can be combined in SIP requests. We recommend checking the possibility of sharing these or those variables in the corresponding section of the VoIP operator settings in the 3CX interface.
| Variable | Description |
| §GWHostPort | Server and port of the VoIP provider, set when creating a connection in the 3CX interface |
| $ OutHostPort | Server and VoIP proxy port, set when creating a connection in 3CX interface |
| §DevHostPort | Server and port of the VoIP provider from which the INVITE request comes |
| $ ContactURI | Contact field contents |
| $ CalledName | Call Recipient Name (default: To → display name) |
| $ Callednum | Call Recipient Number (Default: To → User) |
| $ CallerName | Call source name (default: From → display name) |
| $ CallerNum | Call Source Number (Default: From → User) |
| $ LineNumber | External line number |
| $ LineID | Internal line number (Virtual extension) |
| $ AuthID | Authentication ID |
| $ OrginatorCallerID | Caller ID of the original call source |
| $ OutboundLineId | Outgoing Caller ID of the line taken from the Outgoing Caller ID field in the VoIP settings of the operator in the 3CX interface |
| $ OutboundCallerID | Outgoing Caller Line ID taken from the Outgoing Caller ID field in the extension parameters in the 3CX interface |
| $ CallerDispName | The caller’s display name from the From header sent by the SIP phone |
| $ CustomField | Custom field |
User variables
If 3CX does not offer value substitution for a variable in the control interface (used in incoming and outgoing parameters, as well as for source identification), you can set the value manually (Custom value). In the example below, manually set mysource.com to identify the source. To: HostPart is a custom value set in accordance with the requirements of the VoIP operator.
<field name = ”Source” parameter = ”ToHostPart” custom = ”mysource.com”> $ CustomField </field>
Conclusion
Obviously, the information presented will be useful not only to the engineers of the operator organizing the connection of 3CX Phone System systems, but also to 3CX administrators, since it helps to understand the purpose of the various options in the configuration interface of the new external connection.
After editing the operator file, place the xml file of the template and png logo file in the same directory in which the rest of the templates are stored. You can also put these files on your website, accompanied by instructions for users. If you want to include the VoIP operator files in the system distribution so that the user can immediately choose you as the recommended operator , contact your 3CX representative in your area.