API & webhook

API tersedia di semua paket. Setiap bulan sudah termasuk 1.000 panggilan, dan kuota tambahan bisa dibeli di halaman Tagihan. Yang dihitung hanya permintaan dari sistem Anda yang memakai API key. Memakai aplikasi, otomasi, chatbot, broadcast, dan webhook keluar tidak dihitung.

Mulai dalam tiga langkah

curl https://karibin.com/api/v1/public/conversations?status=OPEN \
  -H "x-api-key: krbn_live_..."

Endpoint

Jendela 24 jam

Teks, media, tombol, dan lokasi hanya bisa dikirim dalam 24 jam sejak pesan terakhir pelanggan, sesuai aturan WhatsApp. Setiap percakapan (dan data webhook pesan) membawa windowOpen dan windowExpiresAt. Di luar jendela, permintaan langsung ditolak dengan 409 window_closed sebelum dikirim ke WhatsApp; pakai endpoint template untuk membuka percakapan lagi. Percakapan yang pelanggannya belum pernah mengirim pesan punya windowExpiresAt: null.

Kalau WhatsApp tetap menolak setelah dikirim, respons berisi status: "FAILED" dan failCode dari Meta.

Mengirim media

Unggah sebagai multipart/form-data dengan field file (opsional caption, replyToId), atau kirim JSON { "url": "https://...", "caption", "filename", "replyToId" } dan Karibin mengunduhnya dari alamat publik itu (tanpa mengikuti pengalihan, maksimal 15 detik).

Isi file diperiksa: file yang mengaku JPG, PNG, WEBP, PDF, atau MP4 tapi isinya lain ditolak.

Tombol dan daftar pilihan

{ "body": "Mau lanjut ke mana?", "buttons": [{ "id": "harga", "title": "Lihat harga" }, { "id": "cs", "title": "Bicara dengan CS" }] }

{ "body": "Pilih cabang terdekat", "list": { "buttonLabel": "Pilih cabang", "rows": [{ "id": "jkt", "title": "Jakarta", "description": "Jl. Sudirman 1" }] } }

Isi salah satu, buttons atau list. Batas WhatsApp berlaku apa adanya dan teks yang melewatinya ditolak, tidak dipotong: body 1.024 karakter, judul tombol 20, judul baris 24, deskripsi baris 72, label daftar 20. Id dan judul tombol harus unik. Saat pelanggan menekan pilihan, webhook message.received membawa message.interactiveReply: { "id": "harga", "title": "Lihat harga" }.

Template dengan header

{ "templateName": "promo_gambar", "languageCode": "id", "parameters": ["Budi", "50%"], "header": { "type": "image", "url": "https://cdn.anda.com/promo.jpg" } }

Sebelum dikirim, Karibin membaca template dari akun WhatsApp nomor pengirim dan memeriksa: template ada dan berstatus disetujui, jumlah parameters sama dengan isian {{1}}, {{2}} di teks, header sesuai jenisnya, dan isian tidak berisi baris baru, tab, atau lebih dari 4 spasi berturut-turut. File header diunduh langsung oleh WhatsApp dari url (harus https). Template dengan isian di teks header atau tombol URL dinamis belum didukung.

Bot atau AI milik Anda

Aktifkan Bot atau AI milik Anda sendiri di Pengaturan, lalu Integrasi & API. Setelah itu:

• Chat baru langsung dipegang bot (botActive: true) dan belum dibagikan ke agen. Menu chatbot dan otomasi pesan masuk tidak ikut menjawab.
• Bot membaca pesan lewat webhook message.received, lalu membalas lewat POST /messages.
• Bot menyerahkan chat ke manusia dengan POST /handoff. Tanpa agentId, Karibin memakai aturan pembagian workspace (termasuk aturan per iklan).
• Kalau bot diam lebih lama dari batas menit yang Anda atur setelah pesan pelanggan (bawaan 5 menit), chat otomatis dialihkan ke agen. Ini juga yang terjadi kalau bot mati atau kuota habis, jadi pelanggan tidak pernah dibiarkan menunggu.
• Begitu agen membalas chat bot, dari aplikasi maupun dari HP, bot berhenti untuk chat itu.

Webhook

Karibin mengirim POST JSON ke alamat Anda setiap kali ada kejadian. Isi pesan dikirim utuh, tanpa dipotong.

{
  "id": "cmd_delivery_id",
  "event": "message.received",
  "workspaceId": "ws_...",
  "createdAt": "2026-09-22T10:30:00.000Z",
  "data": {
    "conversation": { "id": "...", "status": "OPEN", "botActive": true, "assignedAgentId": null },
    "contact": { "id": "...", "name": "Budi", "phone": "6281234567890" },
    "message": { "id": "...", "direction": "INBOUND", "origin": "customer", "body": "Harga paket berapa?", "mediaUrl": null, "replyToId": null }
  }
}

const expected = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
const provided = req.headers["x-karibin-signature"].replace("sha256=", "");
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) return res.status(401).end();

Kuota, batas, dan kesalahan

Setiap respons membawa header X-Karibin-Quota-Used dan X-Karibin-Quota-Limit. Pemilik dan admin menerima email saat pemakaian mencapai 80% dan 100%. Kuota direset setiap tanggal 1 (WIB).