Creating Custom IP Phone Templates

Duplicate A Base Phone Template

  1. Go to "Admin Console → Advanced → Templates" to get to the Phone Templates page
  2. Select the template from the drop-down you wish to copy

  1. Ensure that the model for which you are creating this custom template is listed within this template

  1. Click the Copy button and give it a new name (in this example yealinkT4x-custom-01), then click the OK button.

  1. Your new custom template will now be visible in the list of Phone Templates at the end of the list under the Custom section.

  1. When you configure a phone for provisioning, you can select your customisations by selecting the model from the Custom section in the Phone Model drop-down; the phone model name will have the filename of your custom template appended to it

Making Changes to a Phone Template

Restarting the Management Console service

When a change is made to any template, the Management Console service will need to be restarted to reflect these changes.

Restarting the Management Console service will drop any presence information displayed by the 3CX Clients (web / desktop / phone). To avoid disruption, perform your tests and changes on a non-production 3CX installation.

Notes about Template File structure

Each template file is an XML file consisting of:

  • information required by the Management Console service to populate appropriate values into each extension's phone provisioning file, depending on the extension's particular desired configuration; please note that this should NOT be adjusted, and any mistakes in this section may result in
  • the inability to list the custom template in the Admin Console
  • extension settings not being accessible anymore
  • the need to restore the last working copy of the template
  • the need to delete the extension completely and re-creating it from scratch
  • one or more <data> sections that contain the data that will be built for the phone by the Management Console service; the content sent to an IP phone will start just after the string <![CDATA[ within the template

General Rules when customising templates

  • 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.
  • Avoid duplicates of the same instruction (provisioning parameter) to the device
  • If you have how-to questions about provisioning a phone, you should refer to the provision guide of the vendor; do not refer to 3CX support for how-to questions
  • If you decide to adjust a particular parameter for a phone to the phone's documented default value, then do NOT simply remove the parameter and assume the default value, but actively set the parameter to the default value
  • Never alter the ua="XXXXX" definition in the template model definition
  • When in doubt, contact the IP phone vendor for more information
  • You can seek help in the 3CX forums
  • Remember to restart the Management Console service after any changes
  • Reprovision the phone after changes
  • Remember all phones using the same template will update to the changes during the next provisioning cycle; typically this happens within the next 24 hours (exceptions apply)

Reviewing Changes

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

 

If the phone is connected to 3CX, it will show up in the Phones page in the Admin Console. Select the Config option in the phone's menu to show the configuration which will be applied to the phone during the next provisioning cycle.

Note that this is NOT necessarily the current configuration for the phone; you can reprovision the phone, and after the reprovisioning restart, it should have your new settings.

You can also use the extension's IP Phone tab in the Admin Console to get to the phone's provision file. Consider the following example for a Yealink phone:

You can build the full provisioning URL by concatenating the Provisioning Link and the device-specific provisioning filename; for this example:

https://3cx.example.com/provisioning/abcdef1234/001122334455.cfg

You can paste this URL into any browser, and you will get a copy of the provisioning file. If the browser tries to render the file instead of downloading it, you can use the View page source option in your browser to see the file contents.                                

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
  • contains settings that apply to all phones with the same model number
  • refers to filenames like y000000000xxx.cfg where xxx is the model identifier defined by Yealink and must not be changed; hereafter referred to as "y-files"
  • for example, y000000000065.cfg refers to device model Yealink T48S
  • The second <![CDATA[ section
  • contains settings specific to a particular IP Phone, such as extension number, user first and last name, etc
  • refers to filenames like 001122334455.cfg which is specific to the device with MAC address 001122334455

If you absolutely need to customize the model-centric file (the y-file), then some changes need to be applied before rolling out the template:

  1. Creating a custom template from the Admin Console will automatically adjust the model name in the XML header lines; in this example, you would expect the model name for the T48S to look like this:

  1. Within the custom template file, navigate to the first <![CDATA[ section, and ensure that ALL model names are IDENTICAL to the model names in the XML header lines; for this example; your changes should look like this:

  1. The y-file filename MUST be correct for the model number; in this example, we have retained y000000000065.cfg to correctly match model Yealink T48S
  2. 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…

 

  • Keep in mind that customizing the y-file content makes your setup significantly more complex, and you will need to become VERY familiar with the intricacies of Yealink provisioning concepts; you will possibly also need to investigate .boot files.

Universal Templates

It is strongly recommended to avoid to hard-coding any values of ports, server IPs or FQDNs, usernames and passwords in a template

When templates do NOT contain such “localized” information, they can be used universally across multiple installations - this can be very useful for integrators replicating the same changes for multiple customers. Custom templates can 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 the folder "CustomTemplate\phones" does not exist, you can create the two folders (case sensitive) and immediately restart the Management Console service to register the changes.

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 applying a Factory Reset to the device, and ONLY open a support ticket if the issue can 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 8 January 2026

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