Kirim ulang tanpa pesan ganda

Koneksi bisa putus setelah Kareeb menerima permintaan Anda tetapi sebelum jawabannya sampai. Bila sistem Anda lalu mengulang permintaan, pelanggan bisa menerima pesan yang sama dua kali. idempotency_key mencegah hal itu.

Cara kerjanya

Setiap POST /api/messages dan POST /api/broadcasts wajib membawa idempotency_key. Kunci itu adalah identitas kiriman Anda.

• Permintaan pertama dengan kunci baru dikirim seperti biasa (201 untuk satu pesan, 202 untuk broadcast).
• Permintaan berikutnya dengan kunci yang sama dijawab 200 dengan "replay": true dan id kiriman pertama. Tidak ada yang dikirim lagi, apa pun isi badan permintaan kedua.

{
  "message_id": 9137,
  "conversation_id": 412,
  "wa_message_id": "wamid.HBgM...",
  "contact_id": 88,
  "replay": true
}

Kunci berlaku per organisasi, panjangnya 1 sampai 128 karakter.

Memilih kunci

Pakai sesuatu yang sudah unik di sistem Anda untuk satu pesan yang dimaksud, misalnya nomor janji ditambah jenis pesannya:

Pesan	Kunci
Pengingat sehari sebelum janji 88123	janji-88123-h1
Pengingat pagi hari janji 88123	janji-88123-h0
Broadcast pengingat kontrol untuk 5 November	kontrol-2026-11-05

Jangan memakai waktu saat ini atau angka acak sebagai kunci. Kunci seperti itu berbeda pada setiap percobaan, sehingga tidak mencegah pesan ganda.

Kapan mengulang

Jawaban	Ulangi?
Koneksi putus, waktu habis, 5xx	Ya, dengan kunci yang sama.
429	Ya, setelah menunggu sebanyak detik di header Retry-After, dengan kunci yang sama.
422	Perbaiki permintaannya dulu. Penolakan 422 tidak mencatat kunci, jadi kunci yang sama boleh dipakai lagi setelah diperbaiki.
402 atau 403	Jangan diulang otomatis. Ada yang perlu diperbaiki oleh admin organisasi Anda.
200 dengan "replay": true	Tidak perlu. Kiriman pertama sudah tercatat.

Satu kunci untuk satu pesan, tanpa percobaan paralel

Untuk POST /api/messages, kunci dicatat sesaat setelah Meta menerima pesan. Dua permintaan yang berpacu dengan kunci yang sama, atau gangguan tepat di antara keduanya, masih bisa membuat pesan terkirim dua kali. Jalankan percobaan ulang satu per satu, jangan bersamaan.

Broadcast dengan daftar yang berubah

Untuk POST /api/broadcasts, kunci adalah identitas seluruh kampanye. Bila kunci yang sama dikirim lagi dengan daftar penerima yang berbeda, Kareeb tetap menjawab dengan kampanye pertama dan tidak mengirim ke daftar baru. Sistem yang berubah pikiran perlu kunci baru, bukan kiriman kedua ke daftar pertama.