Как создать и использовать пользовательские шаблоны IP‑телефонов в 3CX

Как создать и использовать пользовательские шаблоны IP‑телефонов в 3CX

В современной корпоративной VoIP‑среде важно обеспечить единообразную конфигурацию IP‑телефонов. В 3CX есть механизм создания пользовательских (кастомных) шаблонов, которые позволяют адаптировать настройки телефонов под уникальные требования вашей организации. Эти шаблоны остаются неизменными после обновления самой платформы, что делает их идеальными для корпоративных развертываний.

Что такое кастомный шаблон IP‑телефона

Обычные шаблоны автонастройки формируются из стандартных XML‑файлов, поставляемых 3CX. Если вам нужно изменить параметры, которых нет в стандартных шаблонах (например, подсветку дисплея, дополнительные параметры интерфейса или уникальные provisioning‑параметры), стоит создать собственную копию базового шаблона и отредактировать её под ваши задачи. 

Копирование базового шаблона телефона

1. Перейдите в Admin Console → Advanced → Templates, чтобы открыть страницу с шаблонами телефонов.
   

2. Выберите шаблон из выпадающего списка, который хотите скопировать.

3. Убедитесь, что модель телефона, для которой создаётся пользовательский шаблон, указана в исходном шаблоне.
   

4. Нажмите Copy, присвойте новому шаблону имя (например, yealinkT4x-custom-01) и нажмите OK.

5. Новый шаблон появится в списке в разделе Custom.

6. При настройке телефона для Provisioning вы сможете выбрать свой шаблон через раздел Custom в выпадающем списке Phone Model. Имя модели будет содержать имя вашего пользовательского шаблона.
   

Внесение изменений в шаблон телефона

Перезапуск службы Management Console

После изменения любого шаблона необходимо перезапустить службу Management Console, чтобы изменения вступили в силу.

⚠️ Перезапуск службы сбросит данные о статусе присутствия (presence) клиентов 3CX. Для минимизации риска выполняйте тесты и изменения на нерабочей установке 3CX.

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

Каждый шаблон — это XML-файл, который содержит:

1. Информацию для Management Console, чтобы корректно заполнять provisioning-файл телефона.

   • Не редактируйте этот раздел без необходимости — ошибки могут привести к:

     • невозможности отображения шаблона в Admin Console,

     • недоступности настроек расширения,

     • необходимости восстановления последней рабочей копии,

     • необходимости пересоздания расширения с нуля.

2. Секции <data>, содержащие данные для телефона. Контент для IP-телефона начинается после <![CDATA[ в шаблоне.

Общие правила при настройке шаблонов

• При серьёзных изменениях может потребоваться Factory Reset телефона и provision напрямую с новым шаблоном.

• Избегайте дублирования одних и тех же инструкций.

• Для вопросов по provisioning обращайтесь к документации производителя телефона, а не в поддержку 3CX.

• Если меняете параметр на значение по умолчанию, не удаляйте параметр, а явно задайте значение.

• Не изменяйте ua="XXXXX" в определении модели.

• При сомнениях — консультируйтесь с производителем телефона.

• После внесения изменений перезапустите Management Console и проведите reprovision телефонов.

• Все телефоны, использующие один шаблон, обновятся при следующем цикле provision (обычно в течение 24 часов).

Проверка изменений

1. Подключённые к 3CX телефоны отображаются на странице Phones в Admin Console.

2. Выберите Config в меню телефона, чтобы увидеть конфигурацию, которая будет применена при следующем provisioning.
   
   Обратите внимание, что это НЕ обязательно текущая конфигурация телефона. Вы можете перенастроить телефон, и после перезагрузки на нём должны появиться ваши новые настройки.

3. Можно также получить provisioning-файл через вкладку IP Phone расширения.

4. Пример URL для Yealink:

   

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

   Вставьте URL в браузер, чтобы скачать или просмотреть файл.

Особенности шаблонов Yealink

• Yealink требует двух файлов конфигурации, поэтому шаблон содержит две секции <![CDATA[.

  • Первая секция <![CDATA[: 

  • Содержит настройки, применимые ко всем телефонам с одинаковым номером модели

  • Относится к именам файлов, таким как y00000000xxx.cfg, где xxx — идентификатор модели, определённый Yealink, и не должен изменяться; далее называется «y-файлами»
  • Например, y000000000065.cfg относится к модели устройства Yealink T48S

  • Вторая секция <![CDATA[:

  • Содержит настройки, специфичные для конкретного IP-телефона, такие как добавочный номер, имя пользователя, фамилия и т.д

  • Относится к именам файлов, например, 001122334455.cfg, которые специфичны для устройства с MAC-адресом 001122334455

Настройка y-файла (шаблон, завязанный на модель)

Если вам необходимо изменить файл, привязанный к модели телефона (y-файл), перед развертыванием шаблона нужно учитывать несколько важных моментов:

1. Автоматическое обновление имени модели
   При создании пользовательского шаблона через Admin Console имя модели в XML-заголовках будет обновлено автоматически. Например, для Yealink T48S имя модели в заголовках XML будет выглядеть соответствующим образом.
   

2. Проверка секции <![CDATA[
   В файле шаблона перейдите к первой секции <![CDATA[ и убедитесь, что все имена моделей совпадают с именами в XML-заголовках. Любое расхождение может привести к некорректной работе шаблона.
   

3. Имя y-файла должно соответствовать модели
   Например, для Yealink T48S сохраняем y000000000065.cfg.

   • Все определения y0000000000xx.cfg должны быть уникальны между шаблонами.

   • Самый простой способ сделать это: скопировать весь контент шаблона в текстовый редактор, использовать «Найти и заменить», заменив y0000000000 на y1000000000 для первого пользовательского шаблона, y2000000000 для второго и так далее.
     

⚠️ Помните: изменения в y-файле значительно усложняют настройку. Требуется хорошее понимание принципов provisioning Yealink. Возможно, вам также потребуется изучить файлы .boot.

Универсальные шаблоны

• Настоятельно рекомендуется избегать жесткого кодирования значения портов, IP-серверов, FQDN, логинов и паролей в шаблоне.

• Шаблоны без «локализованных» данных можно использовать на разных установках — удобно для интеграторов, которые внедряют одинаковые настройки для нескольких клиентов.

Папка для пользовательских шаблонов:

Linux:
/var/lib/3cxpbx/Instance1/Data/Http/Interface/provisioning/XXXXXXXXXX/CustomTemplates/phones/

Windows:
C:\ProgramData\3CX\Instance1\Data\Http\Interface\provisioning\XXXXXXXXXX\CustomTemplates\phones

Файлы в этой папке будут резервно копироваться и восстанавливаться при обновлениях системы. Никогда не используйте то же имя файла, что и у стандартного шаблона, так как они будут перезаписаны/обновлены 3CX при необходимости без резервного копирования и предупреждения.

Если папка CustomTemplates\phones не существует, создайте её вручную (с учётом регистра букв) и перезапустите Management Console, чтобы зарегистрировать изменения.

Важная информация о пользовательских шаблонах, поддержке и ответственности

• 3CX предоставляет шаблоны для всех поддерживаемых и устаревших моделей IP-телефонов, которые описывают работу устройств в соответствии с требованиями 3CX

• Любые изменения шаблонов аннулируют официальную поддержку этих устройств.

• Если требуется обращение в поддержку 3CX:

  1. Верните телефон к стандартному шаблону.

  2. Сделайте Factory Reset устройства.

  3. Создавайте тикет только если проблема воспроизводится на стандартном шаблоне.

В противном случае, если во время сессии поддержки c 3CX обнаружится пользовательский шаблон, услуги будут оплачены по тарифу 100€/$ в час владельцем лицензии.

• За исключением этого руководства по правильному созданию пользовательского шаблона, 3CX не предоставляет никакой дополнительной поддержки по этому вопросу.

• Кроме того, автор, вносящий изменения в шаблон, также берет на себя ответственность за постоянное обновление и мониторинг изменений стандартного шаблона, которые могут повлиять на работу пользовательских шаблонов или привести к их сбоям.