# Integrasi

Hubungkan agen ke aplikasi lain lewat Public API dan Webhooks, dan batasi siapa yang dibalas di WhatsApp dengan Whitelister.

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

| Fitur | Fungsi | Paket |
| --- | --- | --- |
| Public API | Mengirim pesan dan membaca data agen dari aplikasi lain, misalnya n8n atau Zapier | Pro |
| Webhooks | Meneruskan event Instagram, TikTok, dan WhatsApp ke endpoint kamu | Pro |
| Whitelister | Agen hanya membalas nomor WhatsApp yang ada di daftar | Butuh WhatsApp terhubung |

{% hint style="info" %}
Panduan ini untuk **dashboard baru** dibales.ai.
{% endhint %}

## 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](/dashboard/mulai/hubungkan-akun).

#### 1. Buka Integrasi

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

![Halaman Integrasi](/assets/dashboard/integrasi/int-01-hub.png)

1. **Koneksi platform**: akun Instagram, TikTok, dan WhatsApp yang dibalas agen ini. Klik **Kelola** untuk membuka halaman koneksinya, lihat [Hubungkan Akun](/dashboard/mulai/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**.

![Halaman Public API](/assets/dashboard/integrasi/int-02-api.png)

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**.

![API key baru](/assets/dashboard/integrasi/int-03-api-key.png)

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**.

![Halaman Webhooks](/assets/dashboard/integrasi/int-04-webhooks.png)

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.

![Kartu webhook](/assets/dashboard/integrasi/int-05-webhook-kartu.png)

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

![Tambah webhook](/assets/dashboard/integrasi/int-06-webhook-baru.png)

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.

![Webhook Secret](/assets/dashboard/integrasi/int-07-secret.png)

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**.

![Pengaturan Whitelister](/assets/dashboard/integrasi/int-08-whitelister.png)

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

| Masalah | Solusi |
| --- | --- |
| **Public API ada di paket Pro** atau **Webhooks ada di paket Pro** | Upgrade agen ke Pro di [Billing](/dashboard/akun/billing). |
| Semua API key ditolak, atau semua webhook dijeda | Agen tidak lagi di paket Pro. Klik **Upgrade ke Pro**, dan key serta webhook aktif lagi. |
| *URL harus diawali https://* | Pakai alamat endpoint yang diawali `https://`. |
| *Endpoint membalas 2xx, tapi body-nya tidak sama dengan nilai challenge.* | Endpoint-mu harus membalas nilai parameter `?challenge=` persis sebagai body. |
| *Endpoint membalas HTTP …* atau *Endpoint tidak bisa dihubungi …* | Pastikan URL benar, aktif, bisa diakses publik, dan membalas 2xx. |
| *Pilih minimal satu platform.* | Nyalakan minimal satu platform di form webhook. |
| Webhook **Dinonaktifkan otomatis** | Webhook gagal terlalu banyak kali berturut-turut. Perbaiki endpoint-nya, lalu klik **Aktifkan**. |
| *Terlalu sering mengirim tes.* atau *Terlalu sering membuat webhook.* | Tunggu sesuai waktu yang tertulis, lalu coba lagi. |
| Signature event tidak cocok setelah klik **Buat ulang** | Secret lama langsung tidak berlaku. Perbarui nilai secret di sistemmu. |
| *Isi nomor yang valid, … digit termasuk kode negara.* atau *Nomor ini sudah ada di daftar.* | Tulis nomor lengkap dengan kode negara, misalnya `6281234567890`, dan jangan masukkan nomor yang sama dua kali. |