Agregue su Marca: Plantillas Personalizadas 3CX

3CX incluye plantillas integradas para los fabricantes de teléfonos compatibles. Si su marca o modelo no figura en esa lista, puede agregar compatibilidad creando una Plantilla Personalizada. Esta guía le explica el proceso utilizando una plantilla de ejemplo que ya está lista para usar y que puede adaptar a sus necesidades.

Qué Hace una Plantilla Personalizada

Una plantilla es un archivo XML que le indica a 3CX cómo generar una configuración de aprovisionamiento para un modelo específico de teléfono. Cuando se aprovisiona un teléfono, 3CX:

1. Cargue la plantilla asignada al dispositivo.
2. Reemplace las variables de 3CX (por ejemplo, %%extension_number%%) por valores reales.
3. Evalúe bloques condicionales (por ejemplo {IF network=SBC}).
4. Guarde el archivo de configuración resultante en la URL de aprovisionamiento que el teléfono obtiene.

Su trabajo al adaptar el ejemplo consiste en asignar la sintaxis de configuración de su proveedor a las variables de 3CX que proporcionan los datos.

Requisitos Previos

• Acceso de Administrador a 3CX (Admin > Avanzado > Plantillas).
• La documentación de aprovisionamiento de su proveedor, específicamente los nombres de los parámetros para las credenciales SIP, los códecs, las teclas BLF, el NTP, la zona horaria, la VLAN y cualquier función que ofrezca su teléfono; algunos proveedores solo proporcionan su documentación técnica a pedido; en cuanto a los recursos en línea, aquí hay algunos ejemplos prácticos:

• Ejemplo de Yealink (Guía de Administración del T57W).
• Parámetros de Aprovisionamiento de la Serie D de Snom.

• La cadena User-Agent del teléfono (visible en el comando SIP REGISTER del dispositivo o en los registros del teléfono 3CX una vez que el dispositivo hace contacto con el PBX).
• El formato de la URL de aprovisionamiento que espera su teléfono.

Procedimiento

• Vaya a Admin > Avanzado > Plantillas > Plantillas de Teléfono.
• Seleccione una plantilla que se acerque a la sintaxis de su proveedor y haga clic en Crear Copia. Asigne a la copia un nombre que refleje su marca (por ejemplo, phonetel-custom.ph).
• Abra la nueva plantilla y reemplace su contenido con la Plantilla de Ejemplo que aparece a continuación.
• Modifique la sección <header>: configure el nombre de la plantilla, el ua (‘User-Agent’), del modelo, el logotipo, los códecs y las capacidades para que coincidan con su dispositivo.
• Modifique la sección CDATA <deviceconfig>. Reemplace cada marcador de posición your_*_variable por el nombre real del parámetro de su proveedor. Mantenga las variables %%...%% 3CX en el lado derecho; estas se sustituyen en el momento del aprovisionamiento.
• Guarde la plantilla.
• Agregue un teléfono en 3CX y seleccione su plantilla personalizada cuando se le solicite el modelo.
• Introduzca la URL de aprovisionamiento proporcionada por 3CX en el teléfono (manualmente o mediante la opción DHCP 66 / PNP) e inicie el proceso de aprovisionamiento.

Estructura de la Plantilla

El XML tiene dos secciones de nivel superior.

Etiqueta de Encabezado

La etiqueta <header> declara los metadatos de la plantilla y los controles de la interfaz de usuario que 3CX muestra para este teléfono:

BlfType y Etiquetas de Datos

• <blftype> — define los formatos de las teclas para cada función BLF (monitor de extensión, tecla de línea, marcación rápida, inicio de sesión en la cola, parqueo, estado del perfil). 3CX los muestra cuando un administrador asigna BLFs en la interfaz de usuario de la extensión.
• <data><device> — enmarca el bloque CDATA <deviceconfig>. El CDATA contiene la sintaxis de configuración literal de su proveedor con variables de 3CX incorporadas. Puede incluir sentencias IF que 3CX analiza para proporcionar diferentes variables según los distintos modelos y condiciones.

Variables de 3CX: Referencia Rápida

Estas son las variables más comunes que se utilizan dentro de la sección CDATA. Las variables se escriben como %%name%% y se sustituyen en el momento del aprovisionamiento.

Identidad y Aprovisionamiento

Extensión / Cuenta SIP

Red

Opciones Disponibles en el Encabezado

Estos provienen de los valores de <option> que usted definió en <header>:

Códecs

BLF / Teclas de Función

Dentro de los bloques {IF blfN} (donde N es el índice de la clave):

Lógica Condicional

La sección CDATA admite condiciones simples. 3CX las evalúa antes de enviar la configuración al teléfono.

Modo de Red

Los diferentes bloques emiten señales según la forma en que el teléfono se conecta al PBX:

{IF network=LOCALLAN}

  ...config for LAN-attached phones...

{ENDIF}

{IF network=SBC}

  ...config for remote phones using the SBC...

{ENDIF}

{IF network=REMOTESTUN}

  ...config for STUN-based remote phones...

{ENDIF}

Posiciones BLF

Cada tecla BLF o tecla de función tiene su propia condición. Dentro del bloque, las variables de contexto BLF (%%Line%%, %%type%%, %%label%%, etc.) hacen referencia a esa tecla:

{IF blf1}

  linekey.1.type  = %%DKtype%%

  linekey.1.value = %%type%%

  linekey.1.label = %%label%%

{ELSE}

  linekey.1.type  = 0

{ENDIF}

Repita el proceso para blf2, blf3, … hasta llegar al número de teclas programables que admita su teléfono.

Parámetros del Sistema

Accede a cualquier parámetro del sistema 3CX mediante sysparam.NAME:

{IF sysparam.CUSTOMIZE_QUEUE_RINGTONES=1}

  ...emit per-queue ringtone mappings...

{ELSE}

  ...emit a single default queue ringtone...

{ENDIF}

Pruebas y Verificación

• Después de guardar la plantilla, agregue una extensión de prueba y asigne su plantilla personalizada como modelo de teléfono.
• Restablezca los ajustes de fábrica del teléfono (recomendado para realizar una prueba sin interferencias).
• Aprovisione el teléfono utilizando una de las siguientes opciones:

• Manual — ingrese %%PROVLINK%% (que se encuentra en la pestaña Teléfono IP de la extensión) en el campo de la URL de configuración del teléfono.
• Opción DHCP 66 — Configure la opción con la URL de configuración del PBX.
• PNP / RPS — si el proveedor lo admite y <rps>1</rps> está configurado en su plantilla.

• Observe el Registro de Actividad de 3CX y los registros locales del teléfono. Verifique que el dispositivo recupere la configuración y se registre correctamente.
• Verifique cada función que haya configurado: orden de los códecs, teclas BLF, tonos de llamada, comportamiento de transferencia, VLAN.

Si un valor aparece incorrecto, revise directamente el archivo de configuración generado - 3CX lo aloja en %%PROVLINK%%/<mac_address>.cfg (o en el patrón de nombre de archivo que haya establecido en <deviceconfig filename="...">).

Configure su Zona Horaria Automáticamente con su Departamento

Su Zona Horaria Global de 3CX o la Zona Horaria personalizada de su Departamento tiene un ID correspondiente a cada nombre de región, tal como se muestra en la tabla de ejemplo a continuación:

Si su plantilla incluye los IDs en su elemento <timezoneParams>, sus teléfonos podrán utilizar la opción predeterminada "Usar Zona Horaria Global". De esta manera, nosotros nos encargamos automáticamente de asignar la zona horaria adecuada y de configurar sus teléfonos en consecuencia, para que no tenga que seleccionar manualmente una zona horaria para cada teléfono por separado.

Si necesita configurar manualmente un ID, consulte aquí la lista completa de IDs de zonas horarias en la guía de referencia de zonas horarias..

Plantilla de Ejemplo

Copie esta plantilla en su plantilla personalizada como punto de partida y, a continuación, reemplace los marcadores de posición de las variables (que aparecen en el fragmento de plantilla a continuación con el formato your_*_variable y [Example_*]) por los parámetros y nombres reales de su dispositivo y proveedor.

Mejores Prácticas para la Edición de Plantillas:

• Formato: Utilice editores de archivos .ph.xml sin procesar o de texto plano. Evite el texto enriquecido (Word/Docs) para prevenir daños en los archivos.
• Estructura: Fuera del bloque CDATA <deviceconfig>, no se toma en cuenta la sangría.
• CDATA: Dentro de la sección CDATA, conserve la sintaxis exacta requerida por el proveedor (espacios y saltos de línea).
• Validación: Guardar como UTF-8, validar el XML e inspeccionar las configuraciones visualizadas en un dispositivo de prueba.

<?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>

    <!-- Template Name -->

    <name>[Example_GreatPhone]</name>

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

    <templatetype>supported</templatetype>

    <!-- List the model user agent, SBC capability, logo filename/dimensions/bitdepth, and model name -->

    <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>

      <!-- The name "[Example_GreatPhone.png]" also defines the firmware foldername -->

    </models>

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

...

    <languages>

    <!-- Options: Language drop-down entries -->

      <option value="English">

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

      </option>

    </languages>

    <ringtones>

    <!-- Default Ringtone drop-down entries -->

      <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[

<!-- The below example section will contain all of your own vendor syntax, replacing 3CX variables with what you define above -->

your_provisioning_url_variable = %%PROVLINK%%

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

your_ntp_server_variable = %%param::time_ntp_server%%

...

<!-- Your own vendor syntax ends here -->

]]></deviceconfig>

    </device>

  </data>

</doc>

Solución de Problemas

Próximos Pasos

Una vez que su plantilla se haya aprovisionado correctamente, considere lo siguiente:

• Publicarlo a través de Crear Copia y compartirlo con otros administradores de su organización.
• Enviarlo a 3CX para que lo incluyan como una plantilla respaldada por la comunidad.
• Agregar entradas <model> adicionales a la misma plantilla si los modelos de su proveedor comparten un esquema de configuración.

Ver También

• Configurando Teléfonos IP.
• Opciones de Aprovisionamiento de Teléfonos IP.
• Teléfonos IP Soportados.
• Crear Plantillas Personalizadas para su Teléfono con IA.

El contenido se aplica a

Versión: Desde V20 U8 | Edición: IA, Pro, Basic | Implementación: Hospedado por 3CX, On-Premise, Autohospedado

Última Actualización

Este documento se actualizó por última vez el 10 de Septiembre de 2026
https://www.3cx.es/docs/custom-phone-template-configuration/