Panduan Integrasi API Messaging: REST, SMPP, dan Webhook

Panduan ini ditujukan bagi backend developer, solution architect, dan CTO yang mengintegrasikan aplikasi dengan penyedia messaging untuk WhatsApp, SMS, atau email. Panduan ini menjelaskan antarmuka mana yang sebaiknya dipakai, serta cara menangani autentikasi, idempotensi, laporan pengiriman (DLR), retry, rate limit, dan pengujian, lengkap dengan contoh bentuk request dan response. Untuk menyinkronkan percakapan ke CRM, lihat panduan pendamping tentang menghubungkan CRM dengan webhook.

Antarmuka mana yang sebaiknya dipakai: REST, SMPP, atau webhook?

Gunakan REST untuk mengirim, webhook untuk menerima, dan SMPP hanya untuk SMS volume tinggi jika Anda sudah menjalankan SMPP. Ketiganya saling melengkapi, bukan bersaing: sebagian besar integrasi menggabungkan panggilan REST ke luar dengan webhook yang kembali ke aplikasi Anda.

Sesi SMPP (Short Message Peer-to-Peer) dimulai dengan bind (transmitter, receiver, atau transceiver), mengirim pesan dengan submit_sm, menerima laporan pengiriman (DLR) dan SMS masuk lewat deliver_sm, dan tetap aktif dengan enquire_link. SMPP efisien, tetapi secara operasional lebih berat daripada HTTPS.

Bagaimana cara autentikasinya?

Gunakan metode terkuat yang ditawarkan penyedia, jauhkan secret dari kode, dan autentikasi kedua arah.

• Panggilan keluar: API key atau bearer token OAuth 2.0 yang dikirim di header Authorization melalui TLS. Simpan di secrets manager, lalu rotasi secara berkala dan setiap ada pergantian staf.
• SMPP: system ID dan password saat bind, umumnya dibatasi pada alamat IP yang masuk allowlist dan, jika didukung, melalui TLS.
• Webhook masuk: verifikasi tanda tangan pada setiap event. Meta menandatangani payload webhook WhatsApp Cloud API dengan tanda tangan HMAC-SHA256 di header X-Hub-Signature-256, dihitung dengan app secret Anda; penyedia lain biasanya menawarkan skema serupa. Hitung tanda tangan dari raw body sebelum parsing.

Gunakan kredensial terpisah untuk tiap lingkungan agar test key yang bocor tidak dapat mengirim trafik produksi.

Bagaimana cara mengirim pesan dengan aman?

Kirim lewat antrean, sertakan idempotency key, dan perlakukan respons sebagai "diterima" (accepted), bukan "terkirim" (delivered).

Contoh request kirim (ilustrasi)

Bentuk di bawah ini adalah pseudo-JSON sebagai ilustrasi, bukan API milik penyedia tertentu.

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

Contoh response (ilustrasi)

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

Segera simpan message_id beserta referensi internal Anda. Semua yang terjadi selanjutnya datang secara asinkron.

Mengapa idempotensi penting?

Karena jaringan bisa timeout setelah server sudah memproses permintaan. Jika permintaan kirim Anda timeout lalu Anda mengulangnya tanpa pengaman, pelanggan bisa menerima dua OTP (kode verifikasi) atau dua notifikasi pengiriman. Idempotency key memungkinkan server mengenali retry dan mengembalikan hasil asli.

Aturan yang terbukti efektif:

1. Turunkan key dari event bisnis (misalnya ID pesanan ditambah jenis event), bukan dari nilai acak untuk setiap percobaan.
2. Gunakan key yang sama untuk setiap retry dari pengiriman yang sama.
3. Simpan key cukup lama untuk mencakup jendela retry Anda.
4. Jika penyedia tidak mendukung key, lakukan deduplikasi di sisi Anda sebelum mengirim.

Draf header Idempotency-Key dari IETF menstandarkan pola ini untuk API HTTP; implementasi tiap penyedia berbeda-beda, jadi baca dokumentasinya.

Bagaimana laporan pengiriman (DLR) bekerja?

Status pengiriman datang kemudian sebagai event: lewat webhook untuk WhatsApp dan sebagian besar REST API, serta lewat laporan deliver_sm pada SMPP. Arti status berbeda di setiap kanal; panduan kami tentang status pengiriman pesan menjelaskan masing-masing status.

Contoh webhook status (ilustrasi)

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

Tangani event status secara defensif:

• Lakukan deduplikasi berdasarkan event_id, atau berdasarkan ID pesan ditambah status.
• Jangan pernah memundurkan pesan dari read kembali ke delivered ketika event tiba tidak berurutan.
• Balas dengan 2xx secepatnya, lalu proses dari antrean.
• Catat kode error untuk pesan yang gagal, dan tentukan mana yang layak di-retry.
• Antisipasi celah data: sebagian jalur SMS hanya mengembalikan laporan terbatas, dan status dibaca (read) bergantung pada kanal dan pengaturan pengguna.

Bagaimana menangani retry dan rate limit?

Retry hanya untuk yang mungkin berhasil, lakukan exponential backoff dengan jitter, dan patuhi sinyal dari server.

RFC 9110 mendefinisikan header Retry-After, yang dapat berisi detik atau tanggal. Pasang pembatas laju (rate limiter) di sisi klien sebelum pengiriman agar Anda tetap berada di bawah batas yang didokumentasikan penyedia, bukan baru mengetahuinya lewat error. WhatsApp juga memiliki batas dari sisi Meta untuk jumlah pelanggan unik yang dapat Anda kirimi pesan, dijelaskan di batas pesan dan quality rating.

Bagaimana cara menguji sebelum go-live?

Uji jalur kegagalan, bukan hanya skenario yang berjalan mulus.

Checklist pra-produksi

1. Kirim setiap template dengan nilai berpanjang sebenarnya, termasuk teks berbahasa Arab.
2. Paksa terjadi timeout dan pastikan retry tidak menggandakan pesan.
3. Kirim ke nomor tidak valid dan pastikan error ditangani tanpa retry.
4. Putar ulang webhook dua kali dan secara tidak berurutan; pastikan hanya ada satu status akhir.
5. Kirim webhook dengan tanda tangan yang salah; pastikan ditolak.
6. Picu 429 dengan load test ke sandbox, jika diizinkan.
7. Rotasi API key dan pastikan tidak ada downtime.
8. Periksa bahwa log berisi ID pesan tetapi bukan isi pesan lengkap atau kode OTP.
9. Jalankan pilot produksi kecil dengan nomor internal di setiap kanal.

Sandbox jarang mereproduksi perilaku operator dan Meta secara persis, jadi tetap pantau di minggu-minggu pertama produksi.

Contoh kasus: layanan OTP dan notifikasi pesanan

"Qafilah Logistics" (fiktif), perusahaan pengiriman paket di Arab Saudi, mengirim pembaruan pesanan lewat WhatsApp dengan fallback (kanal cadangan) SMS serta OTP autentikasi.

• Arsitektur: event pesanan masuk ke antrean; worker pengirim memanggil REST API dengan idempotency key shipment-id:event.
• Fallback: jika WhatsApp mengembalikan status gagal untuk pengguna non-WhatsApp, worker mengirim SMS dengan key baru, shipment-id:event:sms.
• OTP: kode cepat kedaluwarsa, sehingga pengiriman OTP tidak di-retry setelah jendela kedaluwarsa; pengguna meminta kode baru. Lihat panduan pesan autentikasi OTP.
• Laporan pengiriman: penerima webhook memverifikasi tanda tangan, melakukan deduplikasi event, dan memperbarui tabel status yang tidak pernah mundur.
• Batas: pembatas token bucket membatasi laju kirim per kanal di bawah batas yang didokumentasikan.

Apa saja kesalahan integrasi yang umum?

• Menganggap "accepted" sama dengan "delivered".
• Retry dengan idempotency key baru pada setiap percobaan.
• Melakukan pemrosesan berat di dalam request webhook.
• Melewatkan verifikasi tanda tangan pada webhook.
• Mengulang error validasi 4xx dalam loop.
• Mencatat kode OTP dan isi pesan lengkap di log.
• Memakai kredensial produksi di lingkungan pengujian.

Bagaimana OmniChannels.ai membantu

OmniChannels.ai, didukung oleh BroadNet Technologies, menyediakan REST/JSON API yang terdokumentasi secara publik dengan spesifikasi OpenAPI 3.1 dan TypeScript SDK, mencakup SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, email, dan push, termasuk template autentikasi WhatsApp dengan OTP one-tap, zero-tap, dan copy-code. Webhook melaporkan status pengiriman dalam satu format yang seragam, SMPP 3.4 melalui TLS melayani SMS volume tinggi, dan MCP server menghubungkan agen AI. Laporan pengiriman (DLR) dengan filter dan ekspor CSV membantu Anda merekonsiliasi apa yang dikirim oleh integrasi Anda. Mulailah dengan dokumentasi developer dan quickstart.