Webhook Deskgram 2: pengaturan peristiwa dan pengiriman

Ringkasan modul webhook

Webhook mengirim peristiwa Deskgram ke alamat pilihan Anda: CRM, layanan otomasi, atau aplikasi sendiri. Ini adalah pemberitahuan keluar Deskgram, bukan pengaturan webhook Telegram Bot API dan bukan saluran perintah masuk ke program.

Diperiksa berdasarkan kode pada 24 Oktober 2026.

Sebelum mulai: Deskgram harus berjalan dan penerima harus dapat diakses dari komputer tersebut. Pengiriman memakai POST JSON. Pengiriman terputus tidak otomatis dipulihkan setelah program dimulai ulang.

Pengaturan melalui antarmuka tidak membutuhkan pemrograman. Pengembang penerima dan pengguna HTTP lokal dapat membaca referensi API.

Pengaturan cepat

1. Dapatkan URL webhook masuk dari sistem penerima, beserta rahasia/token jika diperlukan.
2. Buka Pengaturan → Integrasi di Deskgram.
3. Pilih Baru, masukkan nama dan Webhook URL.
4. Pada Tindakan yang dikirim, pilih peristiwa.
5. Pada Dari modul mana, gunakan semua atau pilih modul.
6. Pada Isi permintaan, pilih format. Mulai dari JSON standar Deskgram jika penerima mendukung.
7. Isi rahasia dan header tambahan bila diperlukan.
8. Periksa Aktifkan webhook setelah disimpan, lalu pilih Buat webhook.
9. Pilih Uji, buka Riwayat, periksa detail pengiriman.
10. Jalankan tindakan nyata singkat yang sesuai peristiwa dan periksa hasil pada penerima.

Uji memakai pengaturan tersimpan. Setelah mengubah URL, rahasia, peristiwa, atau bidang, simpan sebelum menguji. Beberapa webhook dapat memakai alamat, peristiwa, dan format berbeda.

Menghubungkan CRM

Masukkan URL webhook masuk CRM, bukan halaman utama atau dasbornya. Kanal yang kompatibel dengan Deskgram mungkin memberikan alamat seperti:

https://crm.example.com/api/v1/channel-webhooks/deskgram/123

Domain dan nomor di atas fiktif. Gunakan alamat CRM Anda.

Deskgram mengenali jalur /channel-webhooks/deskgram/{id} dan menampilkan bidang rahasia CRM. Nilai dikirim pada x-secret. CRM memberikan alamat dan rahasia secara terpisah; URL saja tidak mengungkap rahasia.

Untuk CRM lain, periksa struktur JSON dan autentikasi. Lead CRM bukan adaptor universal: nama bidang harus mengikuti kontrak penerima.

Pada n8n, Make, Zapier, atau API sendiri, salin URL langkah penerima lalu atur bidang. Alur masuk harus aktif dan dapat dijangkau.

Memilih peristiwa

Untuk memindahkan tiap pesan ke CRM, pilih peristiwa pesan. Tugas selesai saja tidak menghasilkan satu permintaan untuk setiap pesan.

Tugas selesai tidak membuktikan setiap tindakannya berhasil. Penghitung dan kesalahan berbeda antar modul. Penerima dilewati atau gagal dikenali tidak selalu menghasilkan message.failed; peristiwa melewati penerima belum tersedia.

Balasan lead harus benar-benar diterima penangan aktif. Membuat webhook tidak mengaktifkan pemantauan akun terus-menerus atau menjamin balasan setelah tugas berakhir.

Hasil tugas memilih tiga peristiwa akhir, Semua tersedia memilih enam, Bersihkan menghapus pilihan. Pilih kembali yang dibutuhkan sebelum menyimpan.

Filter modul

Filter menentukan tugas mana yang boleh memasok peristiwa. Semua modul tidak membatasi sumber; Pilih modul membatasi ke pilihan.

task.completed dengan spampm berarti tugas pesan pribadi selesai. message.sent dengan spampm berarti satu pesan dari tugas itu terkirim.

Memilih modul tidak menambahkan jenis peristiwa. Pesan dan balasan langsung saat ini terhubung ke spam_pm; memilih modul lain tidak otomatis memberinya kemampuan itu.

Memilih data permintaan

Isi tergantung peristiwa serta daftar tersimpan. Bandingkan pratinjau dengan data terkirim dalam detail sesungguhnya.

Bidang sendiri

Pada tiap baris, isikan bidang penerima di kiri, sumber Deskgram di kanan, lalu aktifkan sakelar.

Contoh hipotetis:

Peristiwa pesan dapat menghasilkan:

{  "contact": {    "telegram_id": "123456789",    "username": "example_client"  },  "comment": "Halo!"}

Titik membuat objek bertingkat. Nilai yang tidak tersedia dihilangkan. Telepon dapat tidak ada: webhook tidak membuka nomor tersembunyi.

Menghapus atau menonaktifkan semua bidang menghasilkan {}, bukan pengganti peristiwa penuh. Pratinjau bukan data nyata calon penerima; permintaan aktual dapat lebih sedikit bidangnya.

Penyusun memilih dan mengganti nama data. Tidak menjalankan JavaScript, perhitungan, pencarian CRM, atau rantai HTTP.

Pengaturan tambahan

Contoh:

{  "Authorization": "Bearer YOUR_RECEIVER_TOKEN"}

YOURRECEIVERTOKEN berarti token sistem penerima, bukan lisensi Deskgram.

Saat mengedit melalui antarmuka, bidang rahasia tersimpan yang dibiarkan kosong mempertahankan nilai lama. Nilainya tidak ditampilkan lagi. REST API mempunyai aturan penghapusan eksplisit berbeda.

Dengan rahasia, dikirim x-secret, X-Deskgram-Webhook-Secret, X-Deskgram-Signature. Tanda tangan memverifikasi badan, tetapi rahasia itu sendiri juga dikirim dalam header. Gunakan HTTPS dan jangan memublikasikan nilainya di log. Contoh verifikasi ada dalam referensi.

Menguji koneksi

Uji mengirim webhook.test, bahkan saat endpoint nonaktif. Memeriksa HTTP dan penanganan permintaan pengujian; tidak memulai tugas Telegram.

Tidak memuat task, lead, account, message. Mapping saat ini berlaku; sumber hanya lead bisa menghasilkan objek kosong. Penerima perlu menangani pengujian secara eksplisit. Penolakan tanpa lead bisa merupakan validasi bisnis; baca status dan respons.

Hanya HTTP 200–299 berhasil. 302 bukan keberhasilan; pengalihan tidak diikuti. Gunakan URL akhir.

HTTP 200 berarti penerimaan pada lapisan HTTP, bukan bukti lead atau pesan dibuat. Periksa respons CRM dan catatan sebenarnya.

Riwayat dan percobaan ulang

Riwayat menampilkan pengiriman terbaru. Pilih penerima/status lalu segarkan daftar.

Detail memuat JSON terkirim, peristiwa asli untuk catatan baru, respons, kesalahan, jumlah percobaan, waktu. Ini bukan rekaman lengkap setiap pertukaran HTTP.

Percobaan otomatis

Maksimal tiga per pengiriman, jeda sekitar 2 dan 4 detik sebelum kedua/ketiga, di luar waktu tunggu jaringan. Respons 4xx dan 5xx juga diulang.

Semua mempertahankan X-Deskgram-Delivery-Id. Penerima sebaiknya mendeduplikasi dalam lingkup pengirim agar tindakan yang selesai tidak diulang.

Percobaan manual

1. Buka pengiriman gagal.
2. Perbaiki URL, rahasia, atau bidang jika perlu.
3. Simpan.
4. Kembali ke catatan dan pilih Coba ulang pengiriman.
5. Periksa catatan baru serta hasil di penerima.

Hanya tersedia untuk error. Membuat pengiriman baru dengan ID baru, mempertahankan catatan asal.

Catatan baru memakai peristiwa asli dan mapping saat ini. Catatan lama tanpa sumber mengirim JSON tersimpan tanpa transformasi kedua. Keduanya memakai URL, rahasia, header saat ini.

Jika penerima memproses tetapi respons hilang, retry dapat menggandakan tindakan. ID manual berbeda, sehingga CRM juga membutuhkan deduplikasi bisnis.

Nonaktif menghentikan peristiwa otomatis baru, bukan permintaan berjalan. Uji/retry eksplisit dapat mengirim saat nonaktif. Penghapusan menyimpan riwayat, tetapi menutup kemungkinan retry.

Skenario praktis

Pesan ke CRM

Pilih spampm dan message.sent, message.failed, lead.replyreceived. Gunakan JSON standar serta rahasia kanal kompatibel. Kirim ke akun uji sendiri, balas, periksa kedua pengiriman dan catatan. Ini menguji peristiwa nyata selain konektivitas.

Otomasi setelah tugas

Pilih task.completed dan modul. Gunakan JSON standar atau hasil singkat. Tambahkan task.failed serta task.cancelled jika ingin menangani kegagalan/penghentian.

Aplikasi sendiri

Atur URL, bidang, rahasia. Terima POST JSON, validasi tanda tangan, simpan/antrekan dengan andal, balas 2xx. Kerjakan proses lama terpisah. Lihat kontrak HTTP dan HMAC.

Pemecahan masalah

Pengelolaan melalui agen AI

Alat MCP memerlukan izin di Pengaturan → MCP. Perbedaannya:

• Pembuatan bawaan dry-run; endpoint baru nonaktif.
• Hanya HTTPS publik, bukan localhost, LAN, HTTP.
• Tindakan nyata yang sesuai untuk membuat, mengedit, mengaktifkan, menguji, retry mempertahankan perlindungan pada pengiriman berikutnya.
• Edit antarmuka atau mematikan MCP tidak menghapus aturan.
• Pembacaan tidak mengungkap rahasia tersimpan, nilai headers, badan lengkap.

Membaca, dry-run, menonaktifkan, menghapus mempunyai aturan sendiri dan tidak otomatis memasukkan endpoint lama dalam kebijakan. Lihat MCP.

Batasan

• Pemberitahuan keluar, bukan eksekusi jarak jauh bebas atau saluran perintah CRM permanen.
• Riwayat bukan antrean otomatis tahan restart; pengiriman terputus saat ditutup tidak dilanjutkan otomatis.
• Hanya POST JSON, tanpa GET, multipart, badan teks bebas.
• Tidak menjamin pengiriman tepat sekali atau urutan antarperistiwa.
• Hasil berbeda per modul dan bidang bisa hilang.
• Kontak, teks, parameter, hasil dapat dikirim keluar. Pilih tujuan dan bidang dengan mempertimbangkan hal itu.

Lanjutkan

Unduh Deskgram 2

Langkah berikutnya

• Semua panduan