Untuk developer

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

  1. Buka Pengaturan, lalu Integrasi & API, dan buat API key. Simpan key-nya, karena hanya ditampilkan sekali.
  2. Kirim permintaan dengan header x-api-key: krbn_live_... ke alamat dasar https://karibin.com/api/v1/public.
  3. 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

MetodeAlamatKegunaan
GET/public/usagePemakaian kuota bulan ini
GET/public/conversationsDaftar percakapan. Filter: status, bot=true, updatedSince, limit, cursor
GET/public/conversations/:idSatu percakapan beserta kontaknya. status berisi kategori, statusName nama status kustom workspace bila ada
GET/public/conversations/:id/messagesPesan dari yang terlama. after=<id pesan> untuk membaca yang baru saja
POST/public/conversations/:id/messagesKirim teks: { "text": "...", "replyToId": "..." }
POST/public/conversations/:id/mediaKirim gambar, video, audio, dokumen, atau stiker. Unggah file, atau { "url": "https://..." }
POST/public/conversations/:id/interactiveKirim 1 sampai 3 tombol, atau daftar 1 sampai 10 pilihan
POST/public/conversations/:id/locationKirim lokasi: { "latitude", "longitude", "name", "address" }
POST/public/conversations/:id/templateKirim template yang disetujui Meta, termasuk template ber-header gambar, video, atau dokumen
POST/public/conversations/:id/handoffSerahkan ke agen: { "agentId": "...", "note": "..." } (keduanya opsional)
POST/public/conversations/:id/botBot mengambil (kembali) percakapan
PATCH/public/conversations/:idUbah 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/contactsTanpa 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/:idSatu kontak beserta label, perusahaan, catatan, dan status broadcast
POST/public/contactsBuat kontak: { "name", "phone", "email", "notes", "tags": ["..."], "company": "..." }
PATCH/public/contacts/:idUbah kolom yang dikirim saja. tags mengganti seluruh label
GET/public/companiesDaftar perusahaan. Saring nama dengan q
GET/public/companies/:idSatu perusahaan beserta jumlah kontak dan deal
POST/public/companiesBuat perusahaan: { "name", "website", "phone", "industry", "address", "notes" }. Butuh contacts:write
PATCH/public/companies/:idUbah kolom yang dikirim saja. Butuh contacts:write
DELETE/public/companies/:idHapus perusahaan (kontak dan deal-nya tetap ada). Butuh contacts:write
POST/public/messages/templateKirim template ke nomor mana pun, termasuk yang belum pernah chat. Kontak dan percakapannya dibuat sendiri
POST/public/leadsSalurkan 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/pipelinesSemua pipeline beserta tahapnya sesuai urutan papan (isWon, isLost) dan field deal-nya
GET/public/dealsDaftar 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/dealsBuat deal di pipeline: { "pipelineId", "title", "stageId", "value", "contactId", "companyId", "ownerUserId", "expectedCloseDate", "description" }. Butuh crm:write
GET/public/deals/:idSatu deal: kontak, tahap, nilai, pemilik, field kustom, label, alasan menang atau kalah, dan chat kontak itu
PATCH/public/deals/:idPindah tahap, tandai menang atau kalah beserta alasannya, ubah nilai, perkiraan tutup, atau pemilik (email anggota)
GET/public/deals/:id/notesCatatan di deal, yang terbaru dulu
POST/public/deals/:id/notesTulis catatan: { "body": "..." }
POST/public/tasksBuat tugas di sebuah deal: { "dealId", "title", "description", "dueAt", "assigneeEmail", "priority" }
GET/public/deals/:id/emailsEmail 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/mailboxesKotak surat yang bisa dipakai key ini untuk mengirim email deal
POST/public/deals/:id/emailsKirim email ke kontak deal: { "subject", "text", "replyToMessageId", "mailboxId" }
GET/public/conversations/:id/draftsDraf balasan dari API di percakapan itu, beserta nasibnya
POST/public/conversations/:id/draftsSiapkan draf balasan untuk disetujui tim: { "text": "...", "note": "..." }. Tidak mengirim apa pun
GET/public/marketing/summaryRingkasan iklan: belanja, lead, deal, dan biaya per lead. Periode: days (bawaan 30), atau since dan until (YYYY-MM-DD)
GET/public/marketing/ad-sourcesSumber iklan (Google, Meta) beserta status sambungannya
GET/public/marketing/ad-accountsAkun iklan yang tersambung
GET/public/marketing/ad-accounts/:id/reportPerforma satu akun iklan. Periode seperti ringkasan
GET/public/marketing/leadsLead dari iklan beserta kontak dan hasilnya. Filter: days/since/until, source (google, meta, link, form), q, campaignId, linkId
GET/public/marketing/audiencesAudiens khusus (Custom Audience). provider=google atau meta (bawaan google)
GET/public/social/accountsAkun media sosial yang tersambung beserta statusnya
GET/public/social/postsPostingan, terbaru dulu. Filter status (DRAFT, SCHEDULED, PUBLISHED, FAILED)
GET/public/social/posts/:idSatu postingan beserta statistiknya
GET/public/social/posts/:id/commentsKomentar pada satu postingan
GET/public/social/commentsAntrean komentar dan mention. unreplied=true untuk yang belum dibalas
GET/public/social/analyticsAnalitik akun untuk satu periode. days 7, 14, atau 30 (bawaan 14); jangkauan, tayangan, dan kunjungan profil dihitung untuk periode itu
POST/public/social/postsBuat atau jadwalkan postingan: { "caption", "accountIds" atau "platforms", "media", "scheduledAt" }. Butuh social:write
PATCH/public/social/posts/:idUbah postingan. Butuh social:write
POST/public/social/posts/:id/publishTerbitkan draf atau yang terjadwal sekarang. Butuh social:write
DELETE/public/social/posts/:idHapus postingan. Butuh social:write
POST/public/social/posts/:id/approvalSetujui atau tolak: { "decision": "approve" atau "reject", "note" }. Butuh social:write
POST/public/social/comments/:id/replyBalas komentar atau mention: { "text" }. Butuh social:write
POST/public/social/comments/:id/handledTandai selesai atau buka lagi: { "handled": true }. Butuh social:write
POST/public/social/comments/handle-allTandai semua selesai. { "kind": "comment" atau "mention" } opsional. Butuh social:write
GET/public/social/campaignsKampanye konten
POST, PATCH, DELETE/public/social/campaigns(/:id)Buat, ubah, hapus kampanye. Butuh social:write
GET/public/social/saved-repliesBalasan tersimpan
POST, PATCH, DELETE/public/social/saved-replies(/:id)Buat, ubah, hapus balasan tersimpan. Butuh social:write
GET/public/social/bioHalaman link-in-bio
PUT/public/social/bioSimpan link-in-bio. Butuh social:write
POST/public/social/accounts/:id/syncTarik ulang komentar dan DM satu akun. Butuh social:write
GET/public/social/dmDaftar percakapan DM
GET/public/social/dm/:idSatu percakapan DM
POST/public/social/dm/:id/replyBalas DM: { "text" }. Butuh social:write
POST/public/social/dm/:id/handledTandai DM selesai: { "handled": true }. Butuh social:write
GET/public/website/sitesSitus di workspace
GET/public/website/sites/:idSatu situs
GET/public/website/sites/:id/overviewRingkasan trafik situs. from, to, compare (none, previous, year)
GET/public/website/sites/:id/pagesHalaman situs. sort, limit, groupId, q, plus rentang
GET/public/website/sites/:id/keywordsKata kunci pencarian. brand (all, brand, nonbrand), pageId, limit, plus rentang
GET/public/website/sites/:id/auditTemuan audit situs
GET/public/website/sites/:id/opportunitiesPeluang 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).

JenisFormatUkuran maksimalKeterangan (caption)
GambarJPG, PNG5 MBBisa, maksimal 1.024 karakter
StikerWEBP500 KBTidak bisa
VideoMP4, 3GP16 MBBisa
AudioAAC, AMR, MP3, M4A, OGG16 MBTidak bisa
DokumenPDF, Word, Excel, PowerPoint, TXT16 MBBisa. 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.

CakupanMembuka
readSemua GET: pemakaian, percakapan, pesan, kontak, pipeline, deal, catatan, draf, email deal, kotak surat
messages:sendKirim teks, media, tombol, lokasi, template, handoff, bot, ubah status, dan template ke nomor baru
contacts:writeBuat dan ubah kontak dan perusahaan, serta /public/leads
crm:writeBuat deal (POST /deals), ubah deal (PATCH /deals/:id), tulis catatan deal, dan buat tugas
drafts:writeSiapkan draf balasan (POST /conversations/:id/drafts). Tidak bisa mengirim
email:sendKirim email ke kontak deal (POST /deals/:id/emails). Email langsung terkirim
social:writeMemposting, 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.

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 klinik tidak melahirkan kembaran dari Klinik.
  • Nomor disimpan dalam bentuk internasional (0812... menjadi 62812...), 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_exists beserta meta.existingId, jadi bot tinggal PATCH kontak itu.
  • PATCH hanya mengubah kolom yang dikirim. tags mengganti 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.
  • whatsappNumberId memilih 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" }
  • stageId harus 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. status yang bertentangan dengan tahap tujuan ditolak 400 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), dan assigneeEmail (pemilik deal; null berarti 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/drafts menunjukkan nasib tiap draf di status: pending, sent (dikirim apa adanya), edited (diubah dulu, teks yang dikirim ada di sentText), dismissed, atau replaced. stale: true berarti 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.
  • text ditulis 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 (header In-Reply-To dan References, juga utas Gmail), email yang dibalas ikut dikutip di bawahnya, dan subject boleh kosong (menjadi Re: ...). Email baru wajib punya subject.
  • 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/mailboxes menunjukkan pilihannya beserta isDefault dan connected. 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/summary memberi 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-accounts memberi akun iklan yang tersambung; GET /public/marketing/ad-accounts/<id>/report memberi performa satu akun. Id akun dari workspace lain dijawab 404 ad_account_not_found.
  • GET /public/marketing/leads memberi lead yang dibawa iklan beserta kontak dan hasilnya (lead, menang), dengan saringan sumber dan kampanye.
  • GET /public/marketing/audiences?provider=google memberi 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/posts membuat atau menjadwalkan (isi caption, accountIds atau platforms, media, dan scheduledAt; kosongkan scheduledAt untuk draf, isi waktu akan datang untuk menjadwalkan). Lalu .../publish, PATCH .../<id>, DELETE .../<id>, dan .../<id>/approval untuk 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/bio untuk bio).
  • DM: .../dm/<id>/reply dan .../dm/<id>/handled.
  • Sinkron: .../accounts/<id>/sync menarik 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/sites memberi situs di workspace; GET /public/website/sites/<id> satu situs. Id dari workspace lain dijawab 404 site_not_found.
  • GET /public/website/sites/<id>/overview memberi ringkasan trafik untuk satu periode (?from=2026-10-01&to=2026-10-31, ?compare=previous).
  • GET /public/website/sites/<id>/pages dan .../keywords memberi performa per halaman dan per kata kunci; .../audit temuan audit; .../opportunities peluang 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 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.

KejadianKapan
message.receivedPesan pelanggan masuk (termasuk yang masuk ke HP lewat mode nomor tetap di HP)
message.sentPesan keluar. origin: agent, api, automation, phone, atau system
message.statusTerkirim, sampai, dibaca, atau gagal (dengan failCode)
conversation.handoffChat diserahkan ke agen. reason: api, agent_replied, bot_timeout
conversation.botBot mengambil (kembali) chat
conversation.statusStatus 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

ResponsArtinya
401 invalid_api_keyKey salah atau sudah dicabut
403 insufficient_scopeKey ini tidak punya cakupan untuk permintaan itu; requiredScope menyebut yang dibutuhkan
429 rate_limitedLebih dari 10 permintaan per detik per workspace. Coba lagi sebentar
429 too_many_failed_requestsTerlalu banyak permintaan gagal dari satu alamat IP dalam semenit (misalnya key salah). Coba lagi 1 menit kemudian
429 api_quota_exceededKuota bulan ini habis (sudah termasuk kelonggaran 10%). Tambah kuota di Tagihan
402 subscription_readonlyLangganan 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_foundId tidak ada di workspace pemilik key (atau tahap bukan milik pipeline deal itu)
400 assignee_not_found, 400 owner_not_foundEmail bukan anggota workspace
400 invalid_cursorcursor (atau after di email deal) bukan dari halaman sebelumnya di workspace ini
400 status_conflicts_with_stage, 400 reason_needs_statusStatus tidak cocok dengan tahap tujuan, atau alasan untuk deal yang tidak kalah atau menang
429 draft_limitSudah 30 draf di percakapan itu dalam 24 jam
404 message_not_found, 404 mailbox_not_foundEmail yang dibalas tidak ada di deal itu, atau kotak surat tidak bisa dipakai key ini
409 deal_has_no_contact, 409 contact_has_no_emailDeal tanpa kontak, atau kontaknya belum punya alamat email yang benar
400 subject_requiredEmail baru tanpa subject
409 mailbox_not_connectedKotak surat terputus. Sambungkan lagi di aplikasi
429 email_daily_limitBatas email harian dari alamat pengirim itu sudah tercapai. Coba lagi besok
409 contact_existsNomor sudah dimiliki kontak lain; meta.existingId menyebut kontaknya
403 contact_opted_outPelanggan 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_foundwhatsappNumberId bukan nomor di workspace ini
400 invalid_phoneNomor tujuan bukan nomor telepon
409 window_closedDi luar jendela 24 jam. Pakai template
409 whatsapp_not_connectedNomor WhatsApp percakapan itu belum tersambung ke Karibin
400 unsupported_channelBukan percakapan WhatsApp
415 unsupported_media_type, 415 content_type_mismatchJenis file tidak didukung, atau isinya tidak cocok dengan tipenya
413 file_too_largeMelebihi ukuran maksimal jenis file itu
400 caption_not_supportedAudio dan stiker tidak bisa diberi keterangan
400 media_url_not_allowed, 422 media_url_unreachable, 422 media_url_redirectAlamat file tidak diizinkan, tidak bisa diunduh, atau mengalihkan
404 template_not_found, 409 template_not_approvedTemplate tidak ada di nomor itu, atau belum disetujui
400 template_params_mismatch, 400 template_param_invalidJumlah isian salah, atau isian berisi baris baru, tab, atau spasi berlebih
400 template_header_required, template_header_type_mismatch, template_has_no_media_headerHeader tidak sesuai template
503 templates_unavailableDaftar 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 bulanHarga
1.000 panggilan, termasuk semua paketRp0
+10.000 panggilanRp349.000
+100.000 panggilanRp1.990.000
+1.000.000 panggilanRp4.900.000