Copy page

Hubungkan Channel

Integrasi WhatsApp

Panduan ini menjelaskan cara menghubungkan nomor WhatsApp Business melalui Meta WhatsApp Cloud API ke OmniStream menggunakan alur manual. Setelah selesai, pesan masuk ke nomor tersebut akan muncul di inbox OmniStream, dan balasan keluar akan dikirim kembali melalui Cloud API.

Peran: Hanya Admin yang dapat membuka halaman Integrations. Rute frontend: /integrations

Prasyarat

1. Meta App di developers.facebook.com dengan produk WhatsApp aktif.
2. WhatsApp Business Account (WABA) yang terhubung ke Meta App.
3. Nomor telepon yang telah ditambahkan ke WABA dan memiliki phone_number_id.
4. Permanent access token dengan izin whatsapp_business_messaging dan whatsapp_business_management.
5. Akses ke server OmniStream Anda pada URL publik (misalnya https://omnistream.example.com) agar Meta dapat memanggil webhook.

Kredensial yang dibutuhkan

Nilai berikut diperlukan untuk menghubungkan WhatsApp. Masukkan di UI Integrations atau konfigurasikan pada server oleh administrator:

Kredensial	Asal
Meta App Secret	Meta App Dashboard → Settings → Basic — untuk verifikasi tanda tangan webhook
Meta Verify Token	Nilai bebas yang Anda tentukan — untuk handshake verifikasi webhook Meta
Meta Access Token	Meta App Dashboard → WhatsApp → API Setup
Meta Phone Number ID	Meta App Dashboard → WhatsApp → API Setup

Langkah-langkah

1. Dapatkan kredensial Meta

1. Masuk ke developers.facebook.com.
2. Pilih app Anda, lalu buka App Settings → Basic.
3. Salin App Secret; berikan ke administrator server untuk dikonfigurasi.
4. Buka WhatsApp → API Setup dan salin:
   • Temporary access token (untuk uji coba) atau buat System User untuk permanent token.
   • Phone number ID dari nomor yang akan dipakai.
5. Tentukan Verify Token sendiri — nilai bebas yang Anda tentukan, harus cocok antara konfigurasi OmniStream dan Meta App Dashboard.

2. Konfigurasikan kredensial

Masukkan nilai yang didapat dari Meta ke UI Integrations → tab WhatsApp, atau minta administrator server untuk mengisi konfigurasi. Perubahan via UI Integrations aktif dalam 30 detik (hot-reload otomatis).

3. Konfigurasi webhook di Meta App Dashboard

1. Di Meta App → WhatsApp → Configuration → Webhook, klik Edit.
2. Masukkan Callback URL: https://<host-omnistream>/webhook/whatsapp
   • Di development lokal, Anda memerlukan tunnel publik (misalnya ngrok) agar Meta dapat menjangkau server Anda.
3. Masukkan Verify Token: nilai yang sama dengan yang dikonfigurasi di OmniStream.
4. Klik Verify and Save. Meta akan mengirim GET /webhook/whatsapp dengan hub.mode=subscribe; OmniStream akan membalas hub.challenge jika token cocok.
5. Pada bagian Webhook fields, langganan ke event messages.

4. Tambahkan integrasi di UI OmniStream

1. Masuk sebagai admin dan buka Integrations (/integrations).
2. Klik + Add Integration, pilih channel WhatsApp.
3. Masukkan phone_number_id, access_token, dan setelan opsional lain (misalnya division_id jika memakai divisi).
4. Klik Save. Baris baru muncul pada tabel integrations dengan is_active = true.
5. Tunggu sampai 30 detik agar konfigurasi aktif (hot-reload otomatis).

5. Kirim pesan uji

1. Dari perangkat lain, kirim pesan WhatsApp ke nomor yang baru saja dikonfigurasi.
2. Buka Inbox di OmniStream; percakapan baru akan muncul dalam beberapa detik.
3. Balas dari Inbox. Pesan akan dikirim kembali melalui Graph API menggunakan META_ACCESS_TOKEN.
4. Jika pesan uji tidak muncul, periksa bahwa Meta App Secret di konfigurasi OmniStream cocok dengan yang ada di Meta App Dashboard — ini adalah penyebab paling umum kegagalan.

Multi-tenant dan atribusi akun

OmniStream menangani payload WhatsApp multi-akun dengan benar: satu request dari Meta yang berisi pesan untuk beberapa nomor akan diproses secara terpisah berdasarkan phone_number_id, tanpa ada pesan yang bocor ke akun lain.

Troubleshooting

• Webhook verification gagal (HTTP 401) — periksa bahwa Meta Verify Token di konfigurasi OmniStream identik dengan yang dimasukkan di Meta App Dashboard.
• Semua payload masuk ditolak InvalidSignature — Meta App Secret tidak cocok. Hubungi administrator untuk memperbarui konfigurasi server.
• Pesan keluar ditolak (#190) Invalid OAuth access token — Meta Access Token kedaluwarsa. Buat token permanen lewat System User, lalu perbarui lewat UI Integrations.
• Nomor tidak dikenali — pastikan Phone Number ID pada integrasi sesuai dengan nomor yang ada di Meta App Dashboard.

WhatsApp Embedded Signup

Hubungan dengan API Reference

Endpoint REST untuk mengelola integrasi WhatsApp tersedia di bawah tag Integrations pada API Reference, termasuk PUT /api/integrations/whatsapp untuk upsert dan GET /api/integrations/whatsapp untuk inspeksi (config di-mask).