API broadcast di messenger WhatsApp dan Telegram

API broadcast WhatsApp dan Telegram: hubungkan akun, buat broadcast, dan terima status pengiriman langsung dari CRM atau situs Anda.

Pesan ke pelanggan hampir tidak pernah bisa menunggu "nanti kalau sempat". Pesan itu dibutuhkan tepat saat kejadiannya: pelanggan membayar pesanan, booking jadwal kunjungan, tidak datang, sebulan tidak muncul. Kejadiannya sudah tercatat di sistem Anda, jadi aneh kalau setelah itu Anda masih harus masuk ke dasbor dan menyusun broadcast secara manual.

Untuk itulah ada API publik. Seluruh proses broadcast berjalan lewat API: menyusun audiens, memeriksa teks, tempo pengiriman yang aman, status untuk setiap penerima, dan balasannya. Antrean, jeda antarpesan, pengulangan, dan perlindungan nomor dari blokir tidak perlu Anda bangun sendiri: semua itu diurus layanan, dan di sistem Anda cukup ada satu panggilan.

Satu set metode yang sama berlaku untuk semuanya: akun WhatsApp dan Telegram serta bot Telegram. Untuk menambah messenger lain, Anda tidak perlu menulis integrasi baru: cukup ganti satu nilai di permintaan yang sama.

Apa saja yang bisa dilakukan API broadcast WhatsApp dan Telegram

Semua yang Anda kerjakan secara manual di dasbor juga tersedia lewat HTTP:

• Menghubungkan messenger dan bot. Cukup satu permintaan: akun messenger dihubungkan lewat kode QR atau nomor telepon, bot lewat token. Hasil koneksinya dilaporkan sendiri oleh layanan. Kalau akun dilindungi kata sandi verifikasi dua langkah, kata sandinya juga dikirim lewat API.
• Audiens. Buat segmen dan unggah nomor telepon, sampai 100 nomor per permintaan. Daftar yang lebih panjang diunggah dengan beberapa permintaan. Nomor yang sudah ada di proyek tidak akan diduplikasi.
• Broadcast. Buat broadcast, tambahkan teks atau media (gambar, video, audio, dokumen, sampai sepuluh pesan per broadcast), lalu pilih penerima: segmen kontak, buku telepon akun, atau chat yang sudah ada. Setelah itu: moderasi teks, peluncuran, jeda, dan pembatalan.
• Mengedit draf. Selama broadcast belum diluncurkan, Anda juga bisa memakai API untuk mengubah teks dan berkas pesan, menghapus pesan yang tidak perlu, dan mengganti nama broadcast. Mengubah teks membatalkan hasil moderasi: sebelum diluncurkan, broadcast harus lolos moderasi lagi.
• Hasil untuk setiap penerima. Terkirim, sampai, dibaca, dibalas, nomor tidak terdaftar di messenger.
• Balasan penerima. Selain status "membalas", API juga memberikan teks balasannya: apa persisnya yang ditulis orang itu sebagai balasan atas broadcast.
• Mengirim satu pesan. Untuk kasus transaksional ada metode tersendiri: teks dan lampiran ditentukan di setiap permintaan, tanpa perlu menyusun broadcast untuk satu nomor.
• Seluruh percakapan. Riwayat dialog dengan seseorang: pesan masuk dan keluar dalam satu alur. Setiap ada pesan masuk baru, layanan mengirim event, dan Anda bisa membalas dengan metode pengiriman satu pesan yang sama, bahkan dengan mengutip pesan tertentu. Di bot, pesan masuk datang seketika, sedangkan di akun messenger percakapan ditarik lewat sinkronisasi, jadi ada jeda. Keduanya butuh paket dengan analitik balasan, penjelasannya ada di bawah.
• Webhook. Akun terhubung atau terputus, messenger membatasi akun, broadcast diluncurkan, dijeda, selesai, penerima membalas, ada pesan masuk baru. Anda tidak perlu melakukan polling API dalam loop.

Penting soal pengirim: pesan dikirim dari akun Anda sendiri yang Anda hubungkan. Layanan tidak menyediakan nomor sendiri, dan itu justru menguntungkan: nomor dan reputasinya tetap milik Anda, dan balasan pelanggan masuk ke aplikasi messenger Anda seperti biasa.

Cara mendapatkan kunci API

1. Masuk ke dasbor broadcast dan buka bagian API.
2. Klik "Buat kunci", beri nama (supaya nanti jelas untuk integrasi mana kunci itu dibuat) dan, kalau perlu, masa berlaku.
3. Salin tokennya. Token hanya ditampilkan sekali: layanan hanya menyimpan hash-nya dan tidak bisa memulihkan nilainya. Kalau token hilang, buat kunci baru dan hapus yang lama.

Bagian API hanya terbuka untuk pemilik proyek: hanya pemilik yang bisa membuat kunci dan melihat daftarnya. Jadi kalau integrasinya dikerjakan developer atau kontraktor, pemilik membuat kunci lalu menyerahkan tokennya kepada mereka, tanpa perlu memberi akses ke dasbor.

Kunci dibuat untuk proyek, tidak terikat pada karyawan tertentu. Simpan seperti kata sandi. Anda bisa membuat beberapa kunci, misalnya satu untuk setiap integrasi, supaya masing-masing bisa dicabut secara terpisah.

Setiap kunci punya izin yang dicentang saat kunci dibuat: membaca data proyek, menyiapkan broadcast dan audiens, meluncurkan broadcast dan mengirim pesan, mengelola akun, mengatur webhook. Secara bawaan kunci baru bisa membaca dan menyiapkan, sedangkan izin lainnya hanya Anda berikan bila memang dibutuhkan. Izin juga bisa diubah belakangan tanpa mengganti kuncinya, jadi integrasi yang sudah memakainya tidak perlu dihentikan.

Token dikirim di header setiap permintaan. Cara termudah untuk memastikan semuanya berjalan adalah meminta daftar akun yang terhubung:

curl https://api.wsender.io/v1/channel \
  -H "Authorization: key TOKEN_ANDA"

Semua metode dijelaskan di dokumentasi API, dan permintaan dengan kunci Anda bisa dijalankan langsung dari peramban tanpa menulis satu baris kode pun. Selain itu tersedia spesifikasi yang bisa dibaca mesin, yaitu berkas OpenAPI: dengan berkas ini, alat seperti Swagger Codegen atau NSwag bisa membuat klien dalam bahasa pemrograman Anda, jadi permintaan dan model tidak perlu ditulis manual.

Broadcast dalam tujuh permintaan

Skenario minimalnya seperti ini: susun segmen → buat broadcast → tambahkan teks → tentukan penerima → kirim ke moderasi → luncurkan.

1. PUT /v1/segment membuat segmen.
2. PUT /v1/segment/{segmentId}/contact mengunggah nomor.
3. PUT /v1/mailing membuat broadcast.
4. PUT /v1/mailing/{mailingId}/message/text menambahkan teks pesan.
5. PUT /v1/mailing/{mailingId}/recipient/source menetapkan bahwa penerima diambil dari segmen.
6. POST /v1/mailing/{mailingId}/moderate mengirim teks ke moderasi.
7. POST /v1/mailing/{mailingId}/start memulai pengiriman dari akun yang dipilih.

Permintaannya sama untuk semua akun: broadcast di WhatsApp dibuat dengan cara yang sama seperti di Telegram atau dari bot. Yang berbeda hanya akun atau bot yang terhubung. Setelah itu Anda tidak perlu terus mengecek: status datang lewat webhook.

Permintaan ulang tidak membuat broadcast kedua

Situasi yang umum dalam integrasi: permintaan terkirim, tetapi responsnya tidak kembali. Jaringan sempat putus, timeout terpicu, layanan Anda restart di saat yang kurang tepat. Lalu harus bagaimana? Kalau diulang, ada risiko membuat broadcast kedua atau memulai pengiriman dua kali. Kalau tidak diulang, bisa jadi tidak ada yang terkirim sama sekali.

Karena itu setiap permintaan yang mengubah sesuatu punya kunci idempotensi. Anda membuat sebuah string (biasanya UUID) dan mengirimnya di header:

Idempotency-Key: 3f0c1b7e-8a2e-4a51-9d2b-6a1e0f2c4d88

Aturannya satu: operasi baru memakai kunci baru, pengulangan operasi yang sama memakai kunci yang sama. Selebihnya diurus layanan. Permintaan pertama dijalankan, dan responsnya disimpan selama satu hari. Permintaan ulang dengan kunci yang sama tidak menjalankan apa pun: Anda menerima respons yang sama seperti pada permintaan pertama. Kalau permintaan pertama masih diproses, permintaan ulang mendapat kode 409: tunggu sebentar lalu coba lagi.

Kalau kunci yang sama dipakai untuk permintaan yang berbeda, Anda mendapat kode 422. Ini melindungi dari pemakaian ulang kunci secara tidak sengaja: Anda tidak akan menerima hasil milik permintaan lain.

Kesimpulan praktis untuk integrasi: ulangi permintaan yang belum punya hasil, yaitu saat koneksi putus, saat server mengembalikan error, dan saat respons 429 (frekuensi permintaan terlampaui). Respons seperti ini tidak disimpan, jadi permintaan ulang benar-benar menjalankan operasinya. Lain halnya dengan penolakan karena isi permintaan, misalnya "kolom wajib tidak diisi": itu sudah merupakan hasil, dan permintaan ulang akan mendapat penolakan yang sama.

Dari mana penerima broadcast diambil

Langkah kelima layak dibahas tersendiri: sumber penerima menentukan hasil sekaligus risiko bagi akun. Sumbernya ada tiga.

• Segmen kontak. Nomornya Anda unggah sendiri. Broadcast yang terikat ke segmen akan terus mengirim pesan ke kontak yang Anda tambahkan belakangan. Untuk integrasi, inilah sumber utama, dan pembahasannya ada di bagian tersendiri di bawah.
• Kontak akun. Buku telepon nomor yang terhubung. Secara bawaan pesan hanya dikirim ke orang yang sudah pernah berkirim pesan dengan Anda: audiens seperti ini lebih sering membalas dan hampir tidak pernah melaporkan spam. Batasan ini bisa dimatikan, tetapi sebaiknya jangan.
• Chat akun. Dialog yang sudah ada. Di sini Anda juga bisa membatasi penerima hanya pada orang yang pernah berkirim pesan dengan Anda, dan mengecualikan chat dengan bot supaya pesan tidak masuk ke chat layanan.

Satu hal yang perlu diperhitungkan saat merancang: pada peluncuran pertama, sumber penerima dikunci bersama messenger-nya dan tidak bisa diubah lagi. Untuk sumber lain diperlukan broadcast baru.

Bot Telegram: API yang sama

Tidak ada API khusus untuk bot, dan ini disengaja: integrasi yang ditulis untuk broadcast dari akun messenger juga bekerja dengan bot tanpa perlu diubah. Metode koneksi yang sama, status yang sama, webhook yang sama, jalur broadcast yang sama dari draf sampai laporan per penerima.

Perbedaannya hanya dua, dan keduanya langsung terlihat.

Koneksi lewat token. Token untuk bot Telegram diberikan oleh @BotFather. Setelah itu permintaannya sama seperti untuk akun messenger, hanya saja Anda mengirim token sebagai ganti cara login. Kalau Anda membuat token baru, bot tidak hilang: permintaan terpisah untuk memperbarui token menggantinya pada bot yang sudah terhubung, sementara pelanggan bot, broadcast, dan riwayat tetap utuh (di dasbor, hal yang sama dilakukan lewat tautan "Perbarui token" di halaman bot).

Penerima: pelanggan bot. Bot hanya bisa mengirim pesan kepada orang yang lebih dulu menulis kepadanya, jadi segmen nomor yang diunggah tidak bisa dipakai bot. Begitulah aturan platformnya: Bot API tidak mengizinkan bot menulis lebih dulu, dan aturan ini tidak bisa diakali.

Dari sini pembagian peran dalam integrasi jadi sederhana. Akun messenger tetap satu-satunya cara menjangkau orang yang belum pernah berkirim pesan dengan Anda. Bot dipakai untuk orang yang sudah berlangganan ke bot: akun tidak berisiko diblokir karena broadcast seperti ini, nomor telepon sama sekali tidak terlibat, dan kecepatannya hanya dibatasi limit platform, tanpa pemanasan pelan demi keamanan akun.

Broadcast berbasis pemicu: satu panggilan untuk satu kejadian

Sifat segmen yang paling berguna: broadcast ke segmen tidak selesai setelah mengirim pesan ke semua orang yang ada di dalamnya. Broadcast tetap berjalan dan menunggu kontak baru: begitu Anda menambahkannya ke segmen, pengiriman langsung berlanjut.

Pada dasarnya, broadcast yang sedang berjalan bekerja sebagai antrean pengiriman. Jadi skemanya seperti ini:

1. Cukup sekali Anda membuat segmen dan broadcast untuk segmen itu, menambahkan teks, lalu meluncurkannya. Mau lewat API atau manual di dasbor, hasilnya sama.
2. Setelah itu, untuk setiap kejadian di sistem Anda cukup satu permintaan: menambahkan nomor ke segmen.

Selesai. Pesan terkirim sendiri dengan tempo yang aman, memakai teks yang sudah lolos moderasi, dan sesuai limit. Pesanan dibayar, jadwal dipesan, pelanggan tidak datang, sebulan tidak muncul: Anda punya broadcast berbasis pemicu sendiri, dan yang perlu Anda pelihara hanya satu panggilan untuk setiap pemicu.

Berhenti berlangganan juga sesederhana itu, dan sebaiknya dipikirkan dari awal: kalau seseorang minta tidak dihubungi lagi, hapus nomornya dari segmen dengan satu permintaan, dan antrean tidak akan mengambilnya. Kontaknya sendiri tetap ada di proyek beserta riwayatnya, hanya keluar dari audiens ini.

Teks broadcast seperti ini sama untuk semua penerima, dengan sisipan nama dan variasi kalimat. Karena itu untuk setiap pemicu dibuat pasangan "segmen plus broadcast" tersendiri: sapaan, pengingat jadwal, ajakan untuk kembali berbelanja. Dibuat sekali, setelah itu tinggal menunggu nomor.

Balasan pelanggan kembali ke sistem Anda

Broadcast tidak berakhir saat pesan terkirim: orang membalas, dan balasan itulah yang biasanya dicari sejak awal. Lewat API Anda bisa melihat siapa yang membalas sekaligus apa yang ditulisnya.

Urutannya begini: masuk webhook "penerima membalas", lalu Anda meminta balasan dari penerima itu dan mendapatkan waktu, teks, jenis pesan, dan nama berkas lampiran.

curl https://api.wsender.io/v1/mailing/{ID_BROADCAST}/recipient/{ID_PENERIMA}/reply \
  -H "Authorization: key TOKEN_ANDA"

Yang dikembalikan hanya balasan untuk broadcast ini, tanpa sisa percakapan dengan orang tersebut: layanan mengambil pesan yang datang setelah pengiriman ke penerima itu. Status "membalas" ditetapkan dengan aturan yang sama, jadi status dan isi balasan tidak akan saling bertentangan.

Dari situ balasan masuk ke CRM Anda: menjadi tugas untuk manajer, masuk ke chat tim penjualan, tampil di panel laporan. Dua catatan supaya tidak berharap berlebihan. Percakapan ditarik dari akun secara berkala, jadi ada jeda antara balasan orang dan kemunculannya di API. Daftarnya juga bisa kosong kalau orang hanya memberi reaksi pada pesan tanpa menulis teks.

Kalau Anda belum punya CRM sendiri, balasan yang sama bisa dilihat di Dialogs, yang dibuka dari dasbor: manajer bisa membacanya dan membalas dari sana. Pesan yang dikirim lewat API diberi tanda "API" di sana, dan saat kursor diarahkan ke tanda itu terlihat kunci mana yang dipakai untuk mengirimnya.

Hal terpenting soal paket. Balasan, begitu juga dialog dan kontak akun, diambil lewat sinkronisasi akun yang terhubung, dan sinkronisasi ini hanya ada di sebagian paket: di paket gratis tidak tersedia. Di paket gratis Anda bisa membangun dan menguji integrasi, broadcast bisa dibuat dan dikirim, tetapi umpan baliknya tidak ada: webhook balasan tidak datang, dan permintaan balasan mengembalikan error 403 dengan keterangan bahwa fitur ini tidak tersedia di paket Anda. Error ini sengaja dipakai sebagai ganti daftar kosong: respons kosong akan Anda artikan sebagai "orangnya tidak membalas", lalu Anda sibuk mencari kesalahan di sistem sendiri.

Hal yang sama berlaku untuk bot. Di paket gratis bot hanya bekerja untuk pesan keluar: broadcast terkirim, tetapi pesan masuk dari pelanggan bot tidak diterima dan tidak disimpan di mana pun, baik di API maupun di dasbor. Jumlah pelanggan bot tetap bertambah, dan broadcast ke mereka tetap bisa dikirim.

Webhook: layanan memberi tahu sendiri apa yang terjadi

Anda tidak perlu terus-menerus bertanya ke API "ada kabar apa". Daftarkan alamat Anda, dan event akan datang sendiri:

curl -X PUT https://api.wsender.io/v1/webhook \
  -H "Authorization: key TOKEN_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/wsender","secret":"rahasia-anda"}'

Setiap proyek hanya punya satu webhook, dan alamatnya wajib HTTPS. Ganti alamat dan nilai secret dari contoh dengan milik Anda: secret boleh berisi huruf Latin, angka, tanda hubung, dan garis bawah. Layanan mengirimkannya kembali di header X-WSender-Secret-Token pada setiap permintaan, sehingga Anda bisa membedakan event dari kami dan permintaan lain yang masuk ke alamat yang sama.

Event yang datang terbagi dalam empat kelompok:

• Akun: terhubung, terputus, dan selama proses koneksi: kode QR siap, kode penautan siap, menunggu kode konfirmasi atau kata sandi verifikasi dua langkah, koneksi berhasil.
• Pembatasan messenger: akun dibatasi dan pembatasan dicabut. Mungkin ini yang paling berharga: saat diblokir, akun tetap terhubung, dan tanpa event ini broadcast berhenti tanpa ada yang tahu.
• Broadcast: lolos moderasi, tidak lolos beserta catatannya, diluncurkan, dijeda beserta alasannya, selesai, dibatalkan.
• Penerima: pesan terkirim, orang membalas, pengiriman gagal, nomor tidak terdaftar di messenger.

Event untuk penerima dan pesan satuan hanya dikirim kalau Anda berlangganan secara eksplisit. Cantumkan jenis yang dibutuhkan di events: daftar kosong tidak mengaktifkannya. Dengan begitu broadcast besar tidak menghasilkan banjir event yang tidak perlu.

Simpan event yang masuk dengan aman lebih dulu, lalu balas dengan kode 2xx, baru kemudian proses. Kalau server Anda tidak merespons dalam 10 detik atau mengembalikan error, layanan mencoba lagi dengan jeda dari 30 detik hingga setengah jam. Setiap event disimpan di antrean paling lama satu hari sejak dibuat.

Satu event bisa datang dua kali: periksa id-nya supaya tindakan di CRM tidak dijalankan dua kali.

Kalau sejak kegagalan pertama sudah lewat satu hari dan selama itu tidak ada satu pun pengiriman yang berhasil, webhook otomatis dijeda. Pemilik proyek menerima pemberitahuan lewat bot notifikasi WSENDER di Telegram, kalau bot itu terhubung. Statusnya bisa dicek dengan permintaan GET /v1/webhook: objek health berisi status Active atau Suspended, error terakhir, dan tanggal-tanggal terkait.

Setelah server penerima Anda diperbaiki, panggil POST /v1/webhook/resume dengan kunci yang punya izin mengatur webhook:

curl -X POST https://api.wsender.io/v1/webhook/resume \
  -H "Authorization: key TOKEN_ANDA"

Layanan akan mengirim event uji webhook.test ke alamat Anda dengan secret yang biasa. Pengiriman baru dilanjutkan kalau responsnya 2xx. Metode POST /v1/webhook/test yang biasa berguna untuk mengecek alamat, tetapi tidak mengakhiri jeda.

Selama jeda, event baru tidak dikumpulkan, dan masa simpan event yang sudah dibuat tidak diperpanjang. Event yang kedaluwarsa dan event selama jeda tidak akan datang setelah pengiriman dilanjutkan. Karena itu, kalau server Anda lama tidak berfungsi, ambil status terkini pesan dan broadcast lewat API. Rincian kolom dan error ada di dokumentasi API.

Kecepatan broadcast: kenapa API tidak mengirim semuanya sekaligus

Di sinilah harapan developer paling sering berbenturan dengan kenyataan messenger. API menerima permintaan seketika, tetapi tempo pengiriman ditentukan oleh Autostrategi: pengiriman dimulai pelan dan kecepatannya naik seiring akun mengumpulkan riwayat pengiriman. Kalau platform memperlambat akun, layanan menjeda broadcast lalu melanjutkannya dengan lebih pelan.

Dengan cara ini layanan menjaga nomor Anda: kalau seluruh basis kontak dikirimi dalam satu jam, messenger kemungkinan besar akan membatasi akun. Karena itu layanan memang tidak menyediakan opsi seperti ini.

Ada empat hal lain yang sebaiknya diperhitungkan sebelum mulai integrasi:

• Teks diperiksa sebelum peluncuran. AI memeriksa pesan dan bisa mengembalikan catatan. Daftarnya bisa dibaca lewat API, dan untuk setiap catatan terlihat apa masalahnya dan di pesan mana. Catatan yang sifatnya rekomendasi bisa diterima dengan satu permintaan, sedangkan topik terlarang hanya bisa diperbaiki dengan mengubah teks.
• Limit paket berlaku sama seperti di dasbor. Pesan memakai kuota harian: saat kuota habis, broadcast dijeda dan tidak berlanjut sendiri. Anda perlu meluncurkannya lagi, di dasbor atau lewat API.
• Limit permintaan dihitung per proyek. Limit ini dipakai bersama oleh semua kunci proyek, jadi membuat kunci baru tidak menambah limit.
• Nomor yang belum dikenal diproses lebih pelan. Kalau nomornya belum ada di percakapan Anda, layanan harus lebih dulu mengecek ke messenger apakah nomor itu terdaftar. Di Telegram pengecekan seperti ini dibatasi lebih ketat daripada di WhatsApp, jadi broadcast ke nomor yang belum dikenal di sana berjalan jauh lebih pelan.

Di mana API broadcast berguna

• CRM: notifikasi status transaksi dan pesanan, sementara balasan pelanggan kembali ke kartu pelanggan.
• Toko online: konfirmasi pesanan, pembayaran, pengiriman.
• Situs atau landing page: balasan instan atas formulir yang diisi, di messenger yang dipakai orang itu.
• Booking online: pengingat kunjungan sehari sebelumnya.
• Reaktivasi: segmen "tidak membeli selama 3 bulan" diisi dari basis data Anda, dan broadcast mengerjakan antreannya sendiri.

Langkah selanjutnya

API tidak dikenai biaya tambahan: yang berlaku tetap paket biasa, dan API tersedia bahkan di paket gratis. Di paket gratis tersedia 15 pesan per hari, cukup untuk membangun dan menguji integrasi.

Mulailah dari yang kecil: buat kunci, jalankan permintaan daftar akun, hubungkan satu akun, lalu kirim broadcast ke segmen berisi satu nomor Anda sendiri. Dalam setengah jam seluruh alurnya akan jelas. Setelah itu tinggal menyusun pasangan "segmen plus broadcast" yang sesungguhnya dan menambahkan nomor ke segmen dari bagian sistem Anda tempat kejadian itu tercatat.

Deskripsi lengkap metode ada di dokumentasi API, dan spesifikasi untuk membuat klien secara otomatis ada di berkas OpenAPI.