Integrasi Webhook Masuk

Dibuat Pada15 Maret 2021

TimelinesAI memungkinkan Anda mengotomatiskan pengiriman pesan WhatsApp sebagai respons terhadap peristiwa atau tindakan dalam alat yang sudah Anda gunakan: CRM, Dukungan, Sistem perekrutan, dll.

Peristiwa "Kirim pesan"

Dimungkinkan untuk menginstruksikan TimelinesAI untuk mengirim pesan (dengan atau tanpa lampiran file) ke kontak tertentu (dapat berupa grup). Jika beberapa akun WhatsApp terhubung di ruang kerja Anda, Anda juga dapat menentukan akun WhatsApp tertentu yang akan digunakan untuk mengirim pesan.

Untuk mengatur integrasi, pemilik ruang kerja harus menavigasi ke layar "Integrations / Inbound Webhooks" dan membuat URL baru. Sistem eksternal harus mengirim pesan dalam format tertentu (lihat detail di bawah) ke URL tersebut.

Keterbatasan

Ukuran maksimum lampiran adalah 2 MB.
Tidak ada validasi langsung atas format nomor telepon penerima atau koneksi ke WhatsApp. Arahkan ke Timeline UI untuk memverifikasi status pengiriman / pembacaan pesan.

Mengirim File melalui Inbound Webhook

Mengirim File: Pengunduhan Langsung vs Layanan Hosting File

Sangat penting untuk mengirim file menggunakan Tautan Unduhan Langsung. Hal ini memungkinkan penerima untuk benar-benar menerima file tersebut.

Sedangkan layanan file hosting harus digunakan sehingga dapat menyediakan tautan unduhan langsung. Tautan seperti itu paling baik diuji melalui penjelajahan penyamaran/private; dengan menempelkan tautan di bilah pencarian. Jika unduhan file langsung dimulai, tautan tersebut dapat diterima. Jika sebaliknya, halaman web apa pun yang ditampilkan, maka tautan tersebut tidak dapat digunakan untuk mengirim file.

Masalahnya dengan tautan Layanan Hosting File adalah file tidak dapat diunduh. Yang diunduh dan dikirim adalah halaman web berbagi, yang dapat menyebabkan file "rusak".

Hal ini, pada gilirannya, akan memengaruhi pesan Anda karena penerima tidak dapat mengakses media yang Anda kirimkan, sehingga file tidak dapat digunakan. Oleh karena itu, sangat penting bagi Anda untuk memastikan bahwa Anda mengirimkan tautan unduhan langsung, karena hal ini akan memungkinkan mereka untuk mengakses file tanpa masalah.

Anda juga dapat menjalankan tes ini dengan mengirimkan pesan webhook ke salah satu nomor tes Anda. Anda akan dapat menentukan bagaimana file akan berperilaku berdasarkan apa yang telah kami ulas di sini; jika Anda mendapatkan pesan kesalahan seperti "File Rusak", "File Tidak Kompatibel"; atau "Gagal memuat dokumen X", setelah mengeklik lampiran, maka ini adalah Tautan Layanan Hosting File dan harus diganti dengan Tautan Unduhan Langsung.

Pemanfaatan Kredit

Mengirim pesan menggunakan 1 pulsa dari kuota pengiriman pesan.
Mengirim pesan dengan teks dan lampiran yang tidak kosong akan menghabiskan 2 kredit dari kuota pengiriman pesan.
Jika pesan tidak dapat terkirim (tidak valid atau tidak terhubung ke nomor WhatsApp, server WhatsApp error), kuota pengiriman pesan akan dipulihkan (biasanya dalam beberapa jam).

Tingkat pengiriman pesan

Pesan akan dikirim dengan penundaan acak sekitar 2 detik di antara dua pesan (untuk menghindari mekanisme deteksi spam WhatsApp).
Jika Anda mengaktifkan webhook dengan frekuensi kurang dari 2 detik, pesan akan diantrekan dan dikirim dengan penundaan. Setiap pesan yang mengantri akan menggunakan pulsa pengiriman pesan, sehingga jumlah pesan yang mengantri tidak dapat melebihi kuota yang tersedia.

Konfigurasi dan tindakan webhook

"Webhook diaktifkan" - memungkinkan untuk menonaktifkan webhook tanpa melepasnya sepenuhnya
"Buat URL baru" - akan membuat URL baru yang unik, yang akan menerima notifikasi. URL sebelumnya tidak akan tersedia lagi.
"Upaya pengiriman terakhir" - status upaya aktivasi webhook terakhir
"Download log" - log terperinci dari 100 upaya aktivasi terakhir, berguna untuk memecahkan masalah pemformatan.

Format permintaan webhook

Webhook menerima data dalam format JSON, melalui permintaan POST.

"action" (wajib) - saat ini, hanya satu nilai yang didukung yaitu "send"
"text" (wajib) - teks biasa yang dikodekan dengan UTF-8 yang akan dikirim (tidak didukung tanda baca, kecuali pemisah baris "\n"), dapat dikosongkan, jika file ditentukan.
"file_url" (opsional) - URL yang dapat diakses publik dari file yang akan diunduh dan dikirim sebagai lampiran.
"nama_file" (opsional) - nama untuk lampiran (harus disediakan, jika URL ditentukan).

Penerima dapat ditentukan dengan memberikan salah satu parameter berikut ini:

"chat_id" - id obrolan seperti yang muncul di TimelinesAI (dapat ditemukan di URL halaman obrolan, atau dalam muatan webhook keluar). Ini mendukung pengiriman pesan ke grup.
"jid" - JID WhatsApp yang menentukan kontak atau grup
"telepon" - nomor telepon, diformat sesuai dengan standar nomor telepon internasional, yaitu:
[+][kode negara][kode area][nomor telepon lokal] (misalnya: +14151231234)
"chat_name" - nama yang tepat untuk obrolan seperti yang muncul di TimelinesAI

Jika beberapa akun WhatsApp terhubung di ruang kerja, gunakan parameter tambahan berikut ini untuk menentukan akun WhatsApp yang akan digunakan:

"whatsapp account phone" (opsional) - menentukan (sebagai nomor telepon, dalam format internasional) akun WhatsApp yang akan digunakan untuk mengirim. Jika dihilangkan, akun WhatsApp aktif yang terakhir terhubung di ruang kerja akan digunakan untuk mengirim. Catatan: jika parameter "chat_id" ditentukan, "whatsapp account phone" akan diabaikan, karena setiap obrolan sudah terhubung ke akun WhatsApp tertentu.

Respons Webhook

Jika berhasil (permintaan divalidasi dan diterima untuk dikirim), Webhook akan merespons dengan status HTTP 200 dan JSON, yang berisi message_id dari pesan yang dibuat:

{
    "status": "success",
    "data": {
        "message_id": "wa_backend:3EB09FCC85FE99662E46"
    }
}

Jika terjadi kesalahan, Webhook akan merespons dengan status HTTP 40X dan JSON dengan rincian kesalahan, misalnya:

{
"status": 40X,
"data": {},
"message": "Webhook not found"
}

Contoh

Contoh 1 - mengirim pesan melalui akun WA tertentu ke nomor telepon tertentu:

{
"action": "send",
"whatsapp account phone" : "+15105566777", 
"phone": "+14151231234", 
"text": "lorem ipsum"
}

Contoh 2 - mengirim pesan dengan teks dan lampiran ke obrolan (atau grup) yang ditentukan oleh id:

{
"action": "send", 
"chat_id": "77234", 
"text": "lorem ipsum"
"file_url" : "https://150588669.v2.pressablecdn.com/logo.png",
"file_name" : "logo.png"
}