External Developer API

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:

<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", "phone": "081234567890", "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:

// Panggil tepat setelah user login
if (window.AI_LiveChat) {
  window.AI_LiveChat.identify({
    username: "esterc",              // Otomatis terhubung ke parameter tool AI & pre-chat
    phone: "085856566565",           // Otomatis terpetakan ke konteks & prefill form
    name: "Ester Cornelia",
    email: "[email protected]",
    tier: "VIP Gold"                 // Parameter kustom lainnya otomatis masuk ke context
  });
}

Metode 3: Script Siap Pakai (Async / Event-Safe Snippet)

Gunakan helper ringkas ini agar identitas tetap terkirim secara aman meskipun widget.js dimuat secara asynchronous atau masih dalam proses loading:

<script>
function setAIUser(user) {
  if (window.AI_LiveChat) return window.AI_LiveChat.identify(user);
  window.addEventListener("ai_livechat_ready", function () {
    window.AI_LiveChat.identify(user);
  }, { once: true });
}

// Panggil saat user aktif / login:
setAIUser({
  username: "esterc",
  phone: "085856566565"
});
</script>

Metode 4: Logout & Hapus Identitas Pengunjung (Clear Sesi)

Saat pengguna menekan tombol Logout di website/aplikasi Anda, panggil fungsi logout untuk menghapus seluruh data sesi di browser pengunjung:

// Panggil ini saat user logout dari aplikasi Anda
if (window.AI_LiveChat) {
  window.AI_LiveChat.logout(); // Atau: window.AI_LiveChat.identify(null);
}

Metode 5: Headless Chat External API (Mobile App / Custom Chat UI)

Kirimkan objek custom_context saat inisialisasi sesi percakapan:

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"
    }
  }'

Fungsi: Menambahkan domain whitelist agar widget hanya boleh di-load dari origin tersebut. Hapus dengan DELETE .../domains/{domain_id}.

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 -X DELETE https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID/domains/DOMAIN_ID \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

Fungsi: Menautkan endpoint Custom API ke bot agar AI bisa mengeksekusi tool saat chatting. Lepas dengan DELETE .../tools/{endpoint_id}.

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 -X DELETE https://YOUR_DOMAIN/api/v1/external/widgets/PUBLIC_BOT_ID/tools/ENDPOINT_UUID \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

Fungsi: Menampilkan daftar API sources. Secret token selalu di-mask di response.

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

Fungsi: Mendaftarkan API source baru (base URL + auth) yang nanti bisa punya banyak tool endpoint.

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
  }'

Fungsi: Mem-parse perintah cURL mentah menjadi API Source + tool endpoint secara otomatis.

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\"}'\''"
  }'

Fungsi: Menampilkan daftar tools di dalam satu API source.

curl -s https://YOUR_DOMAIN/api/v1/external/custom-apis/SOURCE_ID/endpoints \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

Fungsi: Menambahkan tool endpoint baru (path, method, parameter) ke API source yang sudah ada.

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 }
    ]
  }'

Fungsi: Menguji eksekusi tool dengan parameter simulasi. Mengembalikan status code, latency, dan preview response.

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" }
  }'

Fungsi: Mengecek ketersediaan & latency base URL API klien.

curl -X POST https://YOUR_DOMAIN/api/v1/external/custom-apis/SOURCE_ID/ping \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

Fungsi: Daftar sesi percakapan organisasi (chat aktif / terbuka). Setiap item di data[] menyertakan session_token yang bisa langsung dipakai untuk:

• GET /api/v1/external/chat/sessions/{session_token}/messages — riwayat pesan (visitor / ai / agent / system), kronologis
• POST .../messages — kirim pesan
• POST .../handover / POST .../close

Query: filter (default open = bukan closed/resolved; juga active, ai, waiting, inbox, archive, all), public_bot_id, customer_id, limit (max 200), offset.

curl -s "https://YOUR_DOMAIN/api/v1/external/chat/sessions?filter=open&limit=50" \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "session_token": "ses_a1b2c3d4e5f6...",
      "conversation_id": "1a2b3c4d-5e6f-...",
      "status": "ai_active",
      "channel": "web",
      "bot_id": "1a2b3c4d-5e6f-...",
      "public_bot_id": "bot_963b51f0_pub",
      "bot_name": "CS Bot",
      "customer_id": "cust-42",
      "customer_name": "Budi",
      "customer_email": "[email protected]",
      "ai_reply_enabled": true,
      "assigned_agent_id": null,
      "started_at": "2026-04-11T08:00:00+00:00",
      "updated_at": "2026-04-11T08:15:00+00:00",
      "closed_at": null
    }
  ],
  "message": "Daftar sesi percakapan berhasil diambil",
  "meta": { "total": 1, "limit": 50, "offset": 0, "filter": "open" }
}

curl -s https://YOUR_DOMAIN/api/v1/external/chat/sessions/ses_a1b2c3d4e5f6.../messages \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

Fungsi: Membuat sesi baru atau melanjutkan jika session_token masih aktif. Persist token di sisi klien.

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" }
  }'

Fungsi: Mengirim pesan user; response berisi jawaban AI (atau system jika eskalasi/agen aktif).

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?" }'

Fungsi: Mengambil riwayat pesan sesi (visitor / ai / agent / system), diurutkan kronologis.

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

Fungsi: Admin / CRM membalas sebagai human agent (bukan AI). Pesan tersimpan dengan sender_type=agent, percakapan di-claim ke agent_active, dan visitor menerima via WebSocket / GET .../messages.

Body: content (wajib), agent_id (opsional — UUID AgentProfile atau User), agent_name (opsional — label display). Jika agent_id kosong, sistem memakai profil agen organisasi (fallback).

Alur: GET /chat/sessions atau POST /chat/sessions → ambil session_token → POST .../agent-messages.

curl -X POST https://YOUR_DOMAIN/api/v1/external/chat/sessions/SESSION_TOKEN/agent-messages \
  -H "X-API-Key: lc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Paket Anda sedang dalam perjalanan, estimasi taterima besok.",
    "agent_name": "CS Budi"
  }'

{
  "success": true,
  "data": {
    "message_id": "a1b2c3d4-...",
    "session_token": "ses_a1b2c3d4e5f6...",
    "conversation_id": "1a2b3c4d-5e6f-...",
    "sender_type": "agent",
    "content": "Paket Anda sedang dalam perjalanan, estimasi taterima besok.",
    "agent_name": "CS Budi",
    "auto_claimed": true,
    "status": "agent_active",
    "assigned_agent_id": "9f8e7d6c-...",
    "created_at": "2026-04-11T08:20:00+00:00"
  },
  "message": "Pesan agen berhasil dikirim ke pengunjung"
}

Fungsi: Mengalihkan percakapan ke antrean Live Agent manusia di Agent Desk.

curl -X POST https://YOUR_DOMAIN/api/v1/external/chat/sessions/SESSION_TOKEN/handover \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

Fungsi: Menutup sesi. Opsional kirim CSAT (rating 1–5 + feedback).

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"
  }'

Fungsi: Menampilkan dokumen terindeks (status, chunk_count, nama file). Filter opsional lewat query bot_id.

curl -s "https://YOUR_DOMAIN/api/v1/external/knowledge/documents?bot_id=BOT_UUID" \
  -H "X-API-Key: lc_live_YOUR_API_KEY"

Fungsi: Mengunggah PDF / TXT / DOCX (multipart/form-data) untuk di-chunk & diindeks ke vector store. Field: file, opsional bot_id.

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"

Fungsi: Menambahkan pasangan FAQ (tanya–jawab) ke knowledge base bot.

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"]
  }'

Fungsi: Menghapus dokumen beserta seluruh embedding vektor terkait.

curl -X DELETE https://YOUR_DOMAIN/api/v1/external/knowledge/documents/DOC_ID \
  -H "X-API-Key: lc_live_YOUR_API_KEY"