Integrasi

Halaman Integrasi mengumpulkan semua sambungan agen: akun platform, alat untuk developer (Public API dan Webhooks), dan aplikasi tambahan seperti Whitelister.

Sebelum mulai

• Paket Pro untuk Public API dan Webhooks. Di paket Plus, kartunya bertuliskan Tersedia di paket Pro.
• Endpoint HTTPS yang bisa diakses publik, kalau mau memakai Webhooks, misalnya webhook node di n8n.
• WhatsApp yang sudah terhubung, kalau mau memakai Whitelister. Lihat Hubungkan Akun.

1. Buka Integrasi

Di sidebar, klik Integrasi. Di HP, buka dulu menunya lewat ikon ☰ di kanan atas.

DesktopHP

1. Koneksi platform: akun Instagram, TikTok, dan WhatsApp yang dibalas agen ini. Klik Kelola untuk membuka halaman koneksinya, lihat Hubungkan Akun.
2. Untuk developer: Public API dan Webhooks untuk menyambungkan agen ke n8n, Zapier, atau sistem kamu sendiri.
3. Aplikasi: tambahan seperti Whitelister untuk mengatur siapa yang dibalas agen.

---

Public API (paket Pro)

2. Buat API key

Klik kartu Public API.

DesktopHP

1. Buat API Key: beri nama supaya kamu ingat key ini dipakai di mana, misalnya n8n Production, lalu klik Buat.
2. Daftar API key: nama, key yang disamarkan, status, kapan terakhir dipakai, dan tanggal dibuat. Klik ikon tempat sampah untuk menghapus key. Aplikasi yang memakai key itu langsung berhenti bekerja.
3. Cara memakai: Base URL (https://public-api.dibales.ai) dan Header autentikasi (Authorization: Bearer <API key>). Setiap API key hanya berlaku untuk agen ini. Daftar endpoint dan batas permintaannya ada di Dokumentasi API.

DesktopHP

1. API key hanya ditampilkan sekali. Klik Salin, lalu simpan di tempat yang aman.
2. Klik Sudah saya simpan. Setelah jendela ini ditutup, key tidak bisa dilihat lagi. Kalau hilang, hapus key-nya lalu buat yang baru.

💡 Kalau agen tidak lagi di paket Pro, semua API key ditolak sampai agen di-upgrade lagi.

---

Webhooks (paket Pro)

Webhooks mengirim event dari Instagram, TikTok, dan WhatsApp ke URL kamu secara langsung, misalnya untuk mencatat DM baru ke Google Sheets atau memberi notifikasi di Slack.

3. Halaman Webhooks

Klik kartu Webhooks.

DesktopHP

1. Webhook Secret dan Tambah Webhook (lihat langkah 4 dan 5). Di bawahnya ada ringkasan jumlah webhook, antrean, dan tingkat keberhasilan pengiriman 24 jam terakhir.
2. Tab Webhook berisi daftar webhook, Log Pengiriman berisi riwayat setiap event yang dikirim, dan Contoh Event berisi contoh payload untuk setiap event.

DesktopHP

1. Setiap kartu webhook menampilkan nama, status, platform, dan URL endpoint-nya:
   • Kirim tes: mengirim event test.ping ke endpoint. Event tes tidak masuk ke Log Pengiriman.
   • Jeda / Aktifkan: menghentikan atau menjalankan lagi pengiriman ke webhook ini.
   • Edit dan Hapus. Webhook yang dihapus berhenti menerima event dan log pengirimannya ikut terhapus.

Setiap pengiriman dicoba sampai 5 kali, dengan jeda 30 detik, 2 menit, 10 menit, lalu 1 jam. Webhook yang gagal 300 kali berturut-turut dinonaktifkan otomatis. Perbaiki endpoint-nya, lalu klik Aktifkan. Log pengiriman disimpan selama 30 hari, dan pengiriman yang gagal bisa dikirim ulang lewat Coba ulang.

---

4. Tambah webhook

DesktopHP

1. Nama (opsional): misalnya n8n Order Masuk.
2. URL: alamat endpoint kamu, wajib diawali https://. Saat disimpan, kami mengirim GET ke URL ini dengan query ?challenge=nilai. Endpoint harus membalas status 2xx dengan body yang persis sama dengan nilai challenge.
3. Platform: nyalakan platform yang event-nya mau diteruskan.
   • Instagram: DM, komentar, balasan story, dan mention.
   • TikTok: DM dan komentar.
   • WhatsApp: pesan, reaksi, tanda dibaca, dan status akun.

Klik Simpan. Semua event dari platform yang dipilih dikirim ke URL ini.

Cek hasilnya: klik Kirim tes di kartu webhook. Kalau berhasil, muncul Tes terkirim, endpoint membalas … dan event test.ping sampai di endpoint-mu. Setelah itu, kirim DM atau komentar sungguhan dari akun lain, lalu cek tab Log Pengiriman.

---

5. Verifikasi event dengan Webhook Secret

Klik Webhook Secret untuk memastikan event yang masuk benar-benar dari dibales.ai.

DesktopHP

1. Satu secret berlaku untuk semua webhook di agen ini. Klik Tampilkan atau Salin untuk melihatnya, atau Buat ulang kalau secret-nya bocor. Secret lama langsung tidak berlaku, jadi perbarui juga nilainya di sistem kamu.
2. Cara memverifikasi event:
   • ambil header X-Dibales-Timestamp dan X-Dibales-Signature dari request;
   • gabungkan timestamp, satu titik, dan body mentah request, lalu hitung HMAC-SHA256 dengan secret ini dalam format hex;
   • bandingkan hasilnya dengan nilai setelah v1= di X-Dibales-Signature. Tolak request kalau berbeda atau timestamp-nya lebih tua dari 5 menit.

---

Whitelister

Whitelister membuat agen hanya membalas nomor WhatsApp yang ada di daftar, misalnya kalau nomor WhatsApp-mu khusus untuk pelanggan terdaftar. Instagram dan TikTok tidak disaring. Whitelister baru berpengaruh kalau WhatsApp sudah terhubung.

6. Atur Whitelister

Di bagian Aplikasi, klik Aktifkan (atau Atur kalau sudah aktif) di kartu Whitelister.

DesktopHP

1. Nomor yang diizinkan: isi Nama dan Nomor WhatsApp, lalu klik Tambah nomor. Nomornya harus sama persis dengan nomor pengirim, termasuk kode negara.
2. Pesan penolakan (opsional): dikirim ke nomor di luar daftar. Kosongkan kalau nomor di luar daftar tidak perlu dibalas.

Klik Simpan dan aktifkan (atau Simpan). Untuk mematikannya, klik Nonaktifkan di kartu Whitelister. Agen kembali membalas semua nomor, dan daftar nomornya tetap tersimpan.

Cek hasilnya: muncul Whitelister disimpan dan aktif. Kirim pesan ke nomor agen dari nomor di dalam daftar (dibalas seperti biasa) dan dari nomor di luar daftar (tidak dibalas, atau menerima pesan penolakan kalau diisi).

Kalau ada kendala