API Kareeb: CRM (2026-11-04)

Organisasi dan izin token yang dikirim di header, untuk diperiksa saat sistem Anda pertama kali tersambung. Hanya menerima token API; sesi operator ditolak dengan 403. Daftar scopes mengikuti urutan tetap daftar izin, apa pun urutan saat token dibuat. Token, hash, dan awalannya tidak pernah dikembalikan. Panggilan ini tercatat sebagai pemakaian token.

Izin: tidak perlu izin khusus, cukup token yang masih aktif.

Template yang boleh disebut saat mengirim, dari salinan template Meta di Kareeb. Semua status ikut; hanya APPROVED yang bisa dikirim. Tidak berhalaman, paling banyak 500 baris. Template di akun WhatsApp yang tidak lagi dipakai organisasi, dan template di akun yang tidak dipakai cabang mana pun, tidak ditampilkan. Komponen template, id Meta, dan id akun WhatsApp tidak pernah ikut. Daftar ini sesegar sinkronisasi template terakhir; token tidak bisa memulai sinkronisasi, admin melakukannya dari menu Template. Jawaban dikirim dengan Cache-Control: no-store.

Izin: read:templates.

Membuat kampanye bertanda source=api di antrean yang sama dengan kampanye dari layar, sehingga muncul di halaman Kampanye lengkap dengan corongnya. Hanya WhatsApp. Penerima yang belum ada menjadi kontak baru. Pengiriman berangkat dari cabang Utama. Dengan scheduled_at, kampanye menunggu sampai waktu itu lalu dijalankan oleh penjadwal Kareeb. Kunci idempotency_key yang sama dijawab 200 dengan kampanye pertama dan tidak mengirim apa pun lagi. Permintaan yang ditolak 422 tidak membuat apa pun, sehingga kuncinya tetap bebas dipakai ulang.

Izin: send:broadcast.

Satu teks (hanya di dalam jendela 24 jam) atau satu template yang sudah disetujui, ke satu pelanggan WhatsApp. Isi tepat satu dari to atau contact_id, dan tepat satu dari text atau template. Pemeriksaan berjalan berurutan: batas permintaan per token, kunci, cabang, tujuan, saluran, berhenti berlangganan, lalu jendela 24 jam untuk teks atau syarat template. Pesan tercatat tanpa nama pengirim, ditandai sebagai kiriman API, dan tidak mengambil alih percakapan dari Agen AI. Status kirim selanjutnya datang lewat webhook message.status.

Izin: write:messages.

Kontak beserta status berhenti berlangganan dan persetujuan terbaru per tujuan. Token API membaca data cabang Utama organisasi Anda. Kontak bisa berubah (label, nama), jadi jalankan jalan penuh dari since_id=0 secara berkala. Kursor id hanya melihat baris baru, tidak melihat perubahan pada baris lama. Lihat panduan Tarik data untuk aturan jalan penuh.

Izin: read:contacts.

Percakapan per kontak dan saluran. Token API membaca data cabang Utama organisasi Anda. Status percakapan bisa berubah, jadi jalankan jalan penuh secara berkala. Kursor id hanya melihat baris baru, tidak melihat perubahan pada baris lama. Lihat panduan Tarik data untuk aturan jalan penuh.

Izin: read:conversations.

Pesan masuk dan keluar beserta status kirim terbaiknya. Mencakup semua cabang organisasi. Isi mentah dari Meta tidak ikut. Tabel ini hanya bertambah, jadi jalan bertahap dengan since_id sudah cukup.

Izin: read:messages.

Kampanye dari layar Kampanye dan dari POST /api/broadcasts. Token API membaca data cabang Utama organisasi Anda. Status kampanye berubah selama pengiriman, jadi jalankan jalan penuh secara berkala. Kursor id hanya melihat baris baru, tidak melihat perubahan pada baris lama. Lihat panduan Tarik data untuk aturan jalan penuh.

Izin: read:campaigns.

Satu baris per kampanye dengan angka corong yang sama dengan halaman Laporan. Angkanya berubah setiap kali penerima bereaksi, jadi endpoint ini selalu dibaca dengan jalan penuh dari since_id=0. Token API membaca data cabang Utama organisasi Anda.

Izin: read:campaigns.

Corong per penerima: terkirim, sampai, dibaca, dibalas, diklik, menghasilkan pesanan. Kursornya sendiri, terpisah dari daftar kampanye. Token API membaca data cabang Utama organisasi Anda.

Izin: read:campaigns.

Pesanan yang dibuat di percakapan. Tautan pembayaran tidak ikut. Token API membaca data cabang Utama organisasi Anda. Status pesanan berubah (misalnya menjadi paid), jadi jalankan jalan penuh secara berkala. Kursor id hanya melihat baris baru, tidak melihat perubahan pada baris lama. Lihat panduan Tarik data untuk aturan jalan penuh.

Izin: read:orders.

Komentar masuk di unggahan Instagram dan Halaman Facebook milik organisasi. Amplopnya sendiri: next_since_id berisi id terakhir hanya bila halaman penuh, dan null bila halaman tidak penuh atau kosong. Berhenti saat null, lalu simpan id terbesar yang Anda terima sebagai since_id berikutnya. Saluran yang sakelar komentar sebagai lead-nya mati tidak mengekspor apa pun, termasuk komentar yang tersimpan saat sakelar masih menyala. Token API membaca data cabang Utama organisasi Anda.

Izin: read:comments.

Satu kontak menurut id, tanpa kursor dan tanpa halaman. Berguna untuk mencocokkan satu baris tanpa menelusuri seluruh daftar. Kolom persetujuan tidak ada di sini; bacalah dari GET /api/export/contacts. Token API membaca data cabang Utama organisasi Anda.

Izin: read:contacts.

Sistem pemantauan Anda mengirim satu sebutan publik tentang merek (komentar YouTube, unggahan Threads, ulasan Google). Sebutan muncul di halaman Pemantauan cabang Utama, tempat agen CS menanganinya. Ini bukan percakapan, bukan kontak, dan tidak bisa dipakai untuk broadcast. Kunci idempotensinya adalah pasangan sumber dan external_id: kiriman ulang dijawab 200 tanpa menimpa apa pun. Hanya menerima token API; sesi operator ditolak dengan 403. Badan paling besar 16 KB.

Izin: write:pemantauan.

Menghapus teks, penulis, penulis_ref, dan url satu sebutan; barisnya, id, dan statusnya tetap. Pakai saat platform menghapus komentar itu atau masa simpan sistem Anda habis. Aman diulang: sebutan yang tidak dikenal dijawab 200 dengan ditemukan false. Tetap berjalan untuk organisasi yang dinonaktifkan atau berstatus baca saja, karena penghapusan adalah kewajiban. Penghitung permintaan dipakai bersama dengan /api/pemantauan/masuk.

Izin: write:pemantauan.

Backend aplikasi Anda meminta token berumur pendek, lalu aplikasi membuka panggilan langsung ke mesin suara dengan token itu. Kunci API mesin suara tetap di Kareeb. Berikan user_id apa adanya sebagai userId di SDK browser mesin suara, karena dari situlah transkrip panggilan menemukan cabang dan sesi ini. Minta token tepat sebelum setiap panggilan. Jangan menaruh nama, nomor rekam medis, atau nomor telepon di session_ref. Selesainya panggilan dikabarkan lewat webhook call.finished.

Izin: write:suara.

Kartu baru muncul di Pipeline, dari percakapan atau dibuat operator. data berisi baris lead.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.

Kartu dipindah ke tahap lain. data berisi baris lead beserta from_stage. Hanya dikirim bila tahapnya benar berubah.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.

Pelanggan mengirim pesan. data memakai nama kolom yang sama dengan GET /api/export/messages, ditambah wa_id, contact_name, dan channel kontak. Webhook ini memuat isi pesan dan nomor pelanggan.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.

Antrean kampanye habis. data berisi baris kampanye yang dibaca ulang setelah selesai, sehingga state sudah done.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.

Percakapan ditutup, dibuka lagi, atau dikembalikan ke antrean. Hanya id dan status, tanpa isi pesan. Hanya dikirim bila statusnya benar berubah.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.

Operator mengubah status sebutan yang dikirim lewat POST /api/pemantauan/masuk. Hanya id dan status, tanpa teks, penulis, atau nama operator. dibalas adalah keterangan operator; Kareeb tidak bisa memeriksa balasan di platform lain.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.

Meta melaporkan sent, delivered, read, atau failed untuk pesan yang dikirim Kareeb, dari API, broadcast, maupun kotak masuk. Hanya id dan status, tanpa teks atau nomor telepon. Status yang diulang Meta diantrekan lagi, jadi buang duplikat dengan pasangan wa_message_id dan status.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.

Panggilan Agen AI suara di aplikasi Anda berakhir. Tanpa transkrip dan tanpa ringkasan.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.

Sambungan ke model Agen AI berganti antara menjawab dan gagal. Dikirim hanya saat berganti, tanpa kunci dan tanpa isi jawaban.

Semua webhook memakai amplop yang sama: id, timestamp, event, data. Kareeb menandatangani byte badan persis seperti dikirim; hitung HMAC-SHA256 dari byte mentah itu dengan secret webhook (hex huruf kecil) lalu bandingkan dengan X-Kareeb-Signature memakai perbandingan waktu tetap. Jawab 2xx dalam 10 detik. Kiriman yang gagal dicoba lagi pada putaran penjadwal berikutnya, sekitar tiap 5 menit, paling banyak 5 kali. Setelah 10 kegagalan berturut-turut, langganan dinonaktifkan dan admin perlu mengaktifkannya lagi. Pengiriman bersifat at least once: buang duplikat dengan id di badan, yang sama untuk satu kejadian di semua endpoint dan semua percobaan.