Eigenen Telefonhersteller hinzufügen: Anleitung für benutzerdefinierte Vorlagen

3CX wird mit integrierten Vorlagen für unterstützte Telefonhersteller ausgeliefert. Wenn Ihre Marke oder Ihr Modell nicht auf dieser Liste steht, können Sie Unterstützung hinzufügen, indem Sie eine benutzerdefinierte Vorlage erstellen. Diese Anleitung führt Sie durch den Prozess anhand einer funktionsfähigen Beispielvorlage, die Sie anpassen können.

Was eine benutzerdefinierte Vorlage bewirkt

Eine Vorlage ist eine XML-Datei, die 3CX mitteilt, wie eine Bereitstellungskonfiguration für ein bestimmtes Telefonmodell generiert werden soll. Wenn ein Telefon bereitgestellt wird, führt 3CX Folgendes aus:

1. Lädt die dem Gerät zugewiesene Vorlage.
2. Ersetzt 3CX-Variablen (z. B. %%extension_number%%) durch reale Werte.
3. Wertet bedingte Blöcke aus (z. B. {IF network=SBC}).
4. Schreibt die resultierende Konfigurationsdatei an die Bereitstellungs-URL, die das Telefon abruft.

Ihre Aufgabe bei der Anpassung des Beispiels besteht darin, die Konfigurationssyntax Ihres Herstellers den 3CX-Variablen zuzuordnen, die die Daten liefern.

Voraussetzungen

• Admin-Zugriff auf 3CX (Admin > Erweitert > Vorlagen).
• Die Bereitstellungsdokumentation Ihres Herstellers, insbesondere die Parameternamen für SIP-Zugangsdaten, Codecs, BLF-Tasten, NTP, Zeitzone, VLAN und alle Funktionen, die Ihr Telefon bietet; einige Hersteller stellen ihre technische Dokumentation nur auf Anfrage zur Verfügung; für Online-Ressourcen finden Sie hier einige praktische Beispiele:

• Yealink-Beispiel (T57W Admin-Handbuch)
• Bereitstellungsparameter der Snom D-Serie

• Der User-Agent-String des Telefons (sichtbar im SIP REGISTER des Geräts oder in den 3CX-Telefonprotokollen, sobald das Gerät die PBX kontaktiert).
• Das vom Telefon erwartete Format der Bereitstellungs-URL.

Vorgehensweise

• Gehen Sie zu Admin > Erweitert > Vorlagen > Telefonvorlagen.
• Wählen Sie eine Vorlage aus, die der Syntax Ihres Herstellers nahekommt, und klicken Sie auf Kopie erstellen. Benennen Sie die Kopie nach Ihrer Marke (z. B. phonetel-custom.ph).
• Öffnen Sie die neue Vorlage und ersetzen Sie deren Inhalt durch die nachstehende Beispielvorlage.
• Bearbeiten Sie den Abschnitt <header>: Legen Sie den Vorlagennamen, die Modell-ua (User-Agent), das Logo, die Codecs und die Funktionen passend zu Ihrem Gerät fest.
• Bearbeiten Sie den CDATA-Abschnitt <deviceconfig>. Ersetzen Sie jeden Platzhalter your_*_variable durch den tatsächlichen Parameternamen Ihres Herstellers. Belassen Sie die 3CX-Variablen %%...%% auf der rechten Seite — diese werden bei der Bereitstellung ersetzt.
• Speichern Sie die Vorlage.
• Fügen Sie ein Telefon in 3CX hinzu und wählen Sie Ihre benutzerdefinierte Vorlage aus, wenn Sie nach dem Modell gefragt werden.
• Geben Sie die von 3CX bereitgestellte Bereitstellungs-URL im Telefon ein (manuell oder über DHCP-Option 66 / PNP) und lösen Sie die Bereitstellung aus.

Struktur der Vorlage

Die XML besteht aus zwei Hauptabschnitten auf oberster Ebene.

Header-Tag

Das <header>-Tag deklariert die Vorlagenmetadaten und die Benutzeroberflächen-Steuerelemente, die 3CX für dieses Telefon anzeigt:

BlfType- und Data-Tags

• <blftype> — definiert die Tastenformate für jede BLF-Funktion (Nebenstellenüberwachung, Leitungstaste, Kurzwahl, Warteschleifen-Anmeldung, Parken, Profilstatus). 3CX durchläuft diese, wenn ein Admin BLFs in der Nebenstellen-UI zuweist.
• <data><device> — umschließt den CDATA-Block <deviceconfig>. Die CDATA enthält die wörtliche Konfigurationssyntax Ihres Herstellers mit eingebetteten 3CX-Variablen. Sie kann IF-Anweisungen enthalten, die 3CX auswertet, um unterschiedliche Variablen für verschiedene Modelle und Bedingungen bereitzustellen.

3CX-Variablen: Kurzreferenz

Dies sind die gebräuchlichsten Variablen im CDATA-Abschnitt. Variablen werden als %%name%% geschrieben und zum Zeitpunkt der Bereitstellung ersetzt.

Identität & Bereitstellung

Nebenstelle / SIP-Konto

Netzwerk

Optionen aus dem Header

Diese stammen aus den <option>-Werten, die Sie im <header> definiert haben:

Codecs

BLF / Funktionstasten

Innerhalb von {IF blfN}-Blöcken (wobei N der Tastenindex ist):

Konditionale Logik

Der CDATA-Abschnitt unterstützt einfache Bedingungen. 3CX wertet diese aus, bevor die Konfiguration an das Telefon gesendet wird.

Netzwerkmodus

Je nachdem, wie das Telefon die PBX erreicht, werden unterschiedliche Blöcke ausgegeben:

{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-Plätze

Jede BLF-/Funktionstaste hat ihre eigene Bedingung. Innerhalb des Blocks beziehen sich die BLF-Kontextvariablen (%%Line%%, %%type%%, %%label%% usw.) auf diese Taste:

{IF blf1}

  linekey.1.type  = %%DKtype%%

  linekey.1.value = %%type%%

  linekey.1.label = %%label%%

{ELSE}

  linekey.1.type  = 0

{ENDIF}

Wiederholen Sie dies für blf2, blf3, … bis zur Anzahl der programmierbaren Tasten, die Ihr Telefon unterstützt.

Systemparameter

Referenzieren Sie jeden 3CX-Systemparameter über sysparam.NAME:

{IF sysparam.CUSTOMIZE_QUEUE_RINGTONES=1}

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

{ELSE}

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

{ENDIF}

Testen und Verifizieren

• Nach dem Speichern der Vorlage fügen Sie eine Test-Nebenstelle hinzu und weisen Ihre benutzerdefinierte Vorlage als Telefonmodell zu.
• Setzen Sie das Telefon auf Werkseinstellungen zurück (empfohlen für einen sauberen Test).
• Richten Sie das Telefon mit einer der folgenden Methoden ein:

• Manuell — geben Sie %%PROVLINK%% (sichtbar im Reiter IP-Telefon der Nebenstelle) in das Feld für die Bereitstellungs-URL des Telefons ein.
• DHCP-Option 66 — weisen Sie die Option auf die PBX-Bereitstellungs-URL hin.
• PNP / RPS — wenn der Hersteller dies unterstützt und <rps>1</rps> in Ihrer Vorlage festgelegt ist.

• Beobachten Sie das 3CX-Aktivitätsprotokoll und die lokalen Protokolle des Telefons. Bestätigen Sie, dass das Gerät die Konfiguration abruft und sich erfolgreich registriert.
• Überprüfen Sie jede von Ihnen zugewiesene Funktion: Codec-Reihenfolge, BLF-Tasten, Klingeltöne, Vermittlungsverhalten, VLAN.

Wenn ein Wert falsch ankommt, prüfen Sie die erzeugte Konfigurationsdatei direkt — 3CX stellt sie unter %%PROVLINK%%/<mac_address>.cfg bereit (oder unter dem Dateinamenmuster, das Sie in <deviceconfig filename="..."> festgelegt haben).

Zeitzone automatisch mit Ihrer Abteilung festlegen

Ihre globale 3CX-Zeitzone oder Ihre benutzerdefinierte Abteilungs-Zeitzone hat eine entsprechende ID pro Region, wie in der folgenden Beispiel-Tabelle zu sehen ist:

Wenn Ihre Vorlage die IDs in ihren <timezoneParams> enthält, können Ihre Telefone die Standardoption „Globale Zeitzone verwenden“ nutzen. Wir ordnen die Zeitzone dann automatisch für Sie zu und stellen Ihre Telefone entsprechend bereit, sodass Sie nicht für jedes Telefon individuell eine Zeitzone manuell auswählen müssen.

Wenn Sie eine ID manuell festlegen müssen, finden Sie die vollständige Liste der Zeitzonen-IDs in der Zeitzonen-Referenzanleitung hier.

Beispielvorlage

Kopieren Sie diese Vorlage als Ausgangspunkt in Ihre benutzerdefinierte Vorlage und ersetzen Sie dann die Variablen-Platzhalter (im folgenden Vorlagenausschnitt im Format your_*_variable und [Example_*]) durch die tatsächlichen Parameter und Namen Ihres Geräts und Herstellers.

Bewährte Verfahren für die Vorlagenbearbeitung:

• Format: Verwenden Sie reine .ph.xml- oder Nur-Text-Editoren. Vermeiden Sie Rich-Text (Word/Docs), um Beschädigungen zu verhindern.
• Struktur: Außerhalb des CDATA-Blocks <deviceconfig> wird die Einrückung ignoriert.
• CDATA: Behalten Sie innerhalb des CDATA-Abschnitts die genaue vom Hersteller geforderte Syntax bei (Leerzeichen/Zeilenumbrüche).
• Validierung: Speichern Sie als UTF-8, validieren Sie das XML und überprüfen Sie erzeugte Konfigurationen auf einem Testgerät.

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

Fehlerbehebung

Nächste Schritte

Sobald Ihre Vorlage einwandfrei bereitstellt, können Sie Folgendes in Erwägung ziehen:

• Veröffentlichen über Kopie erstellen und Teilen mit anderen Admins in Ihrer Organisation.
• Einreichen bei 3CX zur Aufnahme als von der Community unterstützte Vorlage.
• Hinzufügen weiterer <model>-Einträge zu derselben Vorlage, wenn die Modelle Ihres Herstellers dasselbe Konfigurationsschema teilen.

Siehe auch

• IP-Telefone konfigurieren
• IP-Telefon-Bereitstellungsoptionen 
• Unterstützte IP-Telefone
• Benutzerdefinierte Telefonvorlagen mit KI erstellen 

Inhalt gilt für Version: Ab V20 U8 - Edition: AI, Pro, Basic - Bereitstellung: HostedBy3CX, OnPremises, SelfHosted

Letztes Update
Dieses Dokument wurde zuletzt am 11. September 2026 aktualisiert
https://www.3cx.de/docs/custom-phone-template-configuration/