View Categories

Panduan Struktur & Deskripsi XML Template CRM 3CX

Admin
Updated on June 30, 2026

6 min read

SPESIFIKASI XML TEMPLATE INTEGRASI CRM 3CX #

  • Dokumen ID: KB-3CX-CRM-XML-01

  • Target Versi: 3CX v18 / v20 (Server-Side Integration)

  • Kategori: Middleware & API Development

1. Pendahuluan & Arsitektur Utama #

3CX menggunakan mesin integrasi berbasis server-side yang mengeksekusi instruksi dari sebuah file konfigurasi XML kustom. Engine ini menangani penanganan pencarian nomor telepon (contact lookup), pencatatan riwayat panggilan (call journaling), pelaporan interaksi pesan (chat journaling), hingga alur otorisasi token yang kompleks (OAuth2).

Engine ini mendukung tiga tipe skenario (Type):

  1. REST: Interaksi via HTTP REST API (mengembalikan data berformat JSON atau XML).

  2. SQLDatabase: Kueri database relasional secara langsung (mendukung MySQL, PostgreSQL, dan Microsoft SQL Server).

  3. NoSQLDatabase: Eksekusi perintah database non-relasional (mendukung MongoDB).

2. Struktur Root Elemen & Atribut Dasar #

Setiap template wajib dibungkus di dalam tag root <Crm> dengan deklarasi atribut sebagai berikut:

XML
 
<Crm Name="Custom_CRM_REST" Version="1" Country="ID" SupportsEmojis="true">
    </Crm>

  • Name: String identitas unik template yang akan ditampilkan pada UI Konsol Admin 3CX.

  • Version: Nilai integer penanda versi skema integrasi (digunakan oleh sistem untuk manajemen pembaruan).

  • Country: Kode negara target aplikasi (bersifat wajib diisi, namun saat ini belum dievaluasi oleh core fungsionalitas).

  • SupportsEmojis: Bernilai boolean (true/false). Jika diset false, karakter emoji pada pesan chat akan otomatis difilter sebelum dikirim ke sistem CRM Anda.

3. Elemen Konfigurasi Komponen Utama #

3.1 Elemen <Number> #

Digunakan untuk menormalisasi format string nomor telepon masuk (caller ID) agar sesuai dengan format indeks pencarian di database CRM.

  • Prefix (Enum): Menentukan perilaku manipulasi awalan nomor:

    • AsIs: Menjaga string asli tanpa modifikasi (contoh: +62 atau 00 tetap utuh).

    • Off: Menghapus semua karakter awalan penanda (seperti simbol + atau digit 00).

    • Plus: Memaksa karakter awalan menggunakan tanda tambah (+).

    • Zeros: Memaksa karakter awalan menggunakan digit nol ganda (00).

  • MaxLength (Expression): Memotong string dari kanan dan hanya mengambil sejumlah $N$ digit terakhir. Nilai ini dapat diset dinamis menggunakan ekspresi variabel [MaxLength] untuk mengambil parameter global dari 3CX Console > Contacts > Options.

3.2 Elemen <Connection> #

Mengonfigurasi batas eksekusi konkurensi engine terhadap server eksternal.

  • MaxConcurrentRequests: Membatasi jumlah maksimal kueri simultan paralel yang diizinkan untuk dikirim ke API CRM (mencegah rate limiting). Satu sesi pencarian panggilan telepon tunggal (meskipun mengeksekusi beberapa skenario lookup paralel untuk Lead, Contact, atau Account) dihitung sebagai satu kesatuan request unit.

3.3 Elemen <Parameters> #

Menampung kumpulan elemen <Parameter> kustom yang nilainya diinput secara dinamis oleh administrator melalui halaman UI Web Console 3CX. Nilai parameter ini dapat dipanggil di bagian mana saja di dalam template dengan format kurung siku: [NamaParameter].

  • Tipe Data Parameter (Type): Mendukung String, Password (input teks tersembunyi), Boolean (checkbox), Integer, Double, DateTime, dan OAuth (memicu tombol interaktif alur otorisasi OAuth2).

  • Atribut Kontrol Editor: Atribut Editor bernilai String (maksimal 100 karakter) atau Sql (maksimal 1000 karakter). Untuk parameter bertipe OAuth, wajib menyertakan atribut RequestUrl, RequestUrlParameters, dan ResponseScenario.

3.4 Elemen <Authentication> #

Mengatur metode injeksi token keamanan pada HTTP Header. Mendukung tiga konfigurasi:

  1. Type="No": Tanpa autentikasi bawaan, digunakan jika CRM menggunakan penanganan token manual di dalam query string URL.

  2. Type="Basic": Menyuntikkan HTTP header Authorization: Basic <base64> otomatis pada setiap request berdasarkan nilai dari anak node <Value>.

  3. Type="Scenario": Digunakan untuk skema token dinamis (seperti OAuth2 Access Token). Opsi ini memicu eksekusi skenario khusus untuk mengambil token segar, mendeteksi masa kedaluwarsa (expiry time), dan menyimpannya di memori runtime state.

4. Penanganan Skenario Berdasarkan Reservasi ID Sistemas #

Atribut Id pada tag <Scenario> mengontrol kapan dan bagaimana sebuah blok instruksi dieksekusi oleh core engine telephony 3CX:

  • Id="" (String Kosong): Skenario default utama untuk mencocokkan kontak berdasarkan nomor telepon masuk (Inbound Call Contact Lookup).

  • Id="LookupByEmail": Dipicu otomatis saat sistem meminta pencarian entitas menggunakan alamat email.

  • Id="SearchContacts": Digunakan untuk fungsionalitas pencarian teks bebas (free text search) lintas kolom data (Nama, Perusahaan, Email, dsb) dari aplikasi klien 3CX.

  • Id="ReportCall": Dieksekusi otomatis seketika saat sesi panggilan telepon berakhir untuk mencatat riwayat log panggilan (Call Journaling).

  • Id="ReportChat": Dieksekusi otomatis ketika sesi interaksi pesan kustom selesai ditangani (Chat Journaling).

  • Id="CreateContactRecordFromClient": Memicu pembuatan baris data kontak baru ke CRM langsung dari tombol aksi di aplikasi klien 3CX.

  • Id="LookupFromCFD_[Entity]_[Type]": Digunakan khusus untuk melempar balikan raw data payload (JSON/XML) langsung ke aplikasi Call Flow Designer (CFD).

⚠️ PENTING UNTUK DEVELOPER (JOURNALING RULES):

Khusus untuk skenario ReportCall dan ReportChat, engine 3CX tidak mengharapkan adanya pengembalian data (output data return). Oleh karena itu, di dalam struktur XML skenario tersebut dilarang keras menyertakan node penutup <Rules>, <Variables>, atau <Outputs>. Cukup deklarasikan elemen interaksi utama seperti <Request>, <Query>, atau <Command>.

5. Pipeline Pengolahan Data Respon (REST) #

Siklus pemrosesan data respon API dalam skenario REST mengikuti 4 tahapan berurutan (sequential pipeline):

  1. <Request>: Mengonstruksi HTTP Request (URL, Method GET/POST/PUT, Headers, dan Request Body).

  2. <Rules>: Memetakan basis awal array objek respon eksternal (Atribut Type="json" menggunakan format penulisan JSONPath, sedangkan Type="xml" menggunakan format XPath). Elemen <Filter> dapat disisipkan di dalamnya untuk menyaring kondisi properti tertentu.

  3. <Variables>: Mengekstrak data nilai properti spesifik dari hasil saringan array untuk dipetakan ke dalam variabel runtime lokal.

    XML
     
    <Variables>
    <Variable Name="ContactID" Path="id" />
    <Variable Name="Company" Path="company.name" />
</Variables>

  4. <Outputs>: Menyerahkan nilai variabel runtime lokal kembali ke core PBX 3CX. Pada skenario contact lookup, properti wajib yang harus dipetakan meliputi: ContactUrl, FirstName, LastName, CompanyName, Email, dan PhoneBusiness.

  • Skenario Berantai (Chained Scenario): Developer dapat memicu skenario lanjutan secara rekursif per baris data dengan menyuntikkan atribut Next pada tag output, misalnya: <Outputs Next="GetContactDetailsByID"/>. Skenario anak otomatis mewarisi seluruh state variabel yang ditangkap pada skenario induknya.

6. Aturan Sintaks Ekspresi & Penulisan Karakter Khusus #

Mesin parsing ekspresi XML 3CX menerapkan aturan ketat terhadap karakter pemesanan sistem. Jika string literal di dalam atribut ekspresi mengandung karakter khusus, Anda wajib melakukan escape dengan ketentuan berikut:

  • Karakter pembuka kurung siku [ wajib diubah menjadi: {{

  • Karakter penutup kurung siku ] wajib diubah menjadi: }}

  • Karakter tanda petik dua " wajib diubah menjadi: ^^

Catatan untuk Pengembang SQL: Khusus penulisan variabel binding di dalam skenario SQLDatabase, pemanggilan nilai variabel dilarang menggunakan format kurung siku [Variable], melainkan wajib menggunakan awalan parameter terikat native SQL yaitu simbol @ (Contoh: WHERE phone = @NumberToLookup).

7. Alur Pengujian & Debugging Kode #

Layanan utama 3CX System Service bertanggung jawab memuat seluruh file skema XML ke dalam memori RAM saat proses booting awal pbx dimulai. Akibatnya, setiap kali developer melakukan perubahan baris kode di dalam file XML template, 3CX System Service wajib direstart secara penuh agar perubahan skema terbaca.

Untuk menguji fungsionalitas integrasi tanpa melakukan panggilan fisik (dummy testing execution), gunakan fungsionalitas tombol interaktif “Test” yang terletak pada halaman manajemen web admin: 3CX Admin Console > Settings > CRM Integration.

Baca juga : Call Center Hospitality untuk Layanan Tamu Multi-Negara dengan 3CX, CRM & AI Agent