Szablony niestandardowe: Własna marka telefonu

System 3CX jest dostarczany z wbudowanymi szablonami dla obsługiwanych producentów telefonów. Jeśli Twoja marka lub model nie znajduje się na tej liście, możesz dodać jej obsługę, tworząc szablon niestandardowy (Custom Template). Niniejszy przewodnik przeprowadzi Cię przez ten proces przy użyciu gotowego, przykładowego szablonu, który możesz dostosować do własnych potrzeb.

Co robi szablon niestandardowy

Szablon to plik XML, który instruuje system 3CX, jak wygenerować plik autokonfiguracji (provisioning) dla konkretnego modelu telefonu. Podczas procesu autokonfiguracji system 3CX:

1. Wczytuje szablon przypisany do urządzenia.
2. Zastępuje zmienne 3CX (np.  %%extension_number%%) rzeczywistymi wartościami.
3. Przetwarza bloki warunkowe (np. {IF network=SBC}).
4. Zapisuje wygenerowany plik konfiguracyjny pod adresem URL autokonfiguracji, z którego pobiera go telefon.

Twoim zadaniem przy dostosowywaniu szablonu jest zmapowanie składni konfiguracyjnej danego producenta na zmienne 3CX dostarczające odpowiednie dane.

Wymagania wstępne

• Dostęp administratora do systemu 3CX („Admin” > „Advanced” > „Templates”).
• Dokumentacja autokonfiguracji wydana przez producenta sprzętu, a w szczególności nazwy parametrów dla danych uwierzytelniających SIP, kodeków, przycisków BLF, NTP, strefy czasowej, VLAN oraz wszelkich innych funkcji oferowanych przez dany telefon. Niektórzy producenci udostępniają dokumentację techniczną wyłącznie na zamówienie; oto praktyczne przykłady dostępne online:

• Przykład Yealink (Yealink T57W Admin Guide)
• Parametry autokonfiguracji dla serii Snom D

• Ciąg User-Agent telefonu (widoczny w komunikatach SIP REGISTER urządzenia lub w dziennikach telefonu 3CX, gdy urządzenie połączy się z centralą PBX).
• Format adresu URL autokonfiguracji wymagany przez dany telefon.

Procedura

• Przejdź do „Admin” > „Advanced” (Zaawansowane) > „Templates” (Szablony) > „Phone Templates” (Szablony telefonów).
• Wybierz szablon zbliżony składnią do rozwiązań Twojego producenta i kliknij „Create Copy” (Utwórz kopię). Nazwij kopię według swojej marki (np. phonetel-custom.ph).
• Otwórz nowy szablon i zastąp jego zawartość poniższym przykładowym szablonem.
• Edytuj sekcję <header>: ustaw nazwę szablonu, parametry modelu ua (User-Agent), logo, kodeki oraz możliwości urządzenia dostosowane do Twojego telefonu.
• Edytuj sekcję CDATA znacznika <deviceconfig>. Zastąp każdy zastępczy parametr your_*_variable rzeczywistą nazwą parametru używaną przez Twojego producenta. Zachowuj zmienne 3CX w formacie %%...%% po prawej stronie — zostaną one zastąpione właściwymi wartościami podczas autokonfiguracji.
• Zapisz szablon.
• Dodaj telefon w systemie 3CX i wybierz swój szablon niestandardowy, gdy system poprosi o wybór modelu.
• Wprowadź adres URL autokonfiguracji dostarczony przez 3CX w telefonie (ręcznie lub przez opcję DHCP 66 / PNP) i uruchom proces autokonfiguracji.

Struktura szablonu

Plik XML składa się z dwóch głównych sekcji najwyższego poziomu.

Znacznik Header

Znacznik <header> deklaruje metadane szablonu oraz elementy sterujące interfejsu użytkownika, które 3CX wyświetla dla tego telefonu:

Znaczniki BlfType i Data

• <blftype> — definiuje formaty klawiszy dla każdej funkcji BLF (monitorowanie numeru wewnętrznego, klawisz linii, szybkie wybieranie, logowanie do kolejki, parkowanie, status profilu). System 3CX iteruje po nich, gdy administrator przypisuje przyciski BLF w interfejsie numeru wewnętrznego.
• <data><device> — otacza blok CDATA znacznika <deviceconfig>. Blok CDATA zawiera dosłowną składnię konfiguracyjną producenta ze wstawionymi zmiennymi 3CX. Może zawierać instrukcje warunkowe IF, które 3CX przetwarza, dostarczając różne zmienne dla różnych modeli i warunków.

Zmienne 3CX: Szybka ściąga

Są to najczęściej używane zmienne wewnątrz sekcji CDATA. Zmienne są zapisywane w formacie %%name%% i są zastępowane właściwymi wartościami podczas autokonfiguracji.

Tożsamość i autokonfiguracja (provisioning)

Numer wewnętrzny / Konto SIP

Sieć

Opcje udostępniane przez sekcję Header

Wartości te pochodzą ze znaczników <option> zdefiniowanych w sekcji <header>:

Kodeki

BLF / Przyciski funkcyjne

Wewnątrz bloków {IF blfN} (gdzie N oznacza indeks klawisza):

Logika warunkowa

Sekcja CDATA obsługuje proste instrukcje warunkowe. System 3CX przetwarza je przed wysłaniem konfiguracji do telefonu.

Tryb sieciowy

W zależności od tego, jak telefon łączy się z centralą PBX, generowane są różne bloki:

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

Sloty BLF

Każdy przycisk BLF/funkcyjny posiada własny warunek. Wewnątrz bloku zmienne kontekstowe BLF (%%Line%%, %%type%%, %%label%% itp.) odnoszą się do tego konkretnego klawisza:

{IF blf1}

  linekey.1.type  = %%DKtype%%

  linekey.1.value = %%type%%

  linekey.1.label = %%label%%

{ELSE}

  linekey.1.type  = 0

{ENDIF}

Powtórz tę strukturę dla blf2, blf3, … aż do maksymalnej liczby programowalnych klawiszy obsługiwanych przez Twój telefon.

Parametry systemowe

Możesz odwołać się do dowolnego parametru systemowego 3CX poprzez sysparam.NAME:

{IF sysparam.CUSTOMIZE_QUEUE_RINGTONES=1}

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

{ELSE}

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

{ENDIF}

Testowanie i weryfikacja

• Po zapisaniu szablonu dodaj testowy numer wewnętrzny i przypisz swój niestandardowy szablon jako model telefonu.
• Przywróć telefon do ustawień fabrycznych (zalecane dla czystego testu).
• Przeprowadź autokonfigurację (provisioning) telefonu za pomocą jednej z metod:

• Ręcznie — wprowadź %%PROVLINK%% (widoczny w zakładce „IP Phone” numeru wewnętrznego) w polu adresu URL autokonfiguracji telefonu.
• Opcja DHCP 66 — wskaż adres URL autokonfiguracji centrali PBX.
• PNP / RPS — jeśli producent to obsługuje i w Twoim szablonie ustawiono <rps>1</rps>.

• Obserwuj Dziennik aktywności 3CX (Activity Log) oraz lokalne dzienniki telefonu. Potwierdź, że urządzenie pobiera konfigurację i pomyślnie się rejestruje.
• Zweryfikuj każdą zamapowaną funkcję: kolejność kodeków, przyciski BLF, dzwonki, zachowanie przy transferze, VLAN.

Jeśli jakaś wartość jest nieprawidłowa, przejrzyj wygenerowany plik konfiguracyjny bezpośrednio — system 3CX udostępnia go pod adresem %%PROVLINK%%/<mac_address>.cfg (lub według wzorca nazwy pliku ustawionego w znaczniku <deviceconfig filename="...">).

Automatyczne ustawianie strefy czasowej zgodnie z Twoim działem

Globalna strefa czasowa 3CX lub niestandardowa strefa czasowa działu posiada odpowiadający jej identyfikator (ID) dla każdej nazwy regionu, jak pokazano w poniższej tabeli przykładowej:

Jeśli Twój szablon zawiera te identyfikatory w sekcji <timezoneParams>, telefony będą mogły korzystać z domyślnej opcji „Use Global Time Zone” (Użyj globalnej strefy czasowej). System automatycznie dopasuje strefę czasową i skonfiguruje telefony, dzięki czemu nie musisz ręcznie wybierać strefy czasowej dla każdego telefonu z osobna.

Jeśli musisz ręcznie ustawić identyfikator, pełną listę identyfikatorów stref czasowych znajdziesz w dokumentacji referencyjnej stref czasowych.

Przykładowy szablon

Skopiuj poniższy szablon do swojego szablonu niestandardowego jako punkt startowy, a następnie zastąp zastępcze parametry zmiennych (widoczne w poniższym fragmencie w formacie your_*_variable oraz [Example_*]) rzeczywistymi parametrami i nazwami Twojego urządzenia i producenta.

Dobre praktyki edycji szablonu:

• Format: Używaj surowych plików .ph.xml lub edytorów tekstu niesformatowanego. Unikaj edytorów tekstu sformatowanego (Word/Docs), aby zapobiec uszkodzeniu struktury.
• Struktura: Poza blokiem CDATA znacznika <deviceconfig> wcięcia są ignorowane.
• CDATA: Wewnątrz sekcji CDATA zachowaj dokładną składnię wymaganą przez producenta (odstępy i znaki nowej linii).
• Walidacja: Zapisuj plik w kodowaniu UTF-8, zweryfikuj poprawność XML i przeanalizuj wygenerowaną konfigurację na urządzeniu testowym.

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

Rozwiązywanie problemów

Kolejne kroki

Gdy Twój szablon poprawnie konfiguruje telefony, rozważ:

• Opublikowanie go za pomocą opcji „Create Copy” i udostępnienie go innym administratorom w Twojej organizacji.
• Przesłanie go do firmy 3CX w celu włączenia jako szablonu wspieranego przez społeczność.
• Dodanie kolejnych wpisów <model> do tego samego szablonu, jeśli modele Twojego producenta dzielą wspólny schemat konfiguracji.

Zobacz także

• Konfigurowanie telefonów IP
• Opcje autokonfiguracji (provisioning) telefonów IP
• Obsługiwane telefony IP
• Tworzenie niestandardowych szablonów telefonów za pomocą AI

Treść dotyczy wersji: od V20 U8 – Edycja: AI, Pro, Basic – Wdrożenie: Hosted By 3CX, On Premise, Self Hosted

Ostatnia aktualizacja
Ten dokument został ostatnio zaktualizowany 10 września 2026 r.
https://www.3cx.pl/docs/custom-phone-template-configuration/