Panduan Endpoint REST API XAPI untuk Konfigurasi 3CX

Updated on July 9, 2026

5 min read

Dokumentasi ini memberikan panduan lengkap mengenai spesifikasi endpoint REST API untuk konfigurasi sistem PBX 3CX. API ini memungkinkan Anda untuk mengelola otentikasi, departemen, pengguna, sistem ekstensi, dan pengecekan versi sistem secara terprogram.

🔗 Base URL & Environment #

Semua permintaan API ditujukan ke FQDN (Fully Qualified Domain Name) dari instance 3CX Anda:

https://{{PBX_FQDN}}

📑 Daftar Isi (Table of Contents) #

Authentication / Authorization
Departemetns Management
Users Management
System & Utilities
Active Calls
Reports & Call History
Trunk & Routing
Phonebok & Contact
System Settings & Utility
Event Logs

1. Authentication / Authorization #

Endpoint: Get Token #

Mengimplementasikan otentikasi dan memberikan access_token berdasarkan peran (role) yang sesuai.

HTTP Method: POST
URL Endpoint: https://{{PBX_FQDN}}/connect/token
Authentication: Wajib (Basic Authentication)
Content-Type: application/x-www-form-urlencoded

Request Body #

Parameter	Tipe	Keterangan
`client_id`	String (Required)	Nilai tetap: `server_principal_id`.
`client_secret`	String (Required)	Kunci rahasia (secret key) yang didapatkan setelah mengatur Service Principal.
`grant_type`	String (Required)	Nilai tetap: `client_credentials`.

Response Contoh (200 OK) #

JSON

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "ACCESS_TOKEN",
  "refresh_token": null
}
}

Error Response (401 Unauthorized) #

JSON

{
  "error": "unauthorized",
  "error_description": "The request requires valid user authentication."
}

💡 Tip BetterDocs: access_token ini berlaku selama 3600 detik (1 jam). Anda wajib melakukan otentikasi ulang setelah token kedaluwarsa.

2. Departments Management #

Endpoint: Check if Department Exists #

Memeriksa apakah departemen dengan nama tertentu sudah terdaftar di sistem 3CX untuk menghindari duplikasi sebelum membuat baru.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq '{Nama_Departemen}'
Contoh URL: https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq '3CX Test'

Response Contoh – Jika Departemen Ditemukan (200 OK) #

JSON

{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
  "value": [
    {
      "Name": "DEFAULT",
      "IsDefault": true,
      "HasMembers": true,
      "Number": "GRP0000",
      "Id": 28
    }
  ]
}

Endpoint: Create a Department #

Membuat departemen baru di dalam sistem 3CX dengan konfigurasi bahasa, zona waktu, dan batas nomor layanan panggilan.

HTTP Method: POST
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups
Content-Type: application/json

Request Body Contoh #

JSON

{
  "AllowCallService": true,
  "Id": 0,
  "Language": "EN",
  "Name": "3CX Test",
  "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7",
  "Props": {
    "LiveChatMaxCount": 20,
    "PersonalContactsMaxCount": 500,
    "PromptsMaxCount": 10,
    "SystemNumberFrom": "300",
    "SystemNumberTo": "319",
    "TrunkNumberFrom": "340",
    "TrunkNumberTo": "345",
    "UserNumberFrom": "320",
    "UserNumberTo": "339"
  },
  "TimeZoneId": "51",
  "DisableCustomPrompt": true
}

Response Contoh (201 Created) #

Membawa header Location yang berisi URL ke entitas departemen yang baru dibuat.

JSON

{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups/$entity",
  "Name": "3CX Test",
  "Id": 35,
  "Language": "EN",
  "Props": {
    "LiveChatMaxCount": 20,
    "PersonalContactsMaxCount": 500,
    "PromptsMaxCount": 10
  },
  "TimeZoneId": "51"
}

Error Response – Nama Duplikat (400 Bad Request) #

JSON

{
  "error": {
    "message": "Name:\nWARNINGS.XAPI.DUPLICATE",
    "details": [
      {
        "target": "Name",
        "message": "WARNINGS.XAPI.DUPLICATE"
      }
    ]
  }
}

Endpoint: Update Department Details #

Mengubah properti atau detail pengaturan dari departemen yang sudah ada.

HTTP Method: PATCH
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups({Id_Departemen})
Contoh URL: https://{{PBX_FQDN}}/xapi/v1/Groups(123)

Request Body Contoh #

JSON

{
  "Id": 123,
  "Name": "3CX Test Modif",
  "Props": {
    "LiveChatMaxCount": 25,
    "PersonalContactsMaxCount": 600
  }
}

Response Sukses: 204 No Content (Tanpa body respon).

Endpoint: Delete a Department #

Menghapus departemen dari sistem 3CX secara permanen berdasarkan ID yang ditentukan.

HTTP Method: POST
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups/Pbx.DeleteCompanyById

Request Body #

JSON

{
  "id": 123
}

Response Sukses: 204 No Content
Response Gagal (404 Not Found): {"error": "Department not found"}

3. Users Management #

Endpoint: Get List of Users #

Mengambil data seluruh pengguna terdaftar, lengkap dengan ID, nama, nomor ekstensi, email, dan keanggotaan grup/departemen mereka.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Users

Query Parameters (Opsional untuk Pagination & Filter) #

$top: Membatasi jumlah user yang dikembalikan (Default: 100).
$skip: Melompati sejumlah data untuk keperluan pagination (Default: 0).
$orderby: Mengurutkan data (Contoh: diurutkan berdasarkan Number).
$select: Memilih kolom spesifik (Contoh: Id,FirstName,LastName,Number,EmailAddress).

4. System & Utilities #

Endpoint: Get Default Group Properties #

Mengambil properti bawaan dari grup bernama “DEFAULT” guna melihat konfigurasi dasar sistem dan perutean panggilan (call routing).

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Groups?$filter=Name eq 'DEFAULT'

Response Contoh (200 OK) #

JSON

{
  "@odata.context": "https://PBX_FQDN/xapi/v1/$metadata#Groups",
  "value": [
    {
      "Name": "DEFAULT",
      "IsDefault": true,
      "HasMembers": true,
      "Number": "GRP0000",
      "Id": 95,
      "OfficeRoute": {
        "Route": { "Number": "101", "To": "Extension", "Name": "sysadmin" }
      },
      "OutOfOfficeRoute": {
        "Route": { "Number": "101", "To": "VoiceMail", "Name": "sysadmin" }
      }
    }
  ]
}

Endpoint: Get 3CX Version & Connection Test #

Endpoint utilitas untuk memeriksa status koneksi API sekaligus mengetahui versi sistem 3CX yang sedang berjalan.

HTTP Method: GET (atau metode pengecekan standar)
Response Header Utama:

Perhatikan bagian Header saat sukses mendapat respons. Terdapat properti:

X-3CX-Version: 20.0.x.x (Menandakan versi 3CX aktif).

Dokumentasi ini disadur dari panduan resmi spesifikasi API 3CX.

5. Active Calls #

Endpoint ini digunakan untuk memantau panggilan yang sedang aktif secara real-time.

Endpoint: Get Active Calls Mengambil daftar semua panggilan yang sedang berlangsung di sistem 3CX.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/ActiveCalls
Query Parameters (Opsional):
- $top: Jumlah maksimal data (default: 100)
- $skip: Pagination (default: 0)
- $orderby: Urutkan data (contoh: EstablishedAt desc)
- $filter: Filter data (contoh: Callee eq ‘101’)

Response Contoh (200 OK)

JSON

{
  "@odata.context": "https://{{PBX_FQDN}}/xapi/v1/$metadata#ActiveCalls",
  "value": [
    {
      "Id": "12345",
      "Caller": "+6281234567890",
      "Callee": "101",
      "EstablishedAt": "2026-07-07T07:45:12Z",
      "Duration": 125,
      "Direction": "Inbound",
      "Queue": null,
      "Status": "Connected"
    }
  ]
}

Catatan: Endpoint ini sangat berguna untuk real-time monitoring (dashboard call center, wallboard, dll).

6. Reports & Call History #

XAPI menyediakan beberapa endpoint khusus untuk mengambil data laporan dan riwayat panggilan.

Endpoint: Call History View Mengambil riwayat panggilan lengkap.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/CallHistoryView
Query Parameters Penting:
- from & to (format ISO: 2026-07-01T00:00:00Z)
- $top, $skip, $orderby, $filter

Endpoint Lain untuk Reports (contoh):

/xapi/v1/ReportCallLogData/Pbx.GetCallLogData(…)
/xapi/v1/ReportAbandonedQueueCalls/Pbx.GetAbandonedQueueCallsData(…)
/xapi/v1/ReportQueuePerformanceOverview/…
/xapi/v1/ReportAgentLoginHistory/…

Contoh Penggunaan (dengan query):

GET https://{{PBX_FQDN}}/xapi/v1/CallHistoryView?$top=100&$skip=0&from=2026-07-01T00:00:00Z&to=2026-07-07T23:59:59Z

Tips: Gunakan Developer Tools (F12) di Web Console 3CX saat membuka report untuk melihat query parameter yang tepat.

7. Trunks & Routing #

Endpoint: Get Trunks Mengambil daftar SIP Trunks yang terdaftar.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/Trunks
Endpoint: Inbound/Outbound Rules

/xapi/v1/InboundRules
/xapi/v1/OutboundRules

Contoh Create/Update Trunk (POST/PATCH):

JSON

{
  "Name": "SIP Provider",
  "Host": "sip.provider.com",
  "Port": 5060,
  "Type": "SIP",
  ...
} Catatan: Pengelolaan routing (DID, Caller ID rules) biasanya melalui endpoint terkait Routes atau DialPlans.

8. Phonebook & Contacts #

Endpoint: Global Phonebook

GET → https://{{PBX_FQDN}}/xapi/v1/Phonebook
POST → Tambah kontak baru
PATCH → Update kontak
DELETE → Hapus kontak

Contoh Request Body (Create Contact):

JSON

{
  "FirstName": "John",
  "LastName": "Doe",
  "Number": "+628123456789",
  "Email": "[email protected]",
  "Company": "PT ABC"
}

Endpoint ini sangat berguna untuk sinkronisasi kontak dengan CRM.

9. System Settings & Utilities #

Endpoint: System Parameters Mengambil dan mengubah pengaturan sistem secara umum.

GET: https://{{PBX_FQDN}}/xapi/v1/SystemParameters
PATCH: Update parameter tertentu (contoh: recording settings, security, dll).

Endpoint Lain:

/xapi/v1/Defs → Mendapatkan definisi sistem (enums, options)
/xapi/v1/Groups?$filter=Name eq ‘DEFAULT’ → Default Group Properties (sudah ada di dokumentasi kamu)

10. Event Logs #

Endpoint: Get Event Logs Mengambil log sistem dan event.

HTTP Method: GET
URL Endpoint: https://{{PBX_FQDN}}/xapi/v1/EventLogs
Query Parameters: $top, $skip, $filter (berdasarkan waktu, severity, dll), $orderby=Timestamp desc

Response Contoh:

JSON

{
  "value": [
    {
      "Timestamp": "2026-07-07T07:50:00Z",
      "Severity": "Info",
      "Component": "CallManager",
      "Message": "Call established between 101 and +62812..."
    }
  ]
}

Rekomendasi Tambahan #

Swagger Reference Akses dokumentasi lengkap langsung dari PBX kamu: https://{{PBX_FQDN}}/xapi/v1/swagger.yaml
Best Practice:
- Selalu gunakan System Owner role untuk akses maksimal.
- Implementasikan refresh token logic karena token expired setiap 1 jam.
- Untuk report besar, gunakan pagination ($top + $skip) agar tidak timeout.
- Gunakan F12 Network tab di 3CX Web Console untuk “spy” endpoint dan parameter yang digunakan sistem.

IP Phone

3CX Softphone: Webclient and Apps

3CX Admin Console & Manajemen Sistem

Keamanan VoIP dan Troubleshoot

Developer

SIP TRUNK

Panduan Endpoint REST API XAPI untuk Konfigurasi 3CX

🔗 Base URL & Environment #

📑 Daftar Isi (Table of Contents) #

1. Authentication / Authorization #

Endpoint: Get Token #

Request Body #

Response Contoh (200 OK) #

Error Response (401 Unauthorized) #

2. Departments Management #

Endpoint: Check if Department Exists #

Response Contoh – Jika Departemen Ditemukan (200 OK) #

Endpoint: Create a Department #

Request Body Contoh #

Response Contoh (201 Created) #

Error Response – Nama Duplikat (400 Bad Request) #

Endpoint: Update Department Details #

Request Body Contoh #

Endpoint: Delete a Department #

Request Body #

3. Users Management #

Endpoint: Get List of Users #

Query Parameters (Opsional untuk Pagination & Filter) #

4. System & Utilities #

Endpoint: Get Default Group Properties #

Response Contoh (200 OK) #

Endpoint: Get 3CX Version & Connection Test #

5. Active Calls #

6. Reports & Call History #

7. Trunks & Routing #

8. Phonebook & Contacts #

9. System Settings & Utilities #

10. Event Logs #

Rekomendasi Tambahan #