Creating Custom IP Phone Templates

Duplicate A Base Template

  1. Go to “Management Console → Settings → Templates”.
  2. Select the default template from the drop-down (1) you want to make a copy of.
  3. Ensure that the model (2) to which a custom template shall be created is listed within this template.
  4. Press the “Copy” button (3) and give it a new name, then press “OK”. The given name will be appended to the model name visible in the phone provisioning list as an identifier of the custom template.

Making Changes

Keeping in mind that any changes made to a template in the “Management Console Service (MC01)” has to be restarted. Side effects are lost of MyPhone/Web Client presence. Therefore it is advised to test template changes on an unused 3CX install with a sample device in a non production environment first.

The content sent to an IP phone will start just after this string within the template:

<![CDATA[

Any information above this is to do with the management console and should not be touched. Any mistake in this area will result in the inability to list the custom template in the Management Console and extension settings may not be accessible anymore. The last working copy might need to be restored or the extension must be deleted completely.

General Rules

  • Avoid duplicates of the same instruction (provisioning parameter) to the device
  • Refer to the provision guide of the vendor, not 3CX support for “how to questions”
  • If a value should be changed from B to default device value A do not just delete the provisioning entry, set it actively back to A
  • Never alter the “ua=”XXXXX”” definition in the template model definition
  • If in doubt contact the IP phone vendor for more information
  • Seek help in the 3CX forums
  • Remember to restart management console after changes
  • Reprovision the phone after changes
  • Remember all phones using the same template will update to the changes within the next 24 hours (exceptions apply)

Reviewing Changes

There are various ways to check if the alterations are correctly parsed into the phone's provisioning file.

 

If a phone is connected to 3CX press the “Config+” button from the “Phones” node while the device in question is selected. This will render the “to apply config” in real time (it does not necessarily mean that this config is the current running config of the device).

Or open the Extension’s phones provisioning tab and build the full provisioning URL containing the MAC address from the given information. The above shown sample may result into http://mypbx.3cx.eu/provisioning/ads234cfsda/cfg123456787890. Paste this in any browser and you will get the copy of the provisioning file. If the file is in a valid XML format some browsers tend to render the content directly without downloading the file. Right click and then “Show Source” to see the “real” generated information.

Map an IP Phone to a Custom Template

Map to an unprovisioned/factory reset IP Phone

  1. Open the Management Console and go to the “Phones” node.
  2. Find the IP Phone you want to provision and highlight it.
  3. Press Add/Assign Ext depending on what you want to do.
  4. In the “Phone Provisioning” tab copy the MAC address of the existing device.
  5. Press the “Delete” button next to the “Your phones” drop-down.
  6. Press the “Add” button and in the new window that opens:
  1. Select the custom template name from the drop-down
  2. Paste the MAC address you copied in step #4
  1. Press OK, then OK again to save the extension.
  2. Go to the “Phones” node, highlight the phone and press reprovision.

Map to an already provisioned IP Phone

  1. Go to the “Management Console → Extensions” → double-click on the extension you want to apply the template to → “Phone Provisioning” tab.
  2. In the “Your phones” drop-down, select the IP Phone you want to apply the custom template to.
  3. Copy the MAC address of the existing device.
  4. Press the “Delete” button next to the “Your phones” drop-down.
  5. Press the “Add” button and in the new window that opens:
  1. Select the custom template name from the drop-down
  2. Paste the MAC address you copied in step #3.
  1. Press OK, then OK again to save the extension.
  2. Go to the “Phones” node, highlight the phone and press reprovision.

Important Note

Depending on the changes you have made in your custom template, it may be required to first Factory Reset the IP Phone, then provision it directly with the custom template.

Yealink-specific template changes

As opposed to most other phones, Yealink phones require 2 configuration files for provisioning and therefore has two <![CDATA[ sections within one template generating two files.

  • The first <![CDATA[ section is the device defaults as “model” and refer to file-names like y0000000000xx.cfg where by xx is a model specific identifier defined by Yealink and must not be changed. Further referred to as “y-files”.
  • The second <![CDATA[ section is for the “device” mac specific configuration itself containing user specific information like extension number.

For correctly working custom yealink template a manual alteration needs to be done before rolling out the template:

  1. The given name of the custom template alters the model name. This new model name needs to be set just above the first <![CDATA[ section for each model 1:1 to the same model name! Ensure that the model name refers to the correct y-file xx ending (eg a T19P’s y-file ends in 53 and MUST remain unchanged).


  1. The y0000000000xx.cfg definitions must be unique across all templates. The easiest way to achieve this is by selecting the whole template content and copying it into a text editor, then use the “Replace All” function and use find y0000000000 and replace with y1000000000 for the first custom template, y2000000000 for the second and so on…

 

Universal Templates

Generally it should be avoided to hard code any values of ports, server IPs or FQDNs, usernames and passwords in a template. In case a template does not contain such “localized” information, the template is a universal template and can be copied to other installations, interesting for integrators often replicating the same changes. Custom templates shall be copied into the following directory:

  • Linux:  /var/lib/3cxpbx/Instance1/Data/Http/Interface/provisioning/XXXXXXXXXX/CustomTemplates/phones/
  • Windows:  C:\ProgramData\3CX\Instance1\Data\Http\Interface\provisioning\XXXXXXXXXX\CustomTemplates\phones

Files in this folder will be backed up and restored on system updates. NEVER use the same filename as a stock template, as those will be overwritten/updated by 3CX if needs be without any backup and warning.

In case “CustomTemplate\phones” does not exist, create the two folders (case sensitive) and restart the MC01 service after.

Important: Custom Templates & Support

3CX ships templates for all supported and legacy IP phones which cover the operation of the devices in relation to 3CX. Modifying those templates voids the support for those devices as per our support guidelines (reference here). If support for a device is required involving 3CX support, the device must be brought back to the default stock template after Factory Resetting the device, before opening a support ticket and the issue must be replicated with the stock template. If failing to do so, and a custom template is detected during the 3CX support session, the carried out support will be billed at a rate of 100€/$ per hour to the license key holder.

Except for this guide on how to correctly start creating a custom template there is NO further support available whatsoever on this matter from 3CX. Furthermore, the altering author of the template also takes the responsibility to constantly update and monitor stock template changes which might affect or break custom templates.

See also

Last Updated

This document was last updated 2 June 2023

https://www.3cx.com/docs/custom-ip-phone-templates/