Add Your Own Phone Brand: Custom Template Guide

3CX, desteklenen telefon üreticileri için yerleşik şablonlarla birlikte gelir. Markanız veya modeliniz bu listede yer almıyorsa, Özel Şablon oluşturarak destek ekleyebilirsiniz. Bu kılavuz, uyarlayabileceğiniz çalışır durumda bir örnek şablon kullanarak süreci adım adım açıklamaktadır.

Özel Bir Şablon Ne Yapar

Şablon, 3CX’e belirli bir telefon modeli için bir provizyon yapılandırmasını nasıl oluşturacağını belirten bir XML dosyasıdır. Bir telefon provizyona girdiğinde, 3CX:

1. Cihaza atanan şablonu yükler.
2. 3CX değişkenlerini (örn. %%extension_number%%) gerçek değerlerle değiştirir.
3. Koşullu blokları değerlendirir (örn. {IF network=SBC}).
4. Ortaya çıkan yapılandırma dosyasını, telefonun aldığı provizyon URL'sine yazar.

Örneği uyarlarken yapmanız gereken, üreticinizin yapılandırma sözdizimini, verileri sağlayan 3CX değişkenleriyle eşleştirmektir.

Ön Koşullar

• 3CX’e yönetici erişimi (Yönetici > Gelişmiş > Şablonlar).
• Üreticinizin provizyon belgeleri; özellikle SIP kimlik bilgileri, kodekler, BLF tuşları, NTP, saat dilimi, VLAN ve telefonunuzun sunduğu diğer tüm özelliklere ilişkin parametre adları; bazı üreticiler teknik belgelerini yalnızca talep üzerine sağlar; çevrimiçi kaynaklar için işte bazı pratik örnekler:

• Yealink Örneği (T57W Yönetici Kılavuzu)
• Snom D Serisi Provizyon Parametreleri

• Telefonun User-Agent dizesi (cihazın SIP REGISTER komutunda veya cihaz PBX ile bağlantı kurduktan sonra 3CX telefon günlüklerinde görülebilir).
• Telefonunuzun beklediği provizyon URL biçimi.

Prosedür

• Yönetici > Gelişmiş > Şablonlar > Telefon Şablonları’na gidin.
• Satıcınızın sözdizimine yakın bir şablon seçin ve Kopya Oluştur düğmesine tıklayın. Kopyaya markanızın adını verin (örn. phonetel-custom.ph).
• Yeni şablonu açın ve içeriğini aşağıdaki Örnek Şablon ile değiştirin.
• <header> bölümünü düzenleyin: şablon adını, model ua (User-Agent), logoyu, kodekleri ve özellikleri cihazınıza uyacak şekilde ayarlayın.
• <deviceconfig> CDATA bölümünü düzenleyin. Her your_*_variable yer tutucusunu, üreticinizin gerçek parametre adıyla değiştirin. Sağ tarafta bulunan %%...%% 3CX değişkenlerini olduğu gibi bırakın — bunlar, provizyon sırasında değiştirilecektir.
• Şablonu kaydedin.
• 3CX'te bir telefon ekleyin ve model sorulduğunda özel şablonunuzu seçin.
• 3CX tarafından sağlanan provizyon URL'sini telefona girin (manuel olarak veya DHCP seçeneği 66 / PNP yoluyla) ve provizyonu başlatın.

Şablon Yapısı

XML'de iki üst düzey bölüm bulunmaktadır.

Başlık Etiketi

<header> etiketi, şablonun meta verilerini ve 3CX’in bu telefon için gösterdiği kullanıcı arayüzü denetimlerini tanımlar:

Blf Türü ve Veri Etiketleri

• <blftype> — her bir BLF işlevi (dahili hat izleme, hat tuşu, hızlı arama, kuyruk girişi, park etme, profil durumu) için tuş biçimlerini tanımlar. Bir yönetici, dahili hat kullanıcı arayüzünde BLF’leri atadığında 3CX bu biçimleri yineler.
• <data><device> — <deviceconfig> CDATA bloğunu sarar. CDATA, 3CX değişkenlerinin gömülü olduğu üreticinizin literal yapılandırma sözdizimini içerir. Farklı modeller ve koşullar için farklı değişkenler sağlamak üzere 3CX tarafından ayrıştırılan IF ifadeleri içerebilir.

3CX Değişkenleri: Hızlı Referans

Bunlar, CDATA bölümü içinde kullanılan en yaygın değişkenlerdir. Değişkenler %%name%% biçiminde yazılır ve kaynak sağlama sırasında yerlerine ilgili değerler konulur.

Kimlik & Provizyon Alma

Dahili / SIP Hesabı

Ağ

Başlık Tarafından Açığa Çıkarılan Seçenekler

<header> içinde tanımlanan <option> değerlerinden geliyor:

Kodekler

BLF / Fonksiyon Tuşları

{IF blfN} bloklarının içinde (burada N, anahtar dizininin indeksidir):

Koşullu Mantık

CDATA bölümü basit koşul ifadelerini destekler. 3CX, yapılandırmayı telefona göndermeden önce bunları değerlendirir.

Ağ Modu

Telefonun PBX’e nasıl bağlandığına bağlı olarak farklı bloklar yayın yapar:

{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 Yuvaları

Her BLF/işlev tuşunun kendine özgü bir koşulu vardır. Blok içinde, BLF bağlam değişkenleri (%%Line%%, %%type%%, %%label%% vb.) bu tuşa atıfta bulunur:

{IF blf1}

  linekey.1.type  = %%DKtype%%

  linekey.1.value = %%type%%

  linekey.1.label = %%label%%

{ELSE}

  linekey.1.type  = 0

{ENDIF}

lf2, blf3, … için bu işlemi, telefonunuzun desteklediği programlanabilir tuş sayısına kadar tekrarlayın.

Sistem Parametreleri

sysparam.NAME aracılığıyla herhangi bir 3CX parametresine başvurabilirsiniz:

{IF sysparam.CUSTOMIZE_QUEUE_RINGTONES=1}

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

{ELSE}

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

{ENDIF}

Test Etme ve Doğrulama

• Şablonu kaydettikten sonra, bir test dahilisi ekleyin ve telefon modeli olarak özel şablonunuzu atayın.
• Telefonu fabrika ayarlarına sıfırlayın (temiz bir test için önerilir).
• Aşağıdakilerden birini kullanarak telefonu provizyon edin:

• Manuel — telefonun provizyon URL’si alanına %%PROVLINK%% (dahilinin IP Telefon sekmesinde görülebilir) girin.
• DHCP Seçeneği 66 — seçeneği PBX provizyon URL'sine yönlendirin.
• PNP / RPS — üretici bunu destekliyorsa ve şablonunuzda <rps>1</rps> ayarlanmışsa.

• 3CX Etkinlik Günlüğünü ve telefonun yerel günlüklerini izleyin. Cihazın yapılandırmayı aldığını ve başarıyla kaydolduğunu doğrulayın.
• Eşleştirdiğiniz her özelliği doğrulayın: kodek sırası, BLF tuşları, zil sesleri, aktarım davranışı, VLAN.

Bir değer yanlış gelirse, oluşturulan yapılandırma dosyasını doğrudan inceleyin — 3CX bu dosyayı %%PROVLINK%%/<mac_address>.cfg adresinde (veya <deviceconfig filename="..."> içinde ayarladığınız dosya adı deseninde) sunar.

Bölümünüzle Saat Diliminizi Otomatik Ayarlama

3CX Global Saat Diliminiz veya özel Bölüm Saat Diliminiz, aşağıdaki örnek tabloda görüldüğü gibi her bölge adına karşılık gelen bir kimliğe sahiptir:

Şablonunuzun <timezoneParams> bölümünde kimlikler (ID’ler) bulunuyorsa, telefonlarınız “Küresel Saat Dilimini Kullan” adlı varsayılan seçeneği kullanabilir. Bu durumda saat dilimini sizin için otomatik olarak eşleştirir ve telefonlarınızı buna göre yapılandırırız; böylece her bir telefon için ayrı ayrı manuel olarak saat dilimi seçmeniz gerekmez.

Bir kimliği manuel olarak ayarlamanız gerekiyorsa, saat dilimi kimliklerinin tam listesini buradaki saat dilimi referans kılavuzunda bulabilirsiniz.

Örnek Şablon

Bu şablonu başlangıç noktası olarak özel şablonunuza kopyalayın; ardından değişken yer tutucularını (aşağıdaki şablon parçasında your_*_variable ve [Example_*] biçiminde görülen) cihazınızın ve üreticinizin gerçek parametreleri ve adlarıyla değiştirin.

Şablon Düzenleme İçin En İyi Uygulamalar:

• Biçim: Ham .ph.xml veya düz metin düzenleyicileri kullanın. Veri bozulmasını önlemek için zengin metin (Word/Docs) formatından kaçının.
• Yapı: <deviceconfig> CDATA bloğunun dışında girintiler dikkate alınmaz.
• CDATA: CDATA bölümü içinde, üretici tarafından gerekli görülen sözdizimini (boşluklar/satır sonları) aynen koruyun.
• Doğrulama: UTF-8 olarak kaydedin, XML'i doğrulayın ve test cihazında görüntülenen yapılandırmaları inceleyin.

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

Sorun Giderme

Sonraki Adımlar

Şablonunuz temiz bir şekilde provizyon aldığında şunları göz önünde bulundurun:

• Kopya Oluştur aracılığıyla yayınlayıp kuruluşunuzdaki diğer yöneticilerle paylaşmak.
• Topluluk tarafından desteklenen bir şablon olarak eklenmesi için 3CX’e göndermek.
• Üreticinizin modelleri aynı yapılandırma şemasını paylaşıyorsa, aynı şablona ek <model> girişleri eklemek.

Ayrıca Bakınız

• IP Telefonları Yapılandırma
• IP Telefon Provizyon Seçenekleri
• Desteklenen IP Telefonlar
• AI ile Özel Telefon Şablonları Oluşturun

İçerik şu sürümler için geçerlidir: V20 U8 ve sonrası - Sürüm: AI, Pro, Basic - Kurulum: 3CX tarafından Barındırılan, Şirket İçinde, Kendi Barındırılan

Son Güncelleme
Bu belge en son 14 Eylül 2026’da güncellendi.
https://www.3cx.com/docs/custom-phone-template-configuration/