Tarik data

Jalur GET /api/export/... dibuat untuk gudang data, alat BI, atau penjadwal yang menyalin data CRM ke sistem Anda. Semuanya hanya membaca, dengan satu aturan kursor yang sama.

Jalur	Izin	Isi
GET /api/export/contacts	read:contacts	Kontak, status berhenti berlangganan, dan persetujuan terbaru per tujuan
GET /api/export/conversations	read:conversations	Percakapan per kontak dan saluran
GET /api/export/messages	read:messages	Pesan masuk dan keluar beserta status kirimnya
GET /api/export/campaigns	read:campaigns	Kampanye dari layar dan dari API
GET /api/export/campaign-stats	read:campaigns	Angka corong per kampanye, sama dengan halaman Laporan
GET /api/export/campaigns/recipients	read:campaigns	Corong per penerima; bisa dibatasi dengan ?campaign_id=
GET /api/export/orders	read:orders	Pesanan yang dibuat di percakapan
GET /api/export/komentar	read:comments	Komentar di unggahan Instagram dan Halaman Facebook sendiri

Kolom lengkap setiap jalur ada di Referensi API.

Aturan kursor

GET /api/export/messages?since_id=0&limit=1000

Parameter	Bawaan	Batas
since_id	0	0 atau lebih, eksklusif: hanya baris dengan id lebih besar
limit	200	1 sampai 1000

Setiap jawaban memakai amplop yang sama:

{
  "items": [],
  "count": 200,
  "next_since_id": 4021,
  "has_more": true
}

• Urutan selalu id naik. Urutan ini tetap, sehingga halaman tidak bergeser saat Anda sedang menelusurinya.
• next_since_id adalah id baris terakhir, atau null pada halaman kosong. Pakai sebagai since_id permintaan berikutnya.
• has_more hanya petunjuk. Tanda selesai yang pasti adalah items kosong. Sistem yang berjalan sampai items kosong membuat satu permintaan tambahan, tetapi tidak pernah berhenti terlalu cepat.

Satu batasan, terus terang

Kursor id hanya melihat baris baru, tidak melihat perubahan. Kontak yang labelnya diganti, percakapan yang ditutup, atau pesanan yang dibayar tidak berganti id, sehingga tidak muncul lagi pada jalan bertahap. Tabel-tabel ini tidak punya kolom waktu ubah.

Akibatnya bagi sistem Anda:

1. Tabel yang hanya bertambah (pesan, dan penerima kampanye saat pertama dicatat) cukup dibaca bertahap: simpan id terakhir per jalur, lalu lanjutkan dari situ.
2. Tabel yang bisa berubah (kontak, percakapan, pesanan, kampanye) perlu jalan penuh dari since_id=0 secara berkala. Setiap malam adalah pola yang dirancang untuk ini.
3. /api/export/campaign-stats selalu dibaca penuh. Angka satu kampanye berubah setiap kali penerimanya bereaksi; jalan bertahap akan mengembalikan id yang sama dengan angka lama.

Tidak ada yang dihapus dari tabel-tabel ini (kontak yang digabung dilipat ke kontak lain), jadi tidak ada umpan penghapusan.

Contoh penarik data

import httpx

BASE = "https://kareeb.id"
HEADERS = {"Authorization": "Bearer kt_xxxxxxxxxxxxxxxxxxxx"}


def jalan(path, since_id=0, limit=1000):
    """Setiap baris sejak since_id. Halaman kosong adalah tanda selesai."""
    with httpx.Client(base_url=BASE, headers=HEADERS, timeout=30) as client:
        while True:
            r = client.get(path, params={"since_id": since_id, "limit": limit})
            r.raise_for_status()
            halaman = r.json()
            if not halaman["items"]:
                return
            yield from halaman["items"]
            since_id = halaman["next_since_id"]


# Bertahap: tabel yang hanya bertambah. Simpan id terakhir per jalur.
for pesan in jalan("/api/export/messages", since_id=terakhir["messages"]):
    ...

# Setiap malam: tabel yang bisa berubah butuh jalan penuh.
for kontak in jalan("/api/export/contacts"):
    ...

Cabang mana yang terbaca

Token API berdiri di cabang Utama. Kontak, percakapan, kampanye, penerima kampanye, pesanan, dan komentar yang terbaca adalah milik cabang Utama. Pesan (/api/export/messages) mencakup semua cabang organisasi Anda.

Kontak, persetujuan, dan berhenti berlangganan

• Identitas kontak adalah pasangan channel dan wa_id, bukan wa_id saja. Di WhatsApp, wa_id berisi nomor telepon, atau id pengguna khusus bisnis dari Meta (diawali ID.) bila pelanggan menyembunyikan nomornya.
• opted_out_at terisi berarti pelanggan meminta berhenti dikirimi pesan. Kareeb menahan semua pengiriman proaktif kepadanya, dan tidak ada pengaturan yang mematikan aturan ini.
• consent_reminders dan consent_marketing adalah persetujuan terbaru per tujuan: granted, revoked, atau null. null bukan penolakan, artinya belum pernah ditanya. Persetujuan berlaku per tujuan: persetujuan pengingat tidak berarti persetujuan promosi, jadi jangan digabung menjadi satu tanda.
• Riwayat lengkap persetujuan sengaja tidak diekspor. Riwayat itu bisa dilihat di layar operator.

Untuk mencocokkan satu kontak tanpa menelusuri daftar, pakai GET /api/contacts/{id} (izin read:contacts). Jawabannya satu objek atau 404, tanpa kursor.

Kampanye dan corongnya

• campaign-stats memberi satu baris per kampanye: targeted, sent, delivered, read, replied, clicked, converted, converted_amount, failed. Corongnya menurun, jadi delivered sudah mencakup yang read.
• cost hanya terisi bila diketik manusia di Kareeb; Kareeb tidak menghitung biaya kiriman. roi adalah rasio, bukan persen (0,5 berarti naik 50%), dan null kecuali cost terisi dan lebih dari nol.
• campaigns/recipients memberi corong per penerima, termasuk clicked (tautan pribadi penerima pernah dibuka; WhatsApp tidak melaporkan ketukan tombol) dan replied (pelanggan mengirim pesan setelah kiriman).
• Pesanan terbayar diatribusikan ke kiriman kampanye terakhir kepada kontak itu dalam jendela atribusi sebelum pesanan dibuat (bawaannya 7 hari, bisa diatur per instalasi). Satu pesanan hanya dihitung untuk satu penerima.

Komentar: amplopnya sendiri

GET /api/export/komentar memakai amplop berbeda dan batas limit 1 sampai 500:

{"komentar": [{"id": 41, "channel": "ig", "post_id": "...", "comment_id": "...",
               "thread_id": 7, "body": "...", "author_name": "...",
               "commented_at": "2026-10-23T02:00:00+00:00", "replied": false}],
 "next_since_id": null}

• next_since_id berisi id terakhir hanya bila halaman penuh, dan null bila tidak penuh atau kosong. Berhenti saat null, lalu simpan id terbesar yang Anda terima sebagai since_id berikutnya.
• replied dinilai saat halaman dibaca. Komentar yang dibalas setelah Anda tarik tidak muncul lagi.
• Saluran yang sakelar "lead dari komentar"-nya mati tidak mengekspor apa pun, termasuk komentar yang tersimpan saat sakelar masih menyala.

Yang sengaja tidak diekspor

• Isi mentah permintaan dan jawaban Meta untuk setiap pesan.
• Tautan pembayaran pesanan, karena tautan aktif adalah alat bayar, bukan data analisis.
• Riwayat persetujuan per kontak.
• Id Meta penulis komentar dan token Halaman.