Adicione Sua Própria Marca de Telefone: Guia

O 3CX vem com modelos integrados para os fabricantes de telefones compatíveis. Se a sua marca ou modelo não estiver nessa lista, você pode adicionar compatibilidade criando um Modelo Personalizado. Este guia explica passo a passo o processo, utilizando um modelo de exemplo funcional que você pode adaptar.

O que um Modelo Personalizado Faz

Um modelo é um arquivo XML que indica ao 3CX como gerar uma configuração de provisionamento para um modelo específico de telefone. Quando um telefone é provisionado, o 3CX:

1. Carrega o modelo atribuído ao dispositivo.
2. Substitui as variáveis do 3CX (por exemplo, %%extension_number%%) por valores reais.
3. Avalia blocos condicionais (por exemplo, {IF network=SBC}).
4. Grava o arquivo de configuração resultante na URL de provisionamento que o telefone acessa.

Sua tarefa ao adaptar o exemplo é mapear a sintaxe de configuração do seu fornecedor para as variáveis do 3CX que fornecem os dados.

Pré-requisitos

• Acesso de administrador ao 3CX (Admin > Avançado > Modelos).
• A documentação de provisionamento do seu fornecedor, especificamente os nomes dos parâmetros para credenciais SIP, codecs, teclas BLF, NTP, fuso horário, VLAN e qualquer recurso que seu telefone ofereça; alguns fornecedores disponibilizam sua documentação técnica somente mediante solicitação; quanto aos recursos on-line, aqui estão alguns exemplos práticos:

• Exemplo da Yealink (Guia do Administrador do T57W)
• Parâmetros de Provisionamento da Série D Snom

• A string User-Agent do telefone (visível no SIP REGISTER do dispositivo ou nos logs de telefone do 3CX assim que o dispositivo entrar em contato com o PABX).
• O formato da URL de provisionamento esperado pelo seu celular.

Procedimento

• Acesse Admin > Avançado > Modelos > Modelos de Telefone.
• Selecione um modelo com sintaxe semelhante à do seu fornecedor e clique em Criar Cópia. Nomeie a cópia com o nome da sua marca (por exemplo, phonetel-custom.ph).
• Abra o novo modelo e substitua seu conteúdo pelo “Modelo de Exemplo” abaixo.
• Edite a seção <header>: defina o nome do modelo, o ua (User-Agent), o logotipo, os codecs e os recursos de acordo com o seu dispositivo.
• Edite a seção <deviceconfig>. Substitua todos os marcadores de lugar your_*_variable pelo nome real do parâmetro do seu fornecedor. Mantenha as variáveis 3CX  %%...%% no lado direito — elas serão substituídas no momento do provisionamento.
• Salve o modelo.
• Adicione um telefone no 3CX e selecione seu modelo personalizado quando for solicitado a informar o modelo.
• Insira a URL de provisionamento fornecida pela 3CX no telefone (manualmente ou por meio da opção 66 do DHCP / PNP) e inicie o processo de provisionamento.

Estrutura do Modelo

O XML possui duas seções de nível superior.

Tag de Cabeçalho

A tag <header> declara os metadados do modelo e os controles da interface do usuário que o 3CX exibe para este telefone:

BlfType e Tags de Dados

• <blftype> — define os formatos das teclas para cada função BLF (monitor de ramal, tecla de linha, discagem rápida, login na fila, estacionamento, status do perfil). O 3CX os itera quando um administrador atribui BLFs na interface de usuário do ramal.
• <data><device> — envolve o bloco CDATA <deviceconfig>. O CDATA contém a sintaxe de configuração literal do seu fornecedor, com variáveis do 3CX incorporadas. Ele pode conter instruções IF que o 3CX analisa para fornecer variáveis diferentes para diversos modelos e condições.

Variáveis do 3CX: Referência Rápida

Estas são as variáveis mais comuns utilizadas na seção CDATA. As variáveis são escritas na forma %%name%% e são substituídas no momento do provisionamento.

Identidade e Provisionamento

Ramal / Conta SIP

Network

Options Exposed by the Header

These come from the <option> values you defined in <header>:

Codecs

BLF / Teclas de Função

Dentro dos blocos {IF blfN} (onde  N é o índice da chave):

Lógica Condicional

A seção CDATA suporta condicionais simples. O 3CX as avalia antes de enviar a configuração para o telefone.

Modo de Rede

Diferentes blocos são emitidos dependendo de como o telefone está se conectando ao PABX:

{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}

BLF Slots

Cada tecla BLF/de função possui sua própria condição. Dentro do bloco, as variáveis de contexto BLF (%%Line%%, %%type%%, %%label%%, etc.) referem-se a essa tecla:

{IF blf1}

  linekey.1.type  = %%DKtype%%

  linekey.1.value = %%type%%

  linekey.1.label = %%label%%

{ELSE}

  linekey.1.type  = 0

{ENDIF}

Repita o procedimento para blf2, blf3, … até o número de teclas programáveis que seu telefone suporta.

Parâmetros do Sistema

Consulte qualquer parâmetro do sistema 3CX por meio de sysparam.NAME:

{IF sysparam.CUSTOMIZE_QUEUE_RINGTONES=1}

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

{ELSE}

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

{ENDIF}

Testes e Verificação

• Depois de salvar o modelo, adicione um ramal de teste e atribua seu modelo personalizado como o modelo do telefone.
• Restaure as configurações de fábrica do celular (recomendado para um teste sem interferências).
• Configure o telefone usando uma das seguintes opções:

• Manual — insira %%PROVLINK%% (visível na aba “Telefone IP” do ramal) no campo “URL de provisionamento” do telefone.
• Opção 66 do DHCP — aponte a opção para a URL de provisionamento do PABX.
• PNP / RPS — caso o fornecedor ofereça suporte a isso e <rps>1</rps> esteja definido no seu modelo.

• Verifique o Registro de Atividades do 3CX e os registros locais do telefone. Confirme se o dispositivo obtém a configuração e se registra com sucesso.
• Verifique cada recurso que você mapeou: ordem dos codecs, teclas BLF, toques, comportamento de transferência, VLAN.

Se algum valor estiver incorreto, verifique diretamente o arquivo de configuração gerado — o 3CX o disponibiliza em %%PROVLINK%%/<mac_address>.cfg (ou no padrão de nome de arquivo definido em <deviceconfig filename="...">).

Defina Seu Fuso Horário Automaticamente com Seu Departamento

Seu Fuso Horário Global do 3CX ou o Fuso Horário Personalizado do seu Departamento possui um ID correspondente a cada nome de região, conforme mostrado na tabela de exemplo abaixo:

Se o seu modelo contiver os IDs no elemento <timezoneParams>, seus telefones poderão utilizar a opção padrão “Usar Fuso Horário Global”. Nesse caso, nós configuramos automaticamente o fuso horário para você e provisionamos seus telefones de acordo com ele, para que você não precise selecionar manualmente um fuso horário para cada telefone individualmente.

Se você precisar definir manualmente um ID, consulte a lista completa de IDs de fusos horários no guia de referência de fusos horários aqui.

Modelo de Exemplo

Copie este modelo para o seu modelo personalizado como ponto de partida e, em seguida, substitua os marcadores de variáveis (exibidos no trecho do modelo abaixo no formato your_*_variable e [Example_*]) pelos parâmetros e nomes reais do seu dispositivo e do fabricante.

Melhores Práticas de Edição de Modelos:

• Formato: Use arquivos .ph.xml sem formatação ou editores de texto simples. Evite arquivos de texto formatado (Word/Docs) para evitar erros de codificação.
• Estrutura: Fora do bloco CDATA <deviceconfig>, a indentação é ignorada.
• CDATA: Dentro da seção CDATA, mantenha exatamente a sintaxe exigida pelo fornecedor (espaços/quebras de linha).
• Validação: Salve como UTF-8, valide o XML e verifique as configurações exibidas em um dispositivo de teste.

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

Solução de Problemas

Próximos Passos

Depois que seu modelo estiver funcionando corretamente, considere o seguinte:

• Publicá-lo por meio de Criar Cópia e compartilhá-lo com outros administradores da sua organização.
• Enviando-o à 3CX para que seja incluído como um modelo com suporte da comunidade.
• Adicionar entradas <model> adicionais ao mesmo modelo, caso os modelos do seu fornecedor compartilhem um esquema de configuração.

Veja Também

• Configuração de Telefones IP
• Opções de Provisionamento de Telefones IP
• Telefones IP Compatíveis
• Crie Modelos de Telefone Personalizados Com IA

O conteúdo se aplica à Versão: a partir da V20 U8 - Edição: IA, Pro, Basic - Implantação: Hospedado pela 3CX, No local, Auto-hospedado

Última Atualização
Este documento foi atualizado pela última vez em 10 de setembro de 2026
https://www.3cx.com.br/docs/custom-phone-template-configuration/