Руководство по пользовательским шаблонам телефонов

3CX поставляется со встроенными шаблонами для поддерживаемых производителей телефонов. Если вашего бренда или модели нет в этом списке, вы можете добавить поддержку, создав пользовательский шаблон (Custom Template). В этом руководстве описывается данный процесс на примере рабочего шаблона, который можно адаптировать под свои нужды.

Что делает пользовательский шаблон

Шаблон — это XML-файл, который указывает 3CX, как сгенерировать конфигурацию автонастройки (provisioning) для конкретной модели телефона. При автонастройке телефона 3CX выполняет следующие действия:

1. Загружает шаблон, назначенный устройству.
2. Заменяет переменные 3CX (например, %%extension_number%%) на реальные значения.
3. Обрабатывает условные блоки (например, {IF network=SBC}).
4. Записывает итоговый конфигурационный файл по URL-адресу автонастройки (provisioning URL), к которому обращается телефон.

Ваша задача при адаптации примера — сопоставить синтаксис конфигурации вашего производителя с переменными 3CX, которые предоставляют данные.

Предварительные требования

• Доступ администратора к 3CX (Admin > Advanced > Templates).
• Документация по автонастройке от вашего производителя, в частности — названия параметров для учетных данных SIP, кодеков, BLF-клавиш, NTP, часового пояса, VLAN и любых других функций, поддерживаемых вашим телефоном. Некоторые производители предоставляют техническую документацию только по запросу. В качестве примеров онлайн-ресурсов можно привести следующие:

• Пример Yealink (Руководство администратора T57W)
• Параметры автонастройки Snom D Series

• Строка User-Agent телефона (отображается в SIP REGISTER устройства или в журналах телефонов 3CX, когда устройство связывается с АТС).
• Формат URL-адреса автонастройки, который ожидает ваш телефон.

Процедура

• Перейдите в Admin > Advanced > Templates > Phone Templates.
• Выберите шаблон, наиболее близкий к синтаксису вашего производителя, и нажмите Create Copy. Назовите копию именем вашего бренда (например,phonetel-custom.ph).
• Откройте новый шаблон и замените его содержимое на пример шаблона, приведенный ниже.
• Отредактируйте раздел <header>: укажите имя шаблона, ua (User-Agent) модели, логотип, кодеки и возможности в соответствии с вашим устройством.
• Отредактируйте раздел CDATA в блоке <deviceconfig>. Замените каждый плейсхолдер your_*_variable на реальное имя параметра вашего производителя. Оставьте переменные 3CX вида %%...%% с правой стороны — они будут заменены во время автонастройки.
• Сохраните шаблон.
• Добавьте телефон в 3CX и выберите ваш пользовательский шаблон при запросе модели.
• Введите URL-адрес автонастройки, предоставленный 3CX, в телефон (вручную или через DHCP опцию 66 / PNP) и запустите процесс автонастройки.

Структура шаблона

XML-файл состоит из двух секций верхнего уровня.

Тег Header

Тег <header> объявляет метаданные шаблона и элементы управления пользовательского интерфейса, которые 3CX отображает для этого телефона:

Теги BlfType и Data

• <blftype> — определяет форматы клавиш для каждой функции BLF (отслеживание статуса добавочного номера, линия, быстрый набор, вход в очередь, парковка вызова, статус профиля). 3CX перебирает их, когда администратор назначает BLF-клавиши в настройках добавочного номера.
• <data><device> — оборачивает блок CDATA <deviceconfig>. Раздел CDATA содержит точный синтаксис конфигурации вашего производителя со встроенными переменными 3CX. В нем могут использоваться условные операторы IF, которые 3CX обрабатывает для подстановки разных переменных в зависимости от модели и условий.

Переменные 3CX: Краткий справочник

Это наиболее часто используемые переменные внутри раздела CDATA. Переменные записываются в формате %%name%% и подставляются во время автонастройки.

Идентификация и автонастройка

Добавочный номер / SIP-аккаунт

Сеть

Параметры, определяемые в заголовке (Header)

Они берутся из значений тега <option>, которые вы задали в разделе <header>:

Кодеки

BLF / Функциональные клавиши

Внутри блоков {IF blfN} (где N — индекс клавиши):

Условная логика

Раздел CDATA поддерживает простые условные выражения. 3CX обрабатывает их перед отправкой конфигурации на телефон.

Сетевой режим

Различные блоки генерируются в зависимости от того, как телефон подключается к АТС:

{IF network=LOCALLAN}

  ...настройки для телефонов, подключенных по локальной сети (LAN)...

{ENDIF}

{IF network=SBC}

  ...настройки для удаленных телефонов, использующих SBC...

{ENDIF}

{IF network=REMOTESTUN}

  ...настройки для удаленных телефонов, использующих STUN...

{ENDIF}

Слоты BLF

Каждая BLF / функциональная клавиша имеет собственное условие. Внутри этого блока контекстные переменные BLF (%%Line%%, %%type%%, %%label%% и т. д.) относятся к данной клавише:

{IF blf1}

  linekey.1.type  = %%DKtype%%

  linekey.1.value = %%type%%

  linekey.1.label = %%label%%

{ELSE}

  linekey.1.type  = 0

{ENDIF}

Повторите эту конструкцию для  blf2, blf3, … вплоть до того количества программируемых клавиш, которое поддерживает ваш телефон.

Системные параметры

Вы можете обращаться к любому системному параметру 3CX через sysparam.NAME:

{IF sysparam.CUSTOMIZE_QUEUE_RINGTONES=1}

  ...назначение индивидуальных рингтонов для каждой очереди...

{ELSE}

  ...один рингтон для очередей по умолчанию...

{ENDIF}

Тестирование и проверка

• После сохранения шаблона добавьте тестовый добавочный номер и выберите ваш пользовательский шаблон в качестве модели телефона.
• Сбросьте телефон до заводских настроек (рекомендуется для чистоты тестирования).
• Выполните автонастройку телефона одним из следующих способов:

• Вручную — введите %%PROVLINK%% (отображается на вкладке «IP-телефон» добавочного номера) в поле URL-адреса автонастройки телефона.
• DHCP-опция 66 — укажите в этой опции URL автонастройки (provisioning URL) вашей АТС.
• PNP / RPS — если производитель поддерживает этот функционал, и в вашем шаблоне задано <rps>1</rps>.

• Проверьте Журнал событий 3CX (Activity Log) и локальные журналы телефона. Убедитесь, что устройство успешно получает конфигурацию и регистрируется.
• Проверьте работу всех настроенных функций: порядок кодеков, BLF-клавиши, рингтоны, поведение при переводе вызова и настройки VLAN.

Если какое-либо значение применяется неверно, проверьте сгенерированный конфигурационный файл напрямую — 3CX предоставляет его по адресу %%PROVLINK%%/<mac_address>.cfg (или по шаблону имени файла, который вы задали в <deviceconfig filename="...">).

Автоматическая настройка часового пояса в соответствии с отделом

Глобальный часовой пояс 3CX или индивидуальный часовой пояс вашего отдела имеет соответствующий ID для каждого названия региона, как показано в таблице примеров ниже:

Если ваш шаблон содержит эти ID в теге <timezoneParams>, телефоны смогут использовать опцию по умолчанию «Использовать глобальный часовой пояс» (Use Global Time Zone). В этом случае 3CX автоматически сопоставит часовой пояс и передаст нужные настройки на устройства, чтобы вам не приходилось вручную выбирать часовой пояс для каждого телефона в отдельности.

Если вам необходимо задать ID вручную, полный список идентификаторов можно найти в справочном руководстве по часовым поясам здесь.

Пример шаблона

Скопируйте этот шаблон в ваш пользовательский шаблон в качестве основы, а затем замените плейсхолдеры переменных (представленные в фрагменте шаблона ниже в формате your_*_variable и [Example_*]) на реальные параметры и названия от вашего производителя.

Рекомендации по редактированию шаблонов:

• Формат: Используйте редакторы простого текста или специализированные редакторы кода для работы с файлами .ph.xml. Избегайте текстовых процессоров (таких как Word или Google Docs), чтобы предотвратить повреждение форматирования.
• Структура: За пределами блока CDATA <deviceconfig> отступы игнорируются.
• CDATA: Внутри раздела CDATA строго сохраняйте синтаксис, требуемый производителем (включая пробелы и переносы строк).
• Проверка: Сохраняйте файл в кодировке UTF-8, проверяйте XML на валидность и всегда тестируйте сгенерированные конфигурации на реальном устройстве.

<?xml version="1.0" encoding="utf-8"?>

<doc xmlns:tcx="http://www.3cx.com">

  <header>

    <type>phone-template</type>

    <version>150000</version>

    <time>2026-01-01 12:30:00</time>

    <!-- Имя шаблона -->

    <name>[Example_GreatPhone]</name>

    <url>https://www.3cx.com/sip-phones/</url>

    <templatetype>supported</templatetype>

    <!-- Укажите user agent модели, поддержку SBC, имя файла/размеры/глубину цвета логотипа и название модели -->

    <models>

      <model ua="[Example_GP100]" canbesbc="true" defaultlogo="[Example_GreatPhone.png]" logowidth="320" logoheight="240" logobitdepth="24">[Example_GreatPhone GP100]</model>

      <model ua="[Example_GreatPhone GP200]" canbesbc="true" defaultlogo="[Example_GreatPhone.png]" logowidth="320" logoheight="240" logobitdepth="24">GreatPhone GP200</model>

      <!-- Имя файла "[Example_GreatPhone.png]" также определяет имя папки с прошивкой -->

    </models>

    <description>[Example_GreatPhone SIP Phones]</description>

...

    <languages>

    <!-- Опции: Элементы выпадающего списка языков -->

      <option value="English">

        <item name="your_language_variable">English</item>

      </option>

    </languages>

    <ringtones>

    <!-- Элементы выпадающего списка рингтонов по умолчанию -->

      <option value="Ring 1">

        <item name="defringtone">your_ring1_variable</item>

      </option>

    </ringtones>

....

  <data>

    <device>

      <type>phone</type>

      <!-- Понятное имя (Friendly Name) -->

      <field name="Name">[Example_GreatPhone GP100 Identity]</field>

      <deviceconfig filename="%%mac_address%%.cfg"><![CDATA[

<!-- Приведенный ниже раздел примера будет содержать синтаксис вашего производителя, где переменные 3CX заменяются на параметры, определенные выше -->

your_provisioning_url_variable = %%PROVLINK%%

your_firmware_url_variable = %%PROVLINK%%/firmware/[Example_GreatPhone]/%%firmware%%

your_ntp_server_variable = %%param::time_ntp_server%%

...

<!-- Синтаксис вашего производителя заканчивается здесь -->

]]></deviceconfig>

    </device>

  </data>

</doc>

Устранение неполадок

Дальнейшие действия

После того как ваш шаблон начнет успешно выполнять автонастройку, рассмотрите следующие шаги:

• Опубликовать его через функцию Create Copy и поделиться с другими администраторами вашей организации.
• Отправить его в 3CX для добавления в качестве шаблона, поддерживаемого сообществом (community-supported).
• Добавить дополнительные записи <model> в этот же шаблон, если другие модели вашего производителя используют одинаковую схему конфигурации.

Дополнительная информация

• Подключение IP-телефонов
• IP Phone Provisioning Options
• Поддерживаемые IP-телефоны
• Создание пользовательских шаблонов телефонов с помощью ИИ

Контент применим к Версия: V20 U8 и выше - Редакция: AI, Pro, Basic - Развертывание: хостинг 3CX, локально, собственный хостинг

Версия документа

Последнее обновление документа 10 сентября 2026
https://www.3cx.ru/docs/custom-phone-template-configuration/