Copy page

Integrasi

Integrasi WhatsApp

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.

Variabel lingkungan yang dibutuhkan

Nilai berikut berasal dari .env.example dan juga dapat dikelola melalui UI Integrations (kecuali META_APP_SECRET dan META_VERIFY_TOKEN yang selalu dibaca dari .env):

Variabel	Asal	Kegunaan
META_APP_SECRET	Meta App Dashboard → Settings → Basic	Memverifikasi tanda tangan X-Hub-Signature-256 pada webhook
META_VERIFY_TOKEN	Anda yang menentukan	Nilai sembarang untuk handshake verifikasi webhook Meta
META_ACCESS_TOKEN	Meta App Dashboard → WhatsApp → API Setup	Token bearer untuk mengirim pesan ke Cloud API
META_PHONE_NUMBER_ID	Meta App Dashboard → WhatsApp → API Setup	ID numerik nomor WhatsApp yang dipakai
META_API_URL	default https://graph.facebook.com/v21.0	Endpoint Graph API Meta

Lihat .env.example di akar repo untuk nilai fallback lengkap.

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; simpan sebagai META_APP_SECRET di .env server OmniStream.
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 META_VERIFY_TOKEN sendiri. Nilai ini harus cocok antara .env dan Meta App Dashboard.

2. Isi .env di server

Code
META_APP_SECRET=abcdef1234567890
META_VERIFY_TOKEN=omnistream-verify-token
META_ACCESS_TOKEN=EAAxxxxxxxxxxxx
META_PHONE_NUMBER_ID=1234567890123456

Restart webhook-ingestor dan message-sender satu kali setelah mengubah .env. Perubahan via UI Integrations setelah itu tidak memerlukan restart (hot-reload 30 detik).

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, OmniStream mengekspos webhook-ingestor pada port 3001; Anda perlu tunnel (misalnya ngrok) agar Meta dapat menjangkaunya.
3. Masukkan Verify Token: nilai yang sama dengan META_VERIFY_TOKEN di .env.
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 message-sender dan webhook-ingestor memuat ulang konfigurasi (hot-reload).

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 log webhook-ingestor — kegagalan HMAC paling sering disebabkan oleh META_APP_SECRET yang tidak cocok antara Meta dan .env.

Multi-tenant dan atribusi akun

webhook-ingestor menangani payload WhatsApp multi-tenant dengan benar: setiap entry[].changes[] diemit sebagai event Kafka terpisah dan dipetakan ke integration_account_id berdasarkan value.metadata.phone_number_id. Jadi satu request dari Meta yang berisi pesan untuk beberapa nomor akan terbagi rapi ke integrasi masing-masing tanpa bocor ke tenant lain.

Troubleshooting

• Webhook verification gagal (HTTP 401) — periksa META_VERIFY_TOKEN di .env identik dengan yang dimasukkan di Meta App Dashboard.
• Semua payload masuk ditolak InvalidSignature — META_APP_SECRET tidak cocok. Token ini tidak bisa di-hot-reload; perlu restart proses webhook-ingestor setelah mengubah .env.
• 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 integration_account sesuai dengan yang ada di metadata.phone_number_id Meta.

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