Creating a VoIP Provider Template in 3CX Phone System
In this article, intended for engineers of VoIP operators, we will discuss how to create a VoIP operator template for 3CX Phone System. The template contains the basic connection parameters, greatly simplifying the connection of the operator’s line to the system.
Most VoIP operators today use a more or less standard set of parameters, which is described in the universal template of VoIP provider Generic. We will take the Generic template as the basis for creating an individual custom template. First of all, we will explain the difference between the two types of VoIP operators used in 3CX:
VoIP Provider - VoIP operator using authorization by username and password. Most of the operators VoIP templates in 3CX are designed for this type of connection.
')
SIP Trunk is a VoIP operator using authorization at the public IP address of the 3CX server. The public IP address of the server must be specified by the operator as the address to which the operator routes calls and from which he expects calls.
After installing the system, the template files of VoIP operators are located in the folder c: \ ProgramData \ 3CX \ Data \ Http \ Templates \ provider \ . 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 of the template contains the name of the VoIP operator, the country, the file name of the logo icon and the web site.
This parameter is determined by the provider of the template (as a rule, by the VoIP operator) and can contain only a number. Starts from 1 and increases with each template update. Updating may be required when a new 3CX version is released or when operator parameters change.
A link to the operator’s web site, which, for example, may contain tariffs or other important information.
It is important to follow the simple rules for creating the provider’s logo:
The logo must be in PNG 16 Ă— 16 format.
The name of the graphic file must match the name of the provider file (without extension), i.e. myprovider.pv.xml> myprovider.png
This section lists the addresses and ports of the SIP server of the VoIP operator, to which 3CX Phone System will connect.
Here you can see the IP address or FQDN of the VoIP server operator. If the ProxyHost / Port parameter is not specified, and the RegistrarHost is specified as a 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 is received with SRV records, 3CX will use the servers with the specified priority.
If SRV records do not exist, 3CX will use the A DNS server record.
Usually, the SIP port of the VoIP server of the operator 5060 is indicated here. If the operator's server is running on a non-standard port, specify the port number in the template.
If the ProxyHost parameter is defined, 3CX Phone System does not search for SRV records, but uses the A record of ProxyHost. The registration request from 3CX Phone System will be sent to RegistrarHost through the proxy server ProxyHost. Often the SIP proxy server and SIP registration server are combined in one server.
Usually, this is the SIP port of the proxy server of the VoIP operator 5060. If the proxy server of the operator is working on a non-standard port, specify the port number in the template.
This part of the template indicates the type and authorization parameters of the 3CX Phone System on the VoIP provider’s server.
This parameter specifies the registration confirmation period for 3CX Phone System on the provider's SIP server. The minimum allowed value is 60 seconds. However, 3CX takes the value transmitted by the VoIP operator’s server, i.e. VoIP operator time always takes precedence. The default time in the 3CX template is 600 seconds. If the connection type is SIP Trunk, this parameter does not apply, but must still be present in the template.
This parameter indicates whether authentication is required to connect to a VoIP operator. As it was said, if the operator uses authorization by IP address, authentication is not required. A value of 1 means no authentication is 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 IP address authorization. Therefore, they should be assigned a read-only status.
<field name = ”LineAuthentication Password” 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 (that is, to the user's IP phone). It is strongly recommended to leave the default value 1 (pass through the 3CX server).
The parameter that determines whether the VoIP operator supports the SIP method Re-invite . Enabling or disabling this option helps if holding, restoring, or transferring a call from the provider is unstable. Possible values ​​are Yes = 1 and No = 0 , but it is recommended to leave the default of 0 .
The parameter that determines whether the VoIP operator supports the SIP Replaces header. Enabling or disabling this option helps if holding, restoring, or transferring a call from the provider is unstable. Possible values ​​are Yes = 1 and No = 0 , but it is recommended to leave the default of 0 .
This option allows you to remove the SDP video description 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 the 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 required, just delete the extra lines.
Available options: pcmu, pcma, gsm, g729, g722 .
When an incoming INVITE request is received, 3CX attempts to identify the source of the call and match the corresponding VoIP trunk to it. The procedure for identifying the source is done in various ways.
It is best to keep the source identification settings intact. Typically, an INVITE request includes a field that identifies the trunk for which the request was sent. This field must be unique. For VoIP providers using a username and password, as a rule, the AuthenticationID parameter is used in one of the standard SIP fields. Therefore, it is recommended to uncomment the Match Strategy parameter and assign the value 1 to it . Next, specify in which SIP field (for example, Contact User Part), the VoIP operator sends the AuthID.
If the VoIP operator sends the AuthID in the Contact User Part field, you can create several VoIP connections to the same operator with different registration parameters (ie, 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 with a VoIP operator is not performed (i.e., a Trunk connection is used), you will have to select a static source identification parameter, such as the IP address or FQDN 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 a single VoIP connection to this operator, since the source identifier with multiple connections of the same type will be duplicated.
field name = ”MatchStrategy”> 1 </ field>
<field name = ”Source” parameter = ”FromHostPart” custom = ””> $ GWHostPort </ field>
Here the GWHostPort parameter should come from the VoIP provider in the same format as it is specified in the RegistrarHost parameter and the RegistrarPort template.
The Incoming and Outgoing SIP Parameters section determines 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 SIP RFC fields, in which a certain value is expected from the VoIP operator, or where 3CX should place 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.
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 the necessary and sufficient (for your VoIP operator) SIP fields to form an outgoing INVITE request. For example, do not define an RPID field if it is not used by an operator.
In incoming INVITE requests, the most important fields for the 3CX Phone System are the location of the CallerNum caller's number and the identifier of the VoIP trunk operator. An example of such fields is given below, however, it can be extended for different VoIP operators.
<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 of the VoIP operator template are enclosed in tags > < . Instead, the 3CX core substitutes the actual SIP values, or reads the required values ​​from them. For parsing incoming SIP messages, it is necessary that the variable is used once, i.e. not met in several SIP fields. When generating outgoing SIP messages, the variable can be specified in different parts of the INVITE request, in accordance with the requirements of the VoIP operator.
Important! Some VoIP operators support the Clip No Screening function, in which you can transfer the original subscriber number, and not the line number of the VoIP operator. For example, an external subscriber called your extension number 3CX, you were not 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 made, but the initial Caller ID of the caller. In this case, use Outgoing parameters Caller ID , not 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 other variables in the appropriate section of setting up a VoIP operator in the 3CX interface.
If 3CX does not offer a substitution of the value for a variable in the management interface (used in incoming and outgoing parameters, as well as when identifying the source), you can set the value manually (Custom value). In the example below, manually set the value to 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 presented information will be useful not only to the engineers of the operator who organizes the connection of 3CX Phone System systems, but also to the 3CX administrators, since it helps to understand the purpose of the various options in the interface settings of the new external connection.
After the operator file has been edited, place the xml template file and the png logo file in the same directory as the rest of the templates. You can also put these files on your web site, accompanied by instructions for users. If you want to include the VoIP operator files in the distribution package so that the user can immediately select you as the recommended operator , contact your local 3CX representative.
Introduction
Most VoIP operators today use a more or less standard set of parameters, which is described in the universal template of VoIP provider Generic. We will take the Generic template as the basis for creating an individual custom template. First of all, we will explain the difference between the two types of VoIP operators used in 3CX:
VoIP Provider - VoIP operator using authorization by username and password. Most of the operators VoIP templates in 3CX are designed for this type of connection.
')
SIP Trunk is a VoIP operator using authorization at the public IP address of the 3CX server. The public IP address of the server must be specified by the operator as the address to which the operator routes calls and from which he expects calls.
After installing the system, the template files of VoIP operators are located in the folder c: \ ProgramData \ 3CX \ Data \ Http \ Templates \ provider \ . 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:
Header File Header
The header of the XML file of the template contains the name of the VoIP operator, the country, the file name of the logo icon and the web site.
Version (Version)
This parameter is determined by the provider of the template (as a rule, by the VoIP operator) and can contain only a number. Starts from 1 and increases with each template update. Updating may be required when a new 3CX version is released or when operator parameters change.
URL
A link to the operator’s web site, which, for example, may contain tariffs or other important information.
Logo (Image)
It is important to follow the simple rules for creating the provider’s logo:
The logo must be in PNG 16 Ă— 16 format.
The name of the graphic file must match the name of the provider file (without extension), i.e. myprovider.pv.xml> myprovider.png
VoIP server addresses and ports (Hostmames and Port Numbers)
This section lists the addresses and ports of the SIP server of the VoIP operator, to which 3CX Phone System will connect.
Registrarhost
Here you can see the IP address or FQDN of the VoIP server operator. If the ProxyHost / Port parameter is not specified, and the RegistrarHost is specified as a 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 is received with SRV records, 3CX will use the servers with the specified priority.
If SRV records do not exist, 3CX will use the A DNS server record.
RegistrarPort
Usually, the SIP port of the VoIP server of the operator 5060 is indicated here. If the operator's server is running on a non-standard port, specify the port number in the template.
ProxyHost (optional)
If the ProxyHost parameter is defined, 3CX Phone System does not search for SRV records, but uses the A record of ProxyHost. The registration request from 3CX Phone System will be sent to RegistrarHost through the proxy server ProxyHost. Often the SIP proxy server and SIP registration server are combined in one server.
ProxyPort (optional)
Usually, this is the SIP port of the proxy server of the VoIP operator 5060. If the proxy server of the operator is working 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 the 3CX Phone System on the VoIP provider’s server.
RegistrationExpiry
This parameter specifies the registration confirmation period for 3CX Phone System on the provider's SIP server. The minimum allowed value is 60 seconds. However, 3CX takes the value transmitted by the VoIP operator’s server, i.e. VoIP operator time always takes precedence. The default time in the 3CX template is 600 seconds. If the connection type is SIP Trunk, this parameter does not apply, but must still be present in the template.
RequiredAuthFor
This parameter indicates whether authentication is required to connect to a VoIP operator. As it was said, if the operator uses authorization by IP address, authentication is not required. A value of 1 means no authentication is 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 IP address authorization. Therefore, they should be assigned a read-only status.
<field name = ”LineAuthentication Password” 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 (that is, to the user's IP phone). It is strongly recommended to leave the default value 1 (pass through the 3CX server).
IsSupportReinvite
The parameter that determines whether the VoIP operator supports the SIP method Re-invite . Enabling or disabling this option helps if holding, restoring, or transferring a call from the provider is unstable. Possible values ​​are Yes = 1 and No = 0 , but it is recommended to leave the default of 0 .
IsSupportReplaces
The parameter that determines whether the VoIP operator supports the SIP Replaces header. Enabling or disabling this option helps if holding, restoring, or transferring a call from the provider is unstable. Possible values ​​are Yes = 1 and No = 0 , but it is recommended to leave the default of 0 .
Disable Video
This option allows you to remove the SDP video description 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 (Codecs)
This section defines the 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 required, just delete the extra lines.
Available options: pcmu, pcma, gsm, g729, g722 .
Source Identification
When an incoming INVITE request is received, 3CX attempts to identify the source of the call and match the corresponding VoIP trunk to it. The procedure for identifying the source is done in various ways.
Recommendations
It is best to keep the source identification settings intact. Typically, an INVITE request includes a field that identifies the trunk for which the request was sent. This field must be unique. For VoIP providers using a username and password, as a rule, the AuthenticationID parameter is used in one of the standard SIP fields. Therefore, it is recommended to uncomment the Match Strategy parameter and assign the value 1 to it . Next, specify in which SIP field (for example, Contact User Part), the VoIP operator sends the AuthID.
If the VoIP operator sends the AuthID in the Contact User Part field, you can create several VoIP connections to the same operator with different registration parameters (ie, 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 with a VoIP operator is not performed (i.e., a Trunk connection is used), you will have to select a static source identification parameter, such as the IP address or FQDN 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 a single VoIP connection to this operator, since the source identifier with multiple connections of the same type will be duplicated.
field name = ”MatchStrategy”> 1 </ field>
<field name = ”Source” parameter = ”FromHostPart” custom = ””> $ GWHostPort </ field>
Here the GWHostPort parameter should come from the VoIP provider in the same format as it is specified in the RegistrarHost parameter and the RegistrarPort template.
Inbound / Outbound Parameters
The Incoming and Outgoing SIP Parameters section determines 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 SIP RFC fields, in which a certain value is expected from the VoIP operator, or where 3CX should place 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.
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 the necessary and sufficient (for your VoIP operator) SIP fields to form an outgoing INVITE request. For example, do not define an RPID field if it is not used by an operator.
In incoming INVITE requests, the most important fields for the 3CX Phone System are the location of the CallerNum caller's number and the identifier of the VoIP trunk operator. An example of such fields is given below, however, it can be extended for different VoIP operators.
<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
XML variables of the VoIP operator template are enclosed in tags > < . Instead, the 3CX core substitutes the actual SIP values, or reads the required values ​​from them. For parsing incoming SIP messages, it is necessary that the variable is used once, i.e. not met in several SIP fields. When generating outgoing SIP messages, the variable can be specified in different parts of the INVITE request, in accordance with the requirements of the VoIP operator.
Important! Some VoIP operators support the Clip No Screening function, in which you can transfer the original subscriber number, and not the line number of the VoIP operator. For example, an external subscriber called your extension number 3CX, you were not 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 made, but the initial Caller ID of the caller. In this case, use Outgoing parameters Caller ID , not Outbound Caller ID .
Matching Variables
Keep in mind that not all variables can be combined in SIP requests. We recommend checking the possibility of sharing these or other variables in the appropriate section of setting up a VoIP operator in the 3CX interface.
| Variable | Description |
| §GWHostPort | Server and port of the VoIP provider installed when creating a connection in the 3CX interface |
| $ Outhostpost | Server and port of VoIP proxy installed when creating a connection in the 3CX interface |
| §DevHostPort | Server and port of the VoIP provider from which the INVITE request comes |
| $ ContactURI | Contact field content |
| $ CalledName | Call recipient name (default: To → display name) |
| $ CalledNum | Call recipient number (default: To → User) |
| $ CallerName | Name of call source (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 Original Call Source |
| $ OutboundLineId | Outgoing Caller ID of the line taken from the Outgoing Caller ID field in the VoIP operator settings in the 3CX interface |
| $ OutboundCallerID | Outgoing Caller ID of the line taken from the Outgoing Caller ID field in the extension settings in the 3CX interface |
| $ CallerDispName | The caller's display name from the From header sent by the SIP phone |
| $ Customfield | Custom field |
Custom variables
If 3CX does not offer a substitution of the value for a variable in the management interface (used in incoming and outgoing parameters, as well as when identifying the source), you can set the value manually (Custom value). In the example below, manually set the value to 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 presented information will be useful not only to the engineers of the operator who organizes the connection of 3CX Phone System systems, but also to the 3CX administrators, since it helps to understand the purpose of the various options in the interface settings of the new external connection.
After the operator file has been edited, place the xml template file and the png logo file in the same directory as the rest of the templates. You can also put these files on your web site, accompanied by instructions for users. If you want to include the VoIP operator files in the distribution package so that the user can immediately select you as the recommended operator , contact your local 3CX representative.
Additional Information
Source: https://habr.com/ru/post/301418/
All Articles