Aggiungi la tua marca di telefono: guida ai templa

3CX include modelli predefiniti per i produttori di telefoni supportati. Se la tua marca o il tuo modello non sono presenti nell’elenco, puoi aggiungere il supporto creando un template personalizzato. Questa guida illustra la procedura utilizzando un template di esempio funzionante che puoi adattare alle tue esigenze.

Cosa fa un template personalizzato

Un template è un file XML che indica a 3CX come generare una configurazione di provisioning per uno specifico modello di telefono. Quando un telefono viene configurato, 3CX:

1. Carica il template assegnato al dispositivo.
2. Sostituisce le variabili 3CX (ad es. %%extension_number%%) con valori reali.
3. Valuta i blocchi condizionali (ad es. {IF network=SBC}).
4. Scrive il file di configurazione risultante all’URL di provisioning da cui il telefono preleva i dati.

Il tuo compito nell’adattare l’esempio è quello di mappare la sintassi di configurazione del tuo fornitore alle variabili 3CX che forniscono i dati.

Prerequisiti

• Accedi come amministratore a 3CX (Admin > Avanzate > Template).
• La documentazione di provisioning del proprio fornitore, in particolare i nomi dei parametri relativi a credenziali SIP, codec, tasti BLF, NTP, fuso orario, VLAN e qualsiasi funzionalità supportata dal proprio telefono; alcuni fornitori forniscono la documentazione tecnica solo su richiesta; per quanto riguarda le risorse online, ecco alcuni esempi pratici:

• Esempio Yealink (Guida amministrativa T57W)
• Parametri di configurazione della serie D di Snom

• La stringa User-Agent del telefono (visibile nel comando SIP REGISTER del dispositivo o nei log del telefono 3CX una volta che il dispositivo si connette al centralino).
• Il formato dell’URL di configurazione richiesto dal telefono.

Procedura

• Vai su Admin > Avanzate > Template > Template telefono.
• Seleziona un modello che rispecchi la sintassi del proprio fornitore e clicca su Crea copia. Assegnare alla copia un nome che rifletta il proprio marchio (ad es. phonetel-custom.ph).
• Apri il nuovo template e sostituisci il contenuto con il template di esempio riportato di seguito.
• Modifica la sezione <header>: imposta il nome del template, l’ua del modello (User-Agent), il logo, i codec e le funzionalità in modo che corrispondano al proprio dispositivo.
• Modifica la sezione CDATA <deviceconfig>. Sostituisci ogni segnaposto your_*_variable con il nome effettivo del parametro del tuo fornitore. Mantieni le variabili 3CX %%...%% sul lato destro: queste verranno sostituite al momento del provisioning.
• Salva il template.
• Aggiungi un telefono in 3CX e seleziona il tuo template personalizzato quando ti viene richiesto il modello.
• Inserisci l’URL di provisioning fornito da 3CX nel telefono (manualmente o tramite l’opzione DHCP 66 / PNP) e avvia il provisioning.

Struttura del template

Il file XML presenta due sezioni di primo livello.

Tag di intestazione

Il tag <header> dichiara i metadati del modello e i controlli dell’interfaccia utente che 3CX mostra per questo telefono:

BlfType e tag dati

• <blftype>: Definisce i formati dei tasti per ciascuna funzione BLF (monitor interni, tasti di linea, composizione rapida, accesso alla coda, parcheggio, stato del profilo). 3CX li genera automaticamente quando un amministratore assegna i BLF nell’interfaccia utente degli interni.
• <data><device>: Racchiude il blocco CDATA <deviceconfig>. Il CDATA contiene la sintassi di configurazione letterale del proprio fornitore con variabili 3CX incorporate. Può contenere istruzioni IF che 3CX analizza per fornire variabili diverse a seconda dei modelli e delle condizioni.

Variabili 3CX: Guida rapida

Queste sono le variabili più comuni utilizzate all’interno della sezione CDATA. Le variabili sono scritte come %%nome%% e vengono sostituite al momento del provisioning.

Identità e configurazione

Estensione / Account SIP

Rete

Opzioni disponibili nell'intestazione

Queste derivano dai valori <option> definiti in <header>:

Codecs

BLF / Tasti funzione

All'interno dei blocchi {IF blfN} (dove N è l'indice della chiave):

Logica condizionale

La sezione CDATA supporta semplici condizioni. 3CX le valuta prima di inviare la configurazione al telefono.

Modalità di rete

Vengono emessi blocchi diversi a seconda di come il telefono si collega al centralino:

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

Tasti BLF

Ogni tasto BLF/funzionale ha una propria condizione. All'interno del blocco, le variabili di contesto BLF (%%Line%%, %%type%%, %%label%%, ecc.) si riferiscono a quel tasto:

{IF blf1}

  linekey.1.type  = %%DKtype%%

  linekey.1.value = %%type%%

  linekey.1.label = %%label%%

{ELSE}

  linekey.1.type  = 0

{ENDIF}

Ripeti l'operazione per blf2, blf3, … fino al numero massimo di tasti programmabili supportati dal tuo telefono.

Parametri di sistema

È possibile fare riferimento a qualsiasi parametro di sistema 3CX tramite sysparam.NAME:

{IF sysparam.CUSTOMIZE_QUEUE_RINGTONES=1}

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

{ELSE}

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

{ENDIF}

Test e verifica

• Dopo aver salvato il template, aggiungi un'estensione di prova e assegna il tuo template personalizzato come template del telefono.
• Ripristina le impostazioni di fabbrica del telefono (consigliato per un test senza interferenze).
• Configura il telefono utilizzando una delle seguenti opzioni:

• Manuale: Inserisci %%PROVLINK%% (visibile nella scheda “IP Phone” dell'estensione) nel campo URL di configurazione del telefono.
• Opzione DHCP 66: Indirizza l’opzione all’URL di configurazione del centralino.
• PNP / RPS: Se il produttore lo supporta e nel template è impostato <rps>1</rps>.

• Controlla il registro attività di 3CX e i registri locali del telefono. Verifica che il dispositivo recuperi la configurazione e si registri correttamente.
• Verifica ogni funzionalità che hai mappato: ordine dei codec, tasti BLF, suonerie, comportamento dei trasferimenti, VLAN.

Se un valore risulta errato, controlla direttamente il file di configurazione generato — 3CX lo rende disponibile all’indirizzo %%PROVLINK%%/<mac_address>.cfg (o secondo il modello di nome file che hai impostato in <deviceconfig filename="...">).

Imposta automaticamente il fuso orario in base al tuo dipartimento

Il fuso orario globale 3CX o il fuso orario personalizzato del tuo dipartimento ha un ID corrispondente al nome della regione, come illustrato nella tabella di esempio qui sotto:

Se il tuo modello contiene gli ID nel tag <timezoneParams>, i tuoi telefoni potranno utilizzare l’opzione predefinita Usa fuso orario globale. Provvederemo quindi automaticamente ad abbinare il fuso orario per te e a configurare i tuoi telefoni di conseguenza, così non dovrai selezionare manualmente un fuso orario per ogni singolo telefono.

Se devi impostare manualmente un ID, trova l’elenco completo degli ID dei fusi orari nella guida di riferimento sui fusi orari qui.

Template di esempio

Copia questo template nel tuo template personalizzato come punto di partenza, quindi sostituisci i segnaposto delle variabili (visibili nel frammento di template qui sotto nel formato your_*_variable e [Example_*]) con i parametri e i nomi effettivi del tuo dispositivo e del tuo fornitore.

Migliori pratiche per la modifica dei modelli:

• Formato: Utilizza editor .ph.xml o di testo semplice. Evita il testo formattato (Word/Docs) per prevenire il danneggiamento dei dati.
• Struttura: Al di fuori del blocco CDATA <deviceconfig>, l’indentazione viene ignorata.
• CDATA: All’interno della sezione CDATA, mantieni esattamente la sintassi richiesta dal fornitore (spazi/interruzioni).
• Convalida: Salva in formato UTF-8, convalida l’XML e verifica le configurazioni visualizzate su un dispositivo di prova.

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

Risoluzione dei problemi

Prossimi passi

Una volta che il template è stato configurato correttamente, valuta di:

• Pubblicarlo tramite Crea copia e condividerlo con altri amministratori della tua organizzazione;
• Inviarlo a 3CX affinché venga incluso come template supportato dalla comunità.
• Aggiungere ulteriori voci <model> allo stesso template se i modelli del proprio fornitore condividono uno schema di configurazione.

Per saperne di più

• Configurazione dei telefoni IP
• Opzioni di configurazione dei telefoni IP
• Telefoni IP supportati
• Creazione di modelli di telefono personalizzati con AI

Il contenuto si applica alla versione: da V20 U8 - Edizione: AI, Pro, Basic - Implementazione: HostedBy3CX, OnPremises, SelfHosted

Ultimo aggiornamento
Questo documento è stato aggiornato il 14 settembre 2026
https://www.3cx.it/doc/custom-phone-template-configuration/