Navigasi

Developer Documentation

External Developer API

REST API untuk mengintegrasikan AI LiveChat Pro ke aplikasi Anda: CRM, mobile app, e-commerce, atau custom UI. Seluruh endpoint data plane memakai header X-API-Key.

Base URL https://ailivechat.pro/api/v1/external Auth X-API-Key Rate limit 60 req/min Format JSON

Pengantar

External API membuka kapabilitas yang sama dengan dashboard, tanpa sesi browser. Di contoh cURL, ganti YOUR_DOMAIN dengan ailivechat.pro (produksi) atau domain staging Anda. Cocok untuk:

Headless chat di aplikasi iOS/Android atau custom web UI
Provisioning bot, widget, dan domain whitelist secara otomatis
Lifecycle WhatsApp (QR / pairing code, outbound message)
Mendaftarkan REST tool agar AI bisa function-calling ke sistem Anda
Ingest dokumen & FAQ ke knowledge base (RAG)

Envelope sukses: semua response sukses memakai bentuk { "success": true, "data": ..., "message": "..." } (kadang disertai meta).

Quick start (3 langkah)

Login & buat API Key Authentikasi sebagai Admin/Owner dengan JWT, lalu POST /api/v1/external/keys. Simpan nilai api_key — plaintext hanya muncul sekali.
Panggil endpoint dengan X-API-Key Sertakan header X-API-Key: lc_live_... (atau lc_test_... di non-produksi).
Mulai dari headless chat atau widgets Contoh: buat sesi chat lalu kirim pesan, atau list bot dengan GET /widgets.

Contoh — list widgets

curl -s https://YOUR_DOMAIN/api/v1/external/widgets \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

Panduan Resource IDs (bot_id, channel_id, source_id)

Banyak endpoint membutuhkan identifier spesifik pada path URL. Berikut penjelasan setiap ID dan cara menemukannya:

public_bot_id bot_963b51f0_pub

Fungsi: Widget embed, headless chat, & URL publik
Dashboard: Bot Management → label Public ID
Via API: GET /api/v1/external/widgets

bot_id UUID 1a2b3c4d-5e6f-…

Fungsi: Provisi saluran WhatsApp & knowledge base (RAG)
Dashboard: Bot Management → label bot_id
Via API: GET /api/v1/external/widgets → field id

channel_id 2c3d4e5f-6a7b-…

Fungsi: WhatsApp & Telegram Channel (status, konfigurasi, & outbound message)
Dashboard: WhatsApp & Telegram Channel → label channel_id
Via API: GET /api/v1/external/whatsapp/sessions / GET /api/v1/external/telegram/sessions

source_id 3d4e5f6a-7b8c-…

Fungsi: Custom REST API source & tool calling
Dashboard: Custom API → kartu API
Via API: GET /api/v1/external/custom-apis

session_token ses_…

Fungsi: Sesi obrolan pengunjung (headless chat)
Dashboard: Otomatis diterbitkan saat inisialisasi chat
Via API: POST /api/v1/external/chat/sessions

💡 Tip Praktis: Buka tab Developer API & Keys di Dashboard. Di bawah tabel API Key terdapat "Resource IDs Directory" yang menampilkan seluruh daftar Bot, WhatsApp, dan Custom API milik organisasi Anda lengkap dengan tombol 1-Click Copy.

Autentikasi

1) Manajemen key — JWT Bearer

Endpoint /keys memakai token login dashboard (role tenant_owner atau admin).

cURL — buat API Key (JWT)

curl -X POST https://YOUR_DOMAIN/api/v1/external/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production CRM",
    "scopes": ["chat:read", "chat:write", "widgets:read"],
    "ip_whitelist": ["203.0.113.15/32"]
  }'

2) Data plane — X-API-Key

Semua endpoint selain manajemen key memakai header:

X-API-Key: lc_live_<prefix8>_<entropy32>

Alternatif: Authorization: Bearer lc_live_... (nilai key, bukan JWT).

Server tidak pernah menyimpan plaintext key. Yang tersimpan hanya SHA-256 hash + prefix 16 karakter untuk UI. Maksimal 2 key aktif per organisasi (dual-key rotation).

Scopes (izin granular)

Setiap key dibatasi scope. Gunakan "*" hanya untuk development. Scope :write / :admin juga mengizinkan :read pada resource yang sama.

Scope	Fungsi
`whatsapp:read`	List sesi, QR, status koneksi
`whatsapp:write`	Provision, pairing, kirim pesan, restart, logout
`whatsapp:admin`	Hapus sesi & cabut key WhatsApp Gateway
`telegram:read`	List sesi Telegram, metadata bot, status webhook
`telegram:write`	Provision bot Telegram, kirim pesan outbound, update config, sync webhook
`telegram:admin`	Hapus sesi Telegram permanen & cabut webhook Telegram Cloud
`widgets:read`	List/detail bot, embed snippet
`widgets:write`	Buat/update bot, theme, domain, tautkan tools
`chat:read`	Baca riwayat pesan
`chat:write`	Buat sesi, kirim pesan, handover, close
`tools:read`	List custom API, ping
`tools:write`	Register API, import cURL, test, endpoints
`knowledge:read`	List dokumen
`knowledge:write`	Upload dokumen, FAQ, hapus dokumen

Error envelope & rate limit

Error eksternal selalu berbentuk:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key tidak valid, nonaktif, atau telah kedaluwarsa.",
    "details": null
  },
  "timestamp": "2026-09-24T12:00:00Z"
}

HTTP	Code	Artinya
401	`INVALID_API_KEY`	Key hilang, salah, nonaktif, atau kedaluwarsa
403	`INSUFFICIENT_SCOPE`	Scope key tidak mencukupi
403	`IP_NOT_ALLOWED`	IP pemanggil di luar whitelist
400	`SSRF_BLOCKED`	URL tujuan ke jaringan privat / metadata
402	`QUOTA_EXCEEDED`	Kuota pesan/token organisasi habis
429	`RATE_LIMIT_EXCEEDED`	> 60 request / menit per API key
404	`RESOURCE_NOT_FOUND`	Resource tidak ada di organisasi Anda

A. Manajemen API Keys

Kelola kredensial organisasi. Auth: JWT Admin/Owner (bukan X-API-Key). Gunakan token login dashboard di header Authorization: Bearer.

POST /api/v1/external/keys

JWT · Admin/Owner

Fungsi: Menerbitkan API key baru untuk integrasi eksternal. Field api_key di response hanya muncul sekali — simpan segera.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App Prod",
    "scopes": ["chat:read", "chat:write", "widgets:read"],
    "ip_whitelist": ["203.0.113.0/24"],
    "expires_at": null
  }'

Response 201

{
  "success": true,
  "data": {
    "id": "9f2c1a...",
    "name": "Mobile App Prod",
    "key_prefix": "lc_live_a1b2c3d4",
    "scopes": ["chat:read", "chat:write", "widgets:read"],
    "ip_whitelist": ["203.0.113.0/24"],
    "is_active": true,
    "api_key": "lc_live_a1b2c3d4_8f9e0a1b2c3d4e5f6a7b8c9d"
  },
  "message": "API Key berhasil diterbitkan. Simpan nilai api_key sekarang — tidak akan ditampilkan lagi."
}

GET /api/v1/external/keys

JWT · Admin/Owner

Fungsi: Menampilkan daftar key organisasi. Hanya key_prefix yang terlihat — plaintext tidak pernah diulang.

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

PATCH /api/v1/external/keys/{key_id}

JWT · Admin/Owner

Fungsi: Mengubah nama, scopes, IP whitelist, atau status aktif/nonaktif. Mengaktifkan key ke-3 akan ditolak (MAX_ACTIVE_KEYS).

cURL

curl -X PATCH https://YOUR_DOMAIN/api/v1/external/keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

DELETE /api/v1/external/keys/{key_id}

JWT · Admin/Owner

Fungsi: Mencabut key secara permanen. Request berikutnya dengan key tersebut mendapat 401 INVALID_API_KEY.

cURL

curl -X DELETE https://YOUR_DOMAIN/api/v1/external/keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

B. WhatsApp Automation

Lifecycle sesi WhatsApp Gateway: allocate → QR/pairing → outbound message → logout/delete. Ganti CHANNEL_ID dengan UUID dari Resource IDs Directory.

POST /api/v1/external/whatsapp/sessions

whatsapp:write

Fungsi: Mengalokasikan sesi WhatsApp baru, mendaftarkan webhook internal, dan menyalakan engine pairing.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "BOT_UUID",
    "session_name": "cs-store-whatsapp"
  }'

Response 201

{
  "success": true,
  "data": {
    "channel_id": "c92842fa-192a-4a55-8ab2-d278b0124801",
    "openwa_session_name": "cs-store-whatsapp",
    "status": "initializing",
    "qr_url": "/api/v1/external/whatsapp/sessions/c92842fa-.../qr"
  },
  "message": "Sesi WhatsApp berhasil dialokasikan"
}

GET /api/v1/external/whatsapp/sessions

whatsapp:read

Fungsi: Menampilkan seluruh saluran WhatsApp organisasi (status, nomor, nama sesi).

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

GET /api/v1/external/whatsapp/sessions/{channel_id}/qr

whatsapp:read

Fungsi: Mengambil QR Code live (data URL PNG Base64) untuk di-scan di WhatsApp Linked Devices. Poll sampai status ready / connected.

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions/CHANNEL_ID/qr \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

POST /api/v1/external/whatsapp/sessions/{channel_id}/pairing-code

whatsapp:write

Fungsi: Alternatif QR — meminta kode pairing 8 digit ke nomor telepon target.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions/CHANNEL_ID/pairing-code \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+6281234567890" }'

GET /api/v1/external/whatsapp/sessions/{channel_id}/status

whatsapp:read

Fungsi: Mengecek status realtime (ready, qr_ready, disconnected, dll.) beserta nomor yang terhubung.

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions/CHANNEL_ID/status \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

POST /api/v1/external/whatsapp/sessions/{channel_id}/messages

whatsapp:write

Fungsi: Mengirim pesan outbound WhatsApp. Field to bisa nomor internasional atau chat id.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions/CHANNEL_ID/messages \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "6281234567890",
    "text": "Pesanan #ORD-123 sudah dikirim. Lacak di link berikut."
  }'

POST /api/v1/external/whatsapp/sessions/{channel_id}/restart

whatsapp:write

Fungsi: Merestart engine sesi jika pairing putus atau QR macet.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions/CHANNEL_ID/restart \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

POST /api/v1/external/whatsapp/sessions/{channel_id}/logout

whatsapp:write

Fungsi: Unlink perangkat WhatsApp tanpa menghapus record channel di database.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions/CHANNEL_ID/logout \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

DELETE /api/v1/external/whatsapp/sessions/{channel_id}

whatsapp:admin

Fungsi: Menghapus sesi permanen dan mencabut scoped API key di WhatsApp Gateway.

cURL

curl -X DELETE https://YOUR_DOMAIN/api/v1/external/whatsapp/sessions/CHANNEL_ID \
  -H "X-API-Key: lc_live_..."

C. Telegram Channel Automation

Lifecycle saluran Telegram Bot API: provision token BotFather → auto-register webhook HTTPS → outbound messaging → status → delete. Ganti CHANNEL_ID dengan UUID saluran Telegram dari Resource IDs Directory.

POST /api/v1/external/telegram/sessions

telegram:write

Fungsi: Mengalokasikan saluran Telegram baru, memvalidasi bot token via getMe, mengenkripsi token dengan AES-256-GCM, mendaftarkan webhook internal secara otomatis (setWebhook), dan menautkan ke Bot AI.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/telegram/sessions \
  -H "X-API-Key: lc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "BOT_UUID",
    "bot_token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz123456"
  }'

Contoh Respon (201 Created)

{
  "success": true,
  "data": {
    "channel_id": "550e8400-e29b-41d4-a716-446655440000",
    "telegram_bot_username": "toko_official_bot",
    "telegram_bot_name": "Toko Official CS",
    "status": "connected"
  },
  "message": "Sesi Telegram berhasil dialokasikan"
}

GET /api/v1/external/telegram/sessions

telegram:read

Fungsi: Menampilkan seluruh saluran Telegram organisasi (username bot, status, allowed chat types, parse mode).

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/telegram/sessions \
  -H "X-API-Key: lc_live_..."

GET /api/v1/external/telegram/sessions/{channel_id}

telegram:read

Fungsi: Mengambil detail konfigurasi saluran Telegram berdasarkan channel_id.

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/telegram/sessions/CHANNEL_ID \
  -H "X-API-Key: lc_live_..."

GET /api/v1/external/telegram/sessions/{channel_id}/status

telegram:read

Fungsi: Memeriksa status kesehatan koneksi dan webhook realtime langsung dari Telegram Cloud API (getWebhookInfo).

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/telegram/sessions/CHANNEL_ID/status \
  -H "X-API-Key: lc_live_..."

POST /api/v1/external/telegram/sessions/{channel_id}/messages

telegram:write

Fungsi: Mengirim pesan outbound ke pelanggan via Telegram Chat ID. Mendukung format teks HTML maupun Markdown.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/telegram/sessions/CHANNEL_ID/messages \
  -H "X-API-Key: lc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "987654321",
    "text": "Halo! Pesanan nomor #ORD-9821 telah dikonfirmasi."
  }'

PATCH /api/v1/external/telegram/sessions/{channel_id}

telegram:write

Fungsi: Mengubah pengaturan saluran Telegram (reassign Bot AI lain, ganti parse mode HTML/Markdown, ubah allowed chat types, atau toggle status aktif).

cURL

curl -X PATCH https://YOUR_DOMAIN/api/v1/external/telegram/sessions/CHANNEL_ID \
  -H "X-API-Key: lc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "parse_mode": "HTML",
    "allowed_chat_types": "private,group",
    "enabled": true
  }'

POST /api/v1/external/telegram/sessions/{channel_id}/sync-webhook

telegram:write

Fungsi: Mendaftarkan ulang webhook URL ke Telegram Cloud API saat terjadi rotasi domain server atau pembaruan sertifikat SSL.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/telegram/sessions/CHANNEL_ID/sync-webhook \
  -H "X-API-Key: lc_live_..."

DELETE /api/v1/external/telegram/sessions/{channel_id}

telegram:admin

Fungsi: Menghapus saluran Telegram secara permanen dan mencabut webhook di Telegram Cloud (deleteWebhook).

cURL

curl -X DELETE https://YOUR_DOMAIN/api/v1/external/telegram/sessions/CHANNEL_ID \
  -H "X-API-Key: lc_live_..."

D. Widgets & Bot Management

Provision bot AI, theme widget, domain whitelist, dan embed snippet secara programmatic. Ganti PUBLIC_BOT_ID dengan nilai dari Resource IDs Directory.

GET /api/v1/external/widgets

widgets:read

Fungsi: Menampilkan semua bot/widget organisasi beserta embed_snippet dan public_bot_id.

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/widgets \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

POST /api/v1/external/widgets

widgets:write

Fungsi: Membuat bot + widget settings default dalam satu pemanggilan.

cURL

curl -X POST https://YOUR_DOMAIN/api/v1/external/widgets \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CS Toko Online",
    "system_prompt": "Kamu adalah asisten CS toko fashion. Jawab singkat dan ramah.",
    "ai_model": "mimo-v2.5",
    "primary_language": "id",
    "tone": "friendly",
    "welcome_message": "Halo! Ada yang bisa kami bantu?",
    "allowed_domains": ["https://tokoanda.com"]
  }'

GET /api/v1/external/widgets/{public_bot_id}

widgets:read

Fungsi: Mengambil detail konfigurasi bot + objek theme (warna, posisi, judul).

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

PATCH /api/v1/external/widgets/{public_bot_id}

widgets:write

Fungsi: Memperbarui prompt, model AI, fallback message, flag handover, dsb. Kirim hanya field yang diubah.

cURL

curl -X PATCH https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "welcome_message": "Halo! Tim CS siap membantu.",
    "system_prompt": "Jawab dalam Bahasa Indonesia, singkat dan sopan."
  }'

PATCH /api/v1/external/widgets/{public_bot_id}/theme

widgets:write

Fungsi: Mengubah tampilan widget (warna, posisi, judul, suara).

cURL

curl -X PATCH https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID/theme \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_color": "#0F766E",
    "position": "bottom-right",
    "widget_title": "Bantuan Toko",
    "widget_subtitle": "Biasanya membalas dalam beberapa detik",
    "enable_sound": true
  }'

GET /api/v1/external/widgets/{public_bot_id}/embed

widgets:read

Fungsi: Mengambil tag <script> embed dan URL iframe untuk dipasang di website. Lihat juga panduan integrasi widget.

cURL

curl -s https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID/embed \
  -H "X-API-Key: lc_liv...pre>



      
      
        
          AUTH / SSO
          Kirim Username & Context ke LiveChat Widget & API
        
        client-side / headless
        Fungsi: Jika website/aplikasi Anda memiliki sistem login pengguna, teruskan identitas (username, customer_name, email, dan objek custom_context) ke sistem AI LiveChat Pro. AI akan secara otomatis mengenali profil pengguna dan memetakannya ke parameter Custom API Tools tanpa harus bertanya lagi ke user.

        Metode 1: HTML Data Attributes pada <script> Tag (PHP / Blade / WordPress)
        Sisipkan atribut data-username dan data-context pada tag script embed di template website:
        HTML Script Tag
        <script 
  src="https://ailivechat.pro/cdn/widget.js" 
  data-bot-id="PUBLIC_BOT_ID"
  data-username="rere123"
  data-customer-name="Rere Pratama"
  data-customer-email="[email protected]"
  data-context='{"username": "rere123", "member_id": "MEM-9876", "tier": "VIP Gold"}'
></script>

        Metode 2: JavaScript Client API (Single Page Application — React / Vue / Next.js)
        Panggil fungsi window.AI_LiveChat.identify() kapan saja tepat setelah pengguna berhasil login:
        JavaScript Frontend
        // Panggil fungsi ini tepat setelah user login
if (window.AI_LiveChat) {
  window.AI_LiveChat.identify({
    username: "rere123",              // Otomatis terhubung ke parameter tool username
    name: "Rere Pratama",
    email: "[email protected]",
    context: {
      username: "rere123",
      member_id: "MEM-9876",
      tier: "VIP Gold"
    }
  });
}

        Metode 3: Headless Chat External API (Mobile App / Custom Chat UI)
        Kirimkan objek custom_context saat inisialisasi sesi percakapan:
        cURL — init session dengan context
        curl -X POST https://YOUR_DOMAIN/api/v1/external/chat/sessions \
  -H "X-API-Key: lc_liv...KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "PUBLIC_BOT_ID",
    "customer_name": "Rere Pratama",
    "custom_context": {
      "username": "rere123",
      "member_id": "MEM-9876",
      "tier": "VIP Gold"
    }
  }'

        
          💡 Otomatis Terhubung ke Custom API: Jika Bot Anda memiliki tool Custom API dengan parameter username, user, member, atau player, AI akan otomatis mengambil nilai username dari session context ini (misal saat user bertanya "cek sisa saldo saya") tanpa meminta user mengetikkan username lagi.
        
      

      
        
          POST
          /api/v1/external/widgets/{public_bot_id}/domains
        
        widgets:write
        Fungsi: Menambahkan domain whitelist agar widget hanya boleh di-load dari origin tersebut. Hapus dengan DELETE .../domains/{domain_id}.
        cURL — tambah domain
        curl -X POST https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID/domains \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_origin": "https://checkout.tokoanda.com" }'
        cURL — hapus domain
        curl -X DELETE https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID/domains/DOMAIN_ID \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
        
          POST
          /api/v1/external/widgets/{public_bot_id}/tools
        
        widgets:write
        Fungsi: Menautkan endpoint Custom API ke bot agar AI bisa mengeksekusi tool saat chatting. Lepas dengan DELETE .../tools/{endpoint_id}.
        cURL — tautkan tool
        curl -X POST https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID/tools \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint_id": "ENDPOINT_UUID" }'
        cURL — lepas tool
        curl -X DELETE https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID/tools/ENDPOINT_UUID \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
      D. Custom API Manager
      Daftarkan REST API pihak ketiga sebagai AI tools. Semua URL diverifikasi SSRF guard (blokir localhost, RFC1918, metadata cloud).

      
        
          GET
          /api/v1/external/custom-apis
        
        tools:read
        Fungsi: Menampilkan daftar API sources. Secret token selalu di-mask di response.
        cURL
        curl -s https://YOUR_DOMAIN/api/v1/external/custom-apis \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
        
          POST
          /api/v1/external/custom-apis
        
        tools:write
        Fungsi: Mendaftarkan API source baru (base URL + auth) yang nanti bisa punya banyak tool endpoint.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/custom-apis \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Merchant Orders",
    "base_url": "https://api.merchant.com",
    "auth_type": "bearer_token",
    "auth_token": "secret_token_xyz",
    "timeout_seconds": 10
  }'
      

      
        
          POST
          /api/v1/external/custom-apis/import-curl
        
        tools:write
        Fungsi: Mem-parse perintah cURL mentah menjadi API Source + tool endpoint secara otomatis.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/custom-apis/import-curl \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "curl_command": "curl -X POST '\''https://api.merchant.com/v1/check-order'\'' -H '\''Authorization: Bearer secret_token_xyz'\'' -H '\''Content-Type: application/json'\'' -d '\''{\"order_id\": \"ORD-12345\"}'\''"
  }'
      

      
        
          GET
          /api/v1/external/custom-apis/{source_id}/endpoints
        
        tools:read
        Fungsi: Menampilkan daftar tools di dalam satu API source.
        cURL
        curl -s https://YOUR_DOMAIN/api/v1/external/custom-apis/SOURCE_ID/endpoints \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
        
          POST
          /api/v1/external/custom-apis/{source_id}/endpoints
        
        tools:write
        Fungsi: Menambahkan tool endpoint baru (path, method, parameter) ke API source yang sudah ada.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/custom-apis/SOURCE_ID/endpoints \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "get_shipping",
    "path": "/v1/shipping/{tracking_id}",
    "http_method": "GET",
    "description": "Cek status pengiriman berdasarkan tracking ID",
    "parameters": [
      { "name": "tracking_id", "location": "path", "data_type": "string", "is_required": true }
    ]
  }'
      

      
        
          POST
          /api/v1/external/custom-apis/{source_id}/test
        
        tools:write
        Fungsi: Menguji eksekusi tool dengan parameter simulasi. Mengembalikan status code, latency, dan preview response.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/custom-apis/SOURCE_ID/test \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "ENDPOINT_UUID",
    "parameters": { "order_id": "ORD-12345" }
  }'
      

      
        
          POST
          /api/v1/external/custom-apis/{source_id}/ping
        
        tools:read
        Fungsi: Mengecek ketersediaan & latency base URL API klien.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/custom-apis/SOURCE_ID/ping \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
      E. Headless Chat
      API chat tanpa widget — ideal untuk mobile app atau custom UI. Pipeline AI sama dengan widget (RAG + tool calling + guardrail). Batas pesan: 2.000 karakter.

      
        
          POST
          /api/v1/external/chat/sessions
        
        chat:write
        Fungsi: Membuat sesi baru atau melanjutkan jika session_token masih aktif. Persist token di sisi klien.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/chat/sessions \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "public_bot_id": "PUBLIC_BOT_ID",
    "customer_name": "Budi",
    "customer_email": "[email protected]",
    "custom_context": { "order_id": "ORD-99" }
  }'
      

      
        
          POST
          /api/v1/external/chat/sessions/{session_token}/messages
        
        chat:write
        Fungsi: Mengirim pesan user; response berisi jawaban AI (atau system jika eskalasi/agen aktif).
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/chat/sessions/SESSION_TOKEN/messages \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Di mana paket saya ORD-99?" }'
      

      
        
          GET
          /api/v1/external/chat/sessions/{session_token}/messages
        
        chat:read
        Fungsi: Mengambil riwayat pesan sesi (visitor / ai / agent / system), diurutkan kronologis.
        cURL
        curl -s https://YOUR_DOMAIN/api/v1/external/chat/sessions/SESSION_TOKEN/messages \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
        
          POST
          /api/v1/external/chat/sessions/{session_token}/handover
        
        chat:write
        Fungsi: Mengalihkan percakapan ke antrean Live Agent manusia di Agent Desk.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/chat/sessions/SESSION_TOKEN/handover \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
        
          POST
          /api/v1/external/chat/sessions/{session_token}/close
        
        chat:write
        Fungsi: Menutup sesi. Opsional kirim CSAT (rating 1–5 + feedback).
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/chat/sessions/SESSION_TOKEN/close \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "feedback_text": "Cepat dan membantu"
  }'
      

      
      F. Knowledge Base (RAG)
      Ingest dokumen dan FAQ agar AI menjawab berbasis knowledge organisasi Anda.

      
        
          GET
          /api/v1/external/knowledge/documents?bot_id={bot_id}
        
        knowledge:read
        Fungsi: Menampilkan dokumen terindeks (status, chunk_count, nama file). Filter opsional lewat query bot_id.
        cURL
        curl -s "https://YOUR_DOMAIN/api/v1/external/knowledge/documents?bot_id=BOT_UUID" \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
        
          POST
          /api/v1/external/knowledge/documents/upload
        
        knowledge:write
        Fungsi: Mengunggah PDF / TXT / DOCX (multipart/form-data) untuk di-chunk & diindeks ke vector store. Field: file, opsional bot_id.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/knowledge/documents/upload \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -F "[email protected]" \
  -F "bot_id=BOT_UUID"
      

      
        
          POST
          /api/v1/external/knowledge/faq
        
        knowledge:write
        Fungsi: Menambahkan pasangan FAQ (tanya–jawab) ke knowledge base bot.
        cURL
        curl -X POST https://YOUR_DOMAIN/api/v1/external/knowledge/faq \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "BOT_UUID",
    "question": "Berapa lama pengiriman ke Jakarta?",
    "answer": "Estimasi 1–2 hari kerja untuk area Jabodetabek.",
    "category": "shipping",
    "tags": ["ongkir", "eta"]
  }'
      

      
        
          DELETE
          /api/v1/external/knowledge/documents/{doc_id}
        
        knowledge:write
        Fungsi: Menghapus dokumen beserta seluruh embedding vektor terkait.
        cURL
        curl -X DELETE https://YOUR_DOMAIN/api/v1/external/knowledge/documents/DOC_ID \
  -H "X-API-Key: lc_live_YOUR_API_KEY"
      

      
      Verifikasi outbound webhook
      Jika sistem mengirim event ke URL Anda, verifikasi signature berikut untuk mencegah spoofing & replay:
      
        X-LiveChat-Timestamp — UNIX timestamp saat event
        X-LiveChat-Signature — hex HMAC-SHA256 dari timestamp + "." + raw_body
      
      
        Tolak request jika |now - timestamp| > 300 detik (anti-replay).
      
      Pseudo-code verifikasi
      message = f"{timestamp}.{raw_body}".encode()
expected = hmac_sha256(secret, message).hex()
assert hmac.compare_digest(expected, signature)
assert abs(time.time() - int(timestamp)) <= 300

      
      Best practices
      
        Least privilege — buat key per aplikasi dengan scopes minimal.
        IP whitelist — aktifkan untuk server backend yang IP-nya stabil.
        Dual-key rotation — buat key baru, migrasi traffic, nonaktifkan/hapus key lama.
        Jangan commit key — format lc_live_ / lc_test_ dideteksi secret scanner.
        Hormati 429 — implement exponential backoff bila terkena rate limit.
        Headless chat — persist session_token di sisi klien untuk melanjutkan percakapan.
      

      
        Siap mencoba? Buat akun, generate API key dari endpoint /keys, lalu mulai dari headless chat atau list widgets.
        Buat akun
        Panduan widget
        Masuk dashboard