API & webhook
Sambungkan bot, AI, atau sistem Anda sendiri ke Karibin untuk membaca dan membalas percakapan WhatsApp, menyalurkan lead, dan menerima setiap kejadian.
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
- Buka Pengaturan, lalu Integrasi & API, dan buat API key. Simpan key-nya, karena hanya ditampilkan sekali.
- Kirim permintaan dengan header
x-api-key: krbn_live_...ke alamat dasarhttps://karibin.com/api/v1/public. - Kalau sistem Anda perlu tahu setiap pesan masuk, tambahkan alamat webhook di halaman yang sama.
curl https://karibin.com/api/v1/public/conversations?status=OPEN \
-H "x-api-key: krbn_live_..."
Endpoint
| Metode | Alamat | Kegunaan |
|---|---|---|
| GET | /public/usage | Pemakaian kuota bulan ini |
| GET | /public/conversations | Daftar percakapan. Filter: status, bot=true, updatedSince, limit, cursor |
| GET | /public/conversations/:id | Satu percakapan beserta kontaknya. status berisi kategori, statusName nama status kustom workspace bila ada |
| GET | /public/conversations/:id/messages | Pesan dari yang terlama. after=<id pesan> untuk membaca yang baru saja |
| POST | /public/conversations/:id/messages | Kirim teks: { "text": "...", "replyToId": "..." } |
| POST | /public/conversations/:id/media | Kirim gambar, video, audio, dokumen, atau stiker. Unggah file, atau { "url": "https://..." } |
| POST | /public/conversations/:id/interactive | Kirim 1 sampai 3 tombol, atau daftar 1 sampai 10 pilihan |
| POST | /public/conversations/:id/location | Kirim lokasi: { "latitude", "longitude", "name", "address" } |
| POST | /public/conversations/:id/template | Kirim template yang disetujui Meta, termasuk template ber-header gambar, video, atau dokumen |
| POST | /public/conversations/:id/handoff | Serahkan ke agen: { "agentId": "...", "note": "..." } (keduanya opsional) |
| POST | /public/conversations/:id/bot | Bot mengambil (kembali) percakapan |
| PATCH | /public/conversations/:id | Ubah status: { "status": "RESOLVED" }. Status kustom workspace di percakapan itu ikut dilepas |
| GET | /public/contacts?phone=0812... | Cari kontak dari nomor, format lokal atau internasional |
| GET | /public/contacts | Tanpa phone: daftar kontak, yang terakhir berubah dulu. Filter: q (nama, nomor, email, atau perusahaan), tag (nama atau id label), updatedSince, ownerEmail (pemilik kontak), limit, cursor |
| GET | /public/contacts/:id | Satu kontak beserta label, perusahaan, catatan, dan status broadcast |
| POST | /public/contacts | Buat kontak: { "name", "phone", "email", "notes", "tags": ["..."], "company": "..." } |
| PATCH | /public/contacts/:id | Ubah kolom yang dikirim saja. tags mengganti seluruh label |
| GET | /public/companies | Daftar perusahaan. Saring nama dengan q |
| GET | /public/companies/:id | Satu perusahaan beserta jumlah kontak dan deal |
| POST | /public/companies | Buat perusahaan: { "name", "website", "phone", "industry", "address", "notes" }. Butuh contacts:write |
| PATCH | /public/companies/:id | Ubah kolom yang dikirim saja. Butuh contacts:write |
| DELETE | /public/companies/:id | Hapus perusahaan (kontak dan deal-nya tetap ada). Butuh contacts:write |
| POST | /public/messages/template | Kirim template ke nomor mana pun, termasuk yang belum pernah chat. Kontak dan percakapannya dibuat sendiri |
| POST | /public/leads | Salurkan lead: { "name", "phone", "email", "source" }. Tambahkan "pipeline" (nama atau id) supaya sekaligus jadi deal: "stage" (kosong = tahap pertama), "assignee" (email anggota), "title", "value", "description". Setiap kiriman dengan pipeline membuat deal baru |
| GET | /public/pipelines | Semua pipeline beserta tahapnya sesuai urutan papan (isWon, isLost) dan field deal-nya |
| GET | /public/deals | Daftar deal, yang terakhir berubah dulu. Filter: pipelineId, stageId, status (open, won, lost, disqualified), assigneeEmail, contactId, updatedSince, q (judul), limit, cursor. Tiap deal membawa hasEmail dan lastEmailAt |
| POST | /public/deals | Buat deal di pipeline: { "pipelineId", "title", "stageId", "value", "contactId", "companyId", "ownerUserId", "expectedCloseDate", "description" }. Butuh crm:write |
| GET | /public/deals/:id | Satu deal: kontak, tahap, nilai, pemilik, field kustom, label, alasan menang atau kalah, dan chat kontak itu |
| PATCH | /public/deals/:id | Pindah tahap, tandai menang atau kalah beserta alasannya, ubah nilai, perkiraan tutup, atau pemilik (email anggota) |
| GET | /public/deals/:id/notes | Catatan di deal, yang terbaru dulu |
| POST | /public/deals/:id/notes | Tulis catatan: { "body": "..." } |
| POST | /public/tasks | Buat tugas di sebuah deal: { "dealId", "title", "description", "dueAt", "assigneeEmail", "priority" } |
| GET | /public/deals/:id/emails | Email di deal, dari yang terlama, sebagai teks biasa. after=<nextCursor> dan limit untuk halaman berikutnya. held berisi email baru dari klien yang belum dimasukkan ke deal mana pun |
| GET | /public/mailboxes | Kotak surat yang bisa dipakai key ini untuk mengirim email deal |
| POST | /public/deals/:id/emails | Kirim email ke kontak deal: { "subject", "text", "replyToMessageId", "mailboxId" } |
| GET | /public/conversations/:id/drafts | Draf balasan dari API di percakapan itu, beserta nasibnya |
| POST | /public/conversations/:id/drafts | Siapkan draf balasan untuk disetujui tim: { "text": "...", "note": "..." }. Tidak mengirim apa pun |
| GET | /public/marketing/summary | Ringkasan iklan: belanja, lead, deal, dan biaya per lead. Periode: days (bawaan 30), atau since dan until (YYYY-MM-DD) |
| GET | /public/marketing/ad-sources | Sumber iklan (Google, Meta) beserta status sambungannya |
| GET | /public/marketing/ad-accounts | Akun iklan yang tersambung |
| GET | /public/marketing/ad-accounts/:id/report | Performa satu akun iklan. Periode seperti ringkasan |
| GET | /public/marketing/leads | Lead dari iklan beserta kontak dan hasilnya. Filter: days/since/until, source (google, meta, link, form), q, campaignId, linkId |
| GET | /public/marketing/audiences | Audiens khusus (Custom Audience). provider=google atau meta (bawaan google) |
| GET | /public/social/accounts | Akun media sosial yang tersambung beserta statusnya |
| GET | /public/social/posts | Postingan, terbaru dulu. Filter status (DRAFT, SCHEDULED, PUBLISHED, FAILED) |
| GET | /public/social/posts/:id | Satu postingan beserta statistiknya |
| GET | /public/social/posts/:id/comments | Komentar pada satu postingan |
| GET | /public/social/comments | Antrean komentar dan mention. unreplied=true untuk yang belum dibalas |
| GET | /public/social/analytics | Analitik akun untuk satu periode. days 7, 14, atau 30 (bawaan 14); jangkauan, tayangan, dan kunjungan profil dihitung untuk periode itu |
| POST | /public/social/posts | Buat atau jadwalkan postingan: { "caption", "accountIds" atau "platforms", "media", "scheduledAt" }. Butuh social:write |
| PATCH | /public/social/posts/:id | Ubah postingan. Butuh social:write |
| POST | /public/social/posts/:id/publish | Terbitkan draf atau yang terjadwal sekarang. Butuh social:write |
| DELETE | /public/social/posts/:id | Hapus postingan. Butuh social:write |
| POST | /public/social/posts/:id/approval | Setujui atau tolak: { "decision": "approve" atau "reject", "note" }. Butuh social:write |
| POST | /public/social/comments/:id/reply | Balas komentar atau mention: { "text" }. Butuh social:write |
| POST | /public/social/comments/:id/handled | Tandai selesai atau buka lagi: { "handled": true }. Butuh social:write |
| POST | /public/social/comments/handle-all | Tandai semua selesai. { "kind": "comment" atau "mention" } opsional. Butuh social:write |
| GET | /public/social/campaigns | Kampanye konten |
| POST, PATCH, DELETE | /public/social/campaigns(/:id) | Buat, ubah, hapus kampanye. Butuh social:write |
| GET | /public/social/saved-replies | Balasan tersimpan |
| POST, PATCH, DELETE | /public/social/saved-replies(/:id) | Buat, ubah, hapus balasan tersimpan. Butuh social:write |
| GET | /public/social/bio | Halaman link-in-bio |
| PUT | /public/social/bio | Simpan link-in-bio. Butuh social:write |
| POST | /public/social/accounts/:id/sync | Tarik ulang komentar dan DM satu akun. Butuh social:write |
| GET | /public/social/dm | Daftar percakapan DM |
| GET | /public/social/dm/:id | Satu percakapan DM |
| POST | /public/social/dm/:id/reply | Balas DM: { "text" }. Butuh social:write |
| POST | /public/social/dm/:id/handled | Tandai DM selesai: { "handled": true }. Butuh social:write |
| GET | /public/website/sites | Situs di workspace |
| GET | /public/website/sites/:id | Satu situs |
| GET | /public/website/sites/:id/overview | Ringkasan trafik situs. from, to, compare (none, previous, year) |
| GET | /public/website/sites/:id/pages | Halaman situs. sort, limit, groupId, q, plus rentang |
| GET | /public/website/sites/:id/keywords | Kata kunci pencarian. brand (all, brand, nonbrand), pageId, limit, plus rentang |
| GET | /public/website/sites/:id/audit | Temuan audit situs |
| GET | /public/website/sites/:id/opportunities | Peluang perbaikan situs |
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).
| Jenis | Format | Ukuran maksimal | Keterangan (caption) |
|---|---|---|---|
| Gambar | JPG, PNG | 5 MB | Bisa, maksimal 1.024 karakter |
| Stiker | WEBP | 500 KB | Tidak bisa |
| Video | MP4, 3GP | 16 MB | Bisa |
| Audio | AAC, AMR, MP3, M4A, OGG | 16 MB | Tidak bisa |
| Dokumen | PDF, Word, Excel, PowerPoint, TXT | 16 MB | Bisa. Nama file ikut tampil |
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.
Cakupan API key
Saat membuat key di Integrasi & API, pilih apa saja yang boleh dilakukannya. Cakupan ditetapkan sekali; butuh yang lain, buat key baru.
| Cakupan | Membuka |
|---|---|
read | Semua GET: pemakaian, percakapan, pesan, kontak, pipeline, deal, catatan, draf, email deal, kotak surat |
messages:send | Kirim teks, media, tombol, lokasi, template, handoff, bot, ubah status, dan template ke nomor baru |
contacts:write | Buat dan ubah kontak dan perusahaan, serta /public/leads |
crm:write | Buat deal (POST /deals), ubah deal (PATCH /deals/:id), tulis catatan deal, dan buat tugas |
drafts:write | Siapkan draf balasan (POST /conversations/:id/drafts). Tidak bisa mengirim |
email:send | Kirim email ke kontak deal (POST /deals/:id/emails). Email langsung terkirim |
social:write | Memposting, menjadwalkan, membalas komentar dan DM, kampanye, balasan tersimpan, dan link-in-bio di modul Social. Postingan benar-benar terbit |
Permintaan di luar cakupan ditolak 403 insufficient_scope beserta requiredScope, dan tidak dihitung ke kuota. Key yang dibuat sebelum ada cakupan, dan key yang dibuat tanpa memilih, punya tiga cakupan pertama. crm:write, drafts:write, email:send, dan social:write hanya ada di key yang dibuat dengan mencentangnya.
Setiap panggilan dengan key dicatat (waktu, metode, alamat tanpa query, hasil, lama proses, IP) dan bisa dilihat di halaman yang sama, 100 terakhir per key, disimpan 30 hari. Panggilan yang ditolak ikut tercatat, jadi “kenapa bot dapat 403 jam 09.14” bisa dijawab dari situ.
Menulis kontak
Bot yang belajar sesuatu dari percakapan (nomor polisi, cabang, minat) bisa menyimpannya ke kontak, dan membaca kembali lain waktu.
POST /public/contacts
{ "name": "Nur Hanifah", "phone": "0812-3456-7890", "email": "nur@klinik.test",
"notes": "Punya 3 cabang", "tags": ["Klinik", "Prospek panas"], "company": "Klinik Sehat Bersama" }
- Label dan perusahaan disebut dengan namanya, bukan id. Nama yang belum ada dibuat otomatis; huruf besar kecil tidak dibedakan, jadi
kliniktidak melahirkan kembaran dariKlinik. - Nomor disimpan dalam bentuk internasional (
0812...menjadi62812...), bentuk yang sama dengan yang ditulis WhatsApp, supaya kontak dari API dan dari chat masuk tidak jadi dua orang. - Nomor yang sudah dimiliki kontak lain ditolak
409 contact_existsbesertameta.existingId, jadi bot tinggalPATCHkontak itu. PATCHhanya mengubah kolom yang dikirim.tagsmengganti seluruh daftar label;"company": ""melepaskan perusahaan.- Kontak yang dibuat lewat API bersumber
api, dan otomasi kontak baru ikut jalan seperti biasa.
Membuka percakapan ke nomor baru
Yang bisa dikirim ke orang yang belum pernah chat hanya template yang disetujui Meta, sesuai aturan WhatsApp. Satu panggilan mengurus kontak, percakapan, dan pengirimannya.
POST /public/messages/template
{ "to": "0812-9999-0001", "name": "Budi", "templateName": "pengingat_servis",
"languageCode": "id", "parameters": ["Budi", "Sabtu 27 Sep"] }
Jawabannya berisi contactId, conversationId, penanda contactCreated dan conversationCreated, serta pesannya. Setelah itu percakapan dilanjutkan lewat endpoint /public/conversations/:id/... seperti biasa, dan balasan pelanggan datang lewat webhook message.received.
- Kalau orang itu sudah punya chat terbuka, template masuk ke chat yang sama, bukan membuka yang baru.
- Percakapan baru mengikuti aturan pembagian agen workspace, jadi sejak pesan pertama sudah ada yang memegang.
whatsappNumberIdmemilih nomor pengirim; tanpa itu dipakai nomor bawaan.- Header media dan aturan isian sama dengan
/conversations/:id/template. - Pelanggan yang sudah membalas STOP ditolak
403 contact_opted_out. Permintaan berhenti itu milik pelanggan, dan laporan spam jatuh ke nomor Anda, bukan ke bot.
Agen penjualan AI: pipeline dan draf balasan
Agen penjualan buatan Anda bisa membaca dan mengurus pipeline, lalu mengusulkan balasan WhatsApp yang dikirim oleh tim. Untuk agen seperti ini, buat key dengan cakupan read, crm:write, dan drafts:write saja, tanpa messages:send, supaya agen tidak bisa mengirim pesan sendiri.
Key berlaku untuk seluruh workspace: agen melihat semua pipeline dan deal, termasuk pipeline yang aksesnya dibatasi untuk anggota tertentu. Orang disebut dengan email anggota workspace. Id yang bukan milik workspace pemilik key ditolak 404, email yang bukan anggota ditolak 400.
Mengubah deal.
PATCH /public/deals/:id
{ "stageId": "<id tahap Kalah>", "lostReason": "PRICE", "lostReasonNote": "Pilih yang lebih murah" }
stageIdharus tahap di pipeline deal itu. Pindah tahap lewat API sama seperti menggeser kartu di papan: riwayat deal, notifikasi ke pemilik, otomasi deal pindah tahap, dan laporan konversi iklan ikut berjalan. Tahap menang atau kalah menutup deal.status(open,won,lost) menandai deal tanpa memindahkan kartunya, sama seperti tombol di halaman deal.statusyang bertentangan dengan tahap tujuan ditolak400 status_conflicts_with_stage.lostReason:PRICE,COMPETITOR,NO_BUDGET,NO_RESPONSE,TIMING,NOT_A_FIT,OTHER.wonReason:PRICE,RELATIONSHIP,PRODUCT_FIT,SPEED,REFERRAL,OTHER. Alasan hanya untuk deal yang memang kalah atau menang (400 reason_needs_status).value(rupiah, bilangan bulat),expectedCloseDate(ISO 8601), danassigneeEmail(pemilik deal;nullberarti tanpa pemilik).- Semua isian diperiksa dulu. Kalau satu salah, tidak ada yang berubah. Jawabannya berisi deal setelah diubah.
- Di riwayat deal, perubahan dari API tertulis atas nama API (nama key).
Catatan dan tugas. POST /public/deals/:id/notes menulis catatan di deal atas nama key. POST /public/tasks membuat tugas di sebuah deal, sama seperti bagian Tugas & tindak lanjut di halaman deal: tugas masuk ke papan CRM / Aktivitas dan tampil di deal. Tugas selalu terikat ke deal; tugas yang hanya terikat ke kontak belum didukung. Pembuat tugas dicatat sebagai orang yang membuat key, atau pemilik workspace bila orang itu sudah keluar.
Draf balasan.
POST /public/conversations/:id/drafts
{ "text": "Paket Dasar Rp99.000 per bulan, Kak. Mau saya kirimkan contohnya?", "note": "Pelanggan tanya harga" }
- Draf muncul di inbox di atas kotak ketik, berlabel Draf dari API: nama key. Tim memilih Kirim, Pakai (ubah dulu), atau Abaikan. Draf tampil walaupun aplikasi Sobat Karib tidak dipasang.
- API tidak mengirim apa pun. Pengiriman terjadi saat orang di tim menekan kirim, lewat jalur biasa, jadi aturan jendela 24 jam dan lainnya berlaku saat itu. Draf tidak memakai kredit Sobat.
- Hanya untuk percakapan WhatsApp (
400 unsupported_channel). Draf baru menggantikan draf API yang masih menunggu di chat yang sama. Maksimal 30 draf per percakapan dalam 24 jam (429 draft_limit). GET /public/conversations/:id/draftsmenunjukkan nasib tiap draf distatus:pending,sent(dikirim apa adanya),edited(diubah dulu, teks yang dikirim ada disentText),dismissed, ataureplaced.stale: trueberarti draf masih menunggu tetapi tim sudah membalas chat itu, sehingga draf tidak ditampilkan lagi.
Agen penjualan AI: email di deal
Agen juga bisa membaca email di sebuah deal dan membalas klien, sama seperti tab Email di halaman deal. Membaca cukup dengan read. Mengirim butuh cakupan email:send, dan email langsung terkirim tanpa persetujuan tim, jadi centang hanya kalau agen memang boleh menulis ke klien sendiri.
Membaca. GET /public/deals/:id/emails mengembalikan email masuk dan keluar dari yang terlama. Tiap email berisi id, direction (in atau out), from, to, cc, subject, text (isi sebagai teks biasa, termasuk kutipan email sebelumnya), sentAt, messageId, threadId, attachments, sentBy (anggota yang mengirim dari halaman deal), dan viaApi. Kalau masih ada email lagi, nextCursor berisi id untuk after. held berisi email baru dari klien deal itu yang belum dimasukkan ke deal mana pun, persis pemberitahuan di halaman deal. Email seperti itu dipilihkan dealnya oleh tim di aplikasi dan belum bisa dibalas lewat API.
Mengirim.
POST /public/deals/:id/emails
{ "text": "Paket tahunan Rp990.000, Pak. Mau saya kirimkan penawarannya?",
"replyToMessageId": "<id email dari GET /deals/:id/emails>" }
- Tujuannya selalu email kontak deal itu. API tidak bisa mengirim ke alamat lain.
textditulis sebagai teks biasa; baris kosong memulai paragraf baru. Tanda tangan email dipasang otomatis, sama seperti dari halaman deal.- Dengan
replyToMessageId, email masuk ke utas yang sama (headerIn-Reply-TodanReferences, juga utas Gmail), email yang dibalas ikut dikutip di bawahnya, dansubjectboleh kosong (menjadiRe: ...). Email baru wajib punyasubject. - Tanpa
mailboxId, email dikirim dari kotak surat yang juga dipakai halaman deal: kotak surat milik pembuat key dulu, lalu kotak surat bersama workspace.GET /public/mailboxesmenunjukkan pilihannya besertaisDefaultdanconnected. Kotak surat pribadi anggota lain tidak bisa dipakai. - Kalau tidak ada kotak surat sama sekali, email dikirim atas nama bisnis Anda lewat pengirim Karibin (nama bisnis via Karibin), sama seperti dari halaman deal. Di daftar kotak surat, pilihan ini muncul dengan id
platform. - Email tercatat di tab Email dan riwayat deal atas nama API (nama key), dan balasan klien sampai ke deal dengan cara yang sama seperti email dari halaman deal.
- Batas harian per alamat pengirim sama dengan follow-up otomatis, dihitung bersama email yang dikirim tim dari alamat itu (
429 email_daily_limit). - Kontak yang sudah berhenti berlangganan email tidak bisa dikirimi email baru (
403 contact_opted_out), tetapi email yang ia kirim tetap bisa dibalas.
Marketing: tarik data iklan
Modul Marketing terbuka lewat API hanya untuk dibaca, supaya hasil iklan bisa ditarik ke dasbor, gudang data, atau automasi Anda sendiri. Semua endpoint butuh cakupan read dan ikut kuota yang sama.
GET /public/marketing/summarymemberi belanja, jumlah lead, deal, dan biaya per lead untuk periode yang dipilih (?days=30, atau?since=2026-10-01&until=2026-10-31).GET /public/marketing/ad-accountsmemberi akun iklan yang tersambung;GET /public/marketing/ad-accounts/<id>/reportmemberi performa satu akun. Id akun dari workspace lain dijawab404 ad_account_not_found.GET /public/marketing/leadsmemberi lead yang dibawa iklan beserta kontak dan hasilnya (lead, menang), dengan saringan sumber dan kampanye.GET /public/marketing/audiences?provider=googlememberi audiens khusus yang dibangun dari CRM.
Semua angka bersifat tingkat workspace, sama seperti yang dilihat pemilik di aplikasi. Membuat atau mengubah iklan, audiens, atau aturan konversi belum dibuka lewat API.
Social: kelola media sosial (baca dan tulis)
Modul Social terbuka penuh lewat API, dibuat agar agen AI dari luar bisa menjalankan media sosial workspace Anda dari ujung ke ujung. Membaca cukup cakupan read; menulis (memposting, menjadwalkan, membalas, dan seterusnya) butuh cakupan social:write dan langganan aktif. Semua ikut kuota yang sama, dan id dari workspace lain dijawab 404.
Membaca: GET /public/social/accounts (akun tersambung), /posts (bisa ?status=PUBLISHED) dan /posts/<id> beserta statistik, /posts/<id>/comments, /comments (antrean komentar dan mention, ?unreplied=true), /analytics?days=14, /campaigns, /saved-replies, /bio, dan /dm beserta /dm/<id>.
Menulis (butuh social:write):
- Postingan:
POST /public/social/postsmembuat atau menjadwalkan (isicaption,accountIdsatauplatforms,media, danscheduledAt; kosongkanscheduledAtuntuk draf, isi waktu akan datang untuk menjadwalkan). Lalu.../publish,PATCH .../<id>,DELETE .../<id>, dan.../<id>/approvaluntuk menyetujui atau menolak. - Komentar dan mention:
.../comments/<id>/reply,.../comments/<id>/handled,.../comments/handle-all. - Kampanye, balasan tersimpan, link-in-bio: buat, ubah, hapus (
PUT /public/social/biountuk bio). - DM:
.../dm/<id>/replydan.../dm/<id>/handled. - Sinkron:
.../accounts/<id>/syncmenarik ulang komentar dan DM.
Menyambungkan dan memutus akun tetap di aplikasi, karena prosesnya login (OAuth) yang interaktif.
Website: tarik performa situs
Modul Website terbuka lewat API hanya untuk dibaca, dengan cakupan read dan kuota yang sama.
GET /public/website/sitesmemberi situs di workspace;GET /public/website/sites/<id>satu situs. Id dari workspace lain dijawab404 site_not_found.GET /public/website/sites/<id>/overviewmemberi ringkasan trafik untuk satu periode (?from=2026-10-01&to=2026-10-31,?compare=previous).GET /public/website/sites/<id>/pagesdan.../keywordsmemberi performa per halaman dan per kata kunci;.../audittemuan audit;.../opportunitiespeluang perbaikan.
Menyambungkan Search Console, menambah situs, dan menjalankan sinkronisasi tetap di aplikasi.
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. Chatbot dan otomasi pesan masuk tidak ikut menjawab. - Bot membaca pesan lewat webhook
message.received, lalu membalas lewatPOST /messages. - Bot menyerahkan chat ke manusia dengan
POST /handoff. TanpaagentId, 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.
| Kejadian | Kapan |
|---|---|
message.received | Pesan pelanggan masuk (termasuk yang masuk ke HP lewat mode nomor tetap di HP) |
message.sent | Pesan keluar. origin: agent, api, automation, phone, atau system |
message.status | Terkirim, sampai, dibaca, atau gagal (dengan failCode) |
conversation.handoff | Chat diserahkan ke agen. reason: api, agent_replied, bot_timeout |
conversation.bot | Bot mengambil (kembali) chat |
conversation.status | Status percakapan berubah. status = kategori (OPEN, PENDING, RESOLVED, CLOSED), statusName = nama status kustom workspace (mis. “Sedang dikerjakan”) atau null |
Contoh isi kiriman dan cara memeriksa tanda tangan
{
"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 }
}
}Setiap kiriman membawa header X-Karibin-Signature: sha256=<hex>, yaitu HMAC SHA-256 dari isi mentah dengan rahasia webhook Anda, serta X-Karibin-Delivery yang bisa dipakai untuk menolak kiriman ganda.
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();Untuk menolak kiriman yang diputar ulang, tolak kiriman yang createdAt-nya lebih dari 5 menit lalu (nilainya ikut ditandatangani) dan simpan id yang sudah diterima supaya kiriman ganda diabaikan.
Balas dengan status 2xx dalam 10 detik. Kalau gagal, Karibin mencoba lagi sampai 8 kali dalam sekitar satu jam. Alamat yang gagal terus 50 kiriman berturut-turut dimatikan otomatis, dan bisa diaktifkan lagi dari halaman pengaturan. Riwayat kiriman 30 hari terakhir ada di tombol Riwayat.
Kuota, batas, dan kesalahan
| Respons | Artinya |
|---|---|
401 invalid_api_key | Key salah atau sudah dicabut |
403 insufficient_scope | Key ini tidak punya cakupan untuk permintaan itu; requiredScope menyebut yang dibutuhkan |
429 rate_limited | Lebih dari 10 permintaan per detik per workspace. Coba lagi sebentar |
429 too_many_failed_requests | Terlalu banyak permintaan gagal dari satu alamat IP dalam semenit (misalnya key salah). Coba lagi 1 menit kemudian |
429 api_quota_exceeded | Kuota bulan ini habis (sudah termasuk kelonggaran 10%). Tambah kuota di Tagihan |
402 subscription_readonly | Langganan tidak aktif; membaca tetap bisa, mengirim tidak |
404 conversation_not_found, 404 contact_not_found, 404 deal_not_found, 404 pipeline_not_found, 404 stage_not_found | Id tidak ada di workspace pemilik key (atau tahap bukan milik pipeline deal itu) |
400 assignee_not_found, 400 owner_not_found | Email bukan anggota workspace |
400 invalid_cursor | cursor (atau after di email deal) bukan dari halaman sebelumnya di workspace ini |
400 status_conflicts_with_stage, 400 reason_needs_status | Status tidak cocok dengan tahap tujuan, atau alasan untuk deal yang tidak kalah atau menang |
429 draft_limit | Sudah 30 draf di percakapan itu dalam 24 jam |
404 message_not_found, 404 mailbox_not_found | Email yang dibalas tidak ada di deal itu, atau kotak surat tidak bisa dipakai key ini |
409 deal_has_no_contact, 409 contact_has_no_email | Deal tanpa kontak, atau kontaknya belum punya alamat email yang benar |
400 subject_required | Email baru tanpa subject |
409 mailbox_not_connected | Kotak surat terputus. Sambungkan lagi di aplikasi |
429 email_daily_limit | Batas email harian dari alamat pengirim itu sudah tercapai. Coba lagi besok |
409 contact_exists | Nomor sudah dimiliki kontak lain; meta.existingId menyebut kontaknya |
403 contact_opted_out | Pelanggan sudah membalas STOP, tidak bisa dikirimi lewat API. Untuk email: kontak sudah berhenti berlangganan email, hanya email darinya yang bisa dibalas |
404 whatsapp_number_not_found | whatsappNumberId bukan nomor di workspace ini |
400 invalid_phone | Nomor tujuan bukan nomor telepon |
409 window_closed | Di luar jendela 24 jam. Pakai template |
409 whatsapp_not_connected | Nomor WhatsApp percakapan itu belum tersambung ke Karibin |
400 unsupported_channel | Bukan percakapan WhatsApp |
415 unsupported_media_type, 415 content_type_mismatch | Jenis file tidak didukung, atau isinya tidak cocok dengan tipenya |
413 file_too_large | Melebihi ukuran maksimal jenis file itu |
400 caption_not_supported | Audio dan stiker tidak bisa diberi keterangan |
400 media_url_not_allowed, 422 media_url_unreachable, 422 media_url_redirect | Alamat file tidak diizinkan, tidak bisa diunduh, atau mengalihkan |
404 template_not_found, 409 template_not_approved | Template tidak ada di nomor itu, atau belum disetujui |
400 template_params_mismatch, 400 template_param_invalid | Jumlah isian salah, atau isian berisi baris baru, tab, atau spasi berlebih |
400 template_header_required, template_header_type_mismatch, template_has_no_media_header | Header tidak sesuai template |
503 templates_unavailable | Daftar template sedang tidak bisa dibaca dari WhatsApp. Coba lagi |
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).
| Kuota per bulan | Harga |
|---|---|
| 1.000 panggilan, termasuk semua paket | Rp0 |
| +10.000 panggilan | Rp349.000 |
| +100.000 panggilan | Rp1.990.000 |
| +1.000.000 panggilan | Rp4.900.000 |