---
title: "Panduan Struktur & Deskripsi XML Template CRM 3CX"
description: "# SPESIFIKASI XML TEMPLATE INTEGRASI CRM 3CX - **Dokumen ID:** `KB-3CX-CRM-XML-01` - **Target Versi:** [3CX v18 / v20](https://www.3cx.com/blog/releases/u9-web-client-smarter-ai/)(Server-Side Integration) - **Kategori:** Middleware & API Development ### 1. Pendahuluan & Arsitektur Utama 3CX menggunakan mesin integrasi berbasis *server-side* yang mengeksekusi instruksi…"
url: "https://solusipbx.id/pusat-bantuan/panduan-struktur-deskripsi-xml-template-crm-3cx/"
updated: "2026-06-30"
category: Developer
---

# Panduan Struktur & Deskripsi XML Template CRM 3CX

# SPESIFIKASI XML TEMPLATE INTEGRASI CRM 3CX

- **Dokumen ID:** `KB-3CX-CRM-XML-01`
- **Target Versi:** [3CX v18 / v20](https://www.3cx.com/blog/releases/u9-web-client-smarter-ai/)(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](https://solusipbx.com/call-center-hospitality/)