Webhook

Diperbarui

Lokasi: Pengaturan > Integrasi > Webhook

Fungsi fitur ini:

"Teruskan event masuk ke server Anda sendiri." SyBox mengirimkan salinan setiap event yang dipilih ke alamat di server Anda secara langsung saat terjadi. Event WhatsApp tiba dalam format asli Meta. Pesan pelanggan di Messenger, Instagram, Telegram, TikTok, dan Live Chat, serta event percakapan (selesai, label, kontak, kesepakatan, kasus CRM), tiba dalam format SyBox sendiri. Pesan email dan SMS tidak dikirimkan.

Siapa yang dapat membukanya: admin utama, dan anggota tim dengan izin "Kelola saluran". Untuk membuat webhook atau mengaktifkan kembali yang dijeda, Anda juga memerlukan izin "Tampilkan nomor kontak", karena data salinan memuat nomor telepon asli pelanggan.

Event yang dapat Anda pilih:

  • "Pesan masuk": pelanggan mengirim pesan.
  • "Status pesan": pesan yang Anda kirim telah terkirim, diterima, dibaca, atau gagal.
  • "Reaksi": pelanggan memberikan reaksi pada pesan.
  • "Percakapan ditandai selesai": percakapan ditandai selesai, baik oleh anggota tim, oleh otomatisasi, maupun secara otomatis setelah pelanggan tidak membalas.
  • "Label ditambahkan atau dihapus": label ditambahkan ke percakapan atau dihapus darinya.
  • "Kontak dibuat atau diperbarui": kontak baru dibuat, atau nama, email, atau kolom kontak berubah. Impor kontak tidak mengirimkan event ini.
  • "Kesepakatan ditutup": kesepakatan dicatat dalam percakapan.
  • "Kasus CRM dibuka atau ditutup": kasus CRM dibuka, atau ditutup sebagai terselesaikan, tidak terselesaikan, atau dibatalkan. Kasus tidak terkait dengan nomor mana pun, sehingga hanya webhook yang mencakup semua nomor yang menerimanya, bukan webhook yang dibatasi pada beberapa nomor.

Lima event terakhir tiba dalam format SyBox sendiri untuk setiap saluran. Halaman Dokumentasi Pengembang menampilkan contoh untuk masing-masing event.

  • "Transkripsi suara" (opsi tambahan): pesan suara ditahan sebentar, hingga sekitar dua menit, agar teks transkripsinya dapat dikirimkan bersamaan. Opsi ini nonaktif kecuali Anda menyalakannya.

Cara menambahkan webhook

  1. Buka Pengaturan > Integrasi > Webhook.
    Settings, Webhooks: an active webhook with its last result, and the "Add webhook" button
  2. Klik "Tambah webhook".
    The new webhook window: its name and the address it calls
  3. Masukkan "Nama".
  4. Masukkan "URL Endpoint". Alamat harus berupa "Alamat https publik yang dapat kami jangkau". Alamat http biasa serta alamat jaringan privat atau internal akan ditolak.
  5. Di bawah "Event", aktifkan minimal satu event. "Pesan masuk" aktif secara default.
  6. Opsional: aktifkan "Transkripsi suara" untuk menerima pesan suara beserta teksnya.
  7. Di bawah "Nomor", biarkan "Semua nomor" aktif untuk mencakup setiap nomor WhatsApp. Atau nonaktifkan dan centang nomor yang Anda inginkan saja.
  8. Klik Simpan.
  9. Sebuah jendela menampilkan "Secret penandatanganan". "Salin sekarang — hanya ditampilkan sekali." Simpan di server Anda.

Tentang pengiriman data:

  • Setiap pengiriman menggunakan format yang sama dengan webhook WhatsApp milik Meta.
  • Setiap pengiriman ditandatangani dengan secret Anda dengan cara yang sama seperti Meta menandatangani webhook-nya. Jika server Anda sudah memverifikasi webhook Meta, server Anda dapat memverifikasi webhook SyBox menggunakan secret SyBox Anda.
  • Jika server Anda tidak merespons dengan sukses, SyBox akan mencoba lagi beberapa kali dengan jeda waktu yang makin lama, hingga sekitar satu jam. Setelah itu SyBox akan menghentikan pengiriman untuk event tersebut.
  • Event yang sama terkadang dapat masuk dua kali, misalnya setelah terjadi waktu habis (timeout). Server Anda sebaiknya menangani data duplikat ini.

Cara menguji webhook

  1. Pastikan webhook sudah aktif. Jika belum aktif, Anda akan melihat "Aktifkan webhook ini terlebih dahulu."
  2. Pada kartunya, klik "Kirim peristiwa uji". Anda akan melihat "Peristiwa uji sedang dikirim. Hasilnya muncul di Pengiriman."
  3. Beberapa detik kemudian daftar "Pengiriman" terbuka dan menampilkan jawaban server Anda. Kartu juga menampilkan balasan terakhir dari server Anda beserta waktunya. Balasan sukses (misalnya "HTTP 200") berwarna hijau. Balasan error berwarna merah. "Pengiriman terakhir: tidak pernah" berarti belum ada yang pernah dikirimkan.
    To test a webhook: "HTTP 200" marked on the screen in SyBox

Peristiwa uji memiliki "event": "test" dan tidak membawa data pelanggan. Anda dapat mengirimkannya setiap beberapa detik; jika lebih cepat, Anda akan melihat "Pengujian baru saja dikirim. Coba lagi dalam beberapa detik."

Cara melihat pengiriman

  1. Pada kartu webhook, klik "Pengiriman".
  2. Daftar menampilkan "50 pengiriman terakhir dari 7 hari terakhir.", mulai dari yang terbaru. Masing-masing menampilkan event, waktu percobaan, dan statusnya:
    • "Terkirim": server Anda menjawab dengan sukses.
    • "Menunggu dikirim": belum dicoba dikirim.
    • "Gagal, mencoba lagi": server Anda tidak menjawab dengan sukses, dan SyBox akan mencoba lagi nanti.
    • "Tidak terkirim": SyBox berhenti mencoba.
    • Daftar ini juga menampilkan kode HTTP yang dijawab server Anda, berapa lama jawaban tersebut dalam milidetik, serta "Percobaan: [jumlah]" jika dicoba lebih dari sekali. Pesan itu sendiri tidak ditampilkan.
  3. Untuk mengirim ulang, klik "Kirim lagi" pada pengiriman yang berstatus "Terkirim" atau "Tidak terkirim". Anda akan melihat "Dalam antrean untuk dikirim lagi." Mengirim lagi memerlukan izin "Tampilkan nomor kontak", karena tindakan ini mengirim ulang data pelanggan.

Nonaktif dengan sendirinya:

Jika server Anda terus gagal — 20 percobaan berturut-turut selama lebih dari satu jam — SyBox akan menonaktifkan webhook. Kartu menampilkan warna merah "Nonaktif dengan sendirinya setelah [jumlah] pengiriman gagal berturut-turut", dan admin utama mendapatkan notifikasi "Webhook dinonaktifkan". Event yang menunggu akan disimpan selama 24 jam. Perbaiki alamat atau server Anda, lalu aktifkan kembali webhook: event yang menunggu akan dikirim, dan hitungan dimulai lagi dari nol.

Cara mengedit, menjeda, atau menghapus webhook

  1. Klik Edit untuk mengubah nama, alamat, event, atau nomor.
    To edit, pause or delete a webhook: "Edit" marked on the screen in SyBox
  2. Untuk mengganti secret penandatanganan, ketik secret baru di "Secret penandatanganan". Biarkan kosong untuk mempertahankan secret saat ini ("Biarkan kosong untuk mempertahankan secret saat ini").
  3. Klik Aktifkan / Nonaktifkan untuk menjedanya. Event yang masuk saat webhook dijeda akan ditampung. Jika Anda segera mengaktifkannya kembali, event tersebut akan dikirimkan.
  4. Klik Hapus, lalu konfirmasi "Hapus webhook ini?".

Aturan dan pesan:

  • Nama dan URL Endpoint wajib diisi, dan minimal satu event harus aktif. Jika tidak, Anda akan melihat "Data tidak lengkap".
  • Alamat yang bukan https publik akan ditolak dengan pesan "Alamat https publik yang dapat kami jangkau".
Secret penandatanganan saya hilang.

Secret tidak dapat ditampilkan kembali. Edit webhook, ketik secret baru pilihan Anda di "Secret penandatanganan", simpan, lalu gunakan secret baru tersebut di server Anda.

Webhook saya nonaktif padahal saya tidak mematikannya.

SyBox menonaktifkannya setelah server Anda gagal 20 kali berturut-turut selama lebih dari satu jam. Lihat "Nonaktif dengan sendirinya" di atas: perbaiki server Anda, lalu aktifkan kembali webhook dalam 24 jam agar event yang menunggu dapat dikirim.

Webhook saya tidak pernah menerima apa pun.

Klik "Kirim peristiwa uji" pada kartunya terlebih dahulu, lalu lihat di "Pengiriman". Kemudian periksa empat hal ini. (1) Webhook dalam status aktif. (2) Minimal satu event telah dipilih. (3) Mencakup nomor WhatsApp yang benar, atau "Semua nomor". (4) Saluran tempat pesan masuk adalah saluran yang didukung webhook (WhatsApp, Messenger, Instagram, Telegram, TikTok, atau Live Chat; bukan email atau SMS). Kemudian lihat hasil pengiriman terakhir pada kartu.

Kartu menampilkan error berwarna merah seperti HTTP 404 atau 500.

SyBox berhasil menjangkau alamat Anda, tetapi server Anda membalas dengan pesan error. Periksa alamat dan log server Anda.

Saya tidak bisa membuat webhook. Ada pesan bahwa saya tidak diizinkan.

Untuk membuat atau mengaktifkan kembali webhook, Anda memerlukan izin "Kelola saluran" dan "Tampilkan nomor kontak". Hubungi admin Anda.