Copy page

Self-Hosting

Meta App Setup

Meta App Setup

OmniStream menghubungi tiga channel Meta: WhatsApp (Cloud API), Instagram DM, dan Facebook Messenger. Ketiganya memakai satu Meta Developer App namun product yang berbeda. Halaman ini merangkum langkah-langkah yang diperlukan di developers.facebook.com untuk menyambungkan app ke instance self-hosted anda.

Prasyarat

• Akun Meta Business Manager
• Nomor telepon terdaftar di WhatsApp Business Account (WABA) untuk channel WA
• Akun Instagram Business terhubung ke Facebook Page untuk channel IG
• Facebook Page untuk channel Messenger
• Domain publik dengan HTTPS (Meta menolak http:// dan localhost untuk webhook produksi)

Env var yang terlibat

Lihat developer/self-hosting/environment-variables untuk tabel lengkap. Yang relevan di sini:

Var	Peran
META_APP_SECRET	Verifikasi HMAC webhook Meta
META_VERIFY_TOKEN	Challenge GET webhook (harus sama dengan yang diset di Meta)
META_ACCESS_TOKEN	System User token long-lived, bisa di-override dari DB
META_PHONE_NUMBER_ID	Phone Number ID dari WABA
META_API_URL	Default https://graph.facebook.com/v21.0
INSTAGRAM_APP_ID	Instagram Login app id
INSTAGRAM_APP_SECRET	Instagram Login app secret
MESSENGER_LOGIN_CONFIG_ID	Facebook Login Configuration ID untuk Messenger

Langkah besar untuk setiap channel

WhatsApp Cloud API

1. Buat App di Meta for Developers dengan tipe Business.
2. Tambahkan product WhatsApp → Select/Create WABA → Tambah phone number.
3. Catat Phone Number ID, WABA ID, dan generate System User access token dengan permission whatsapp_business_messaging + whatsapp_business_management. Isi ke META_ACCESS_TOKEN atau simpan via UI Settings → Integrations.
4. Webhook:
   • Callback URL: https://your-domain.com/webhook/whatsapp (di-proxy ke binary webhook-ingestor pada port WEBHOOK_INGESTOR_PORT)
   • Verify Token: nilai META_VERIFY_TOKEN anda
   • Subscribe ke field: messages, message_template_status_update, message_status
5. Simpan App Secret di META_APP_SECRET. Webhook-ingestor memverifikasi HMAC-SHA256 setiap request dengan secret ini — lihat developer/webhook/inbound-whatsapp.

Instagram DM

1. Di App yang sama, tambahkan product Instagram → Instagram API with Instagram Login.
2. Catat App ID dan App Secret Instagram Login, isi ke INSTAGRAM_APP_ID + INSTAGRAM_APP_SECRET.
3. Tambahkan redirect OAuth di Meta dashboard yang menunjuk ke endpoint API gateway untuk OAuth callback (lihat panduan/integrasi/instagram).
4. Webhook Instagram:
   • Callback URL: https://your-domain.com/webhook/instagram (di-proxy ke binary webhook-ingestor pada port WEBHOOK_INGESTOR_PORT)
   • Verify Token: sama dengan META_VERIFY_TOKEN
   • Subscribe ke field: messages, messaging_postbacks, messaging_seen

Facebook Messenger

1. Di App yang sama, tambahkan product Messenger.
2. Buat Login Configuration ID di Facebook Login for Business → Use Cases → "Authenticate and request data". Isi ke MESSENGER_LOGIN_CONFIG_ID.
3. Link satu Facebook Page dan generate Page Access Token — disimpan ke tabel integrations via UI admin.
4. Webhook Messenger di-proxy ke webhook-ingestor yang sama dengan ingestor Messenger (lihat developer/webhook/inbound-* untuk topologi detail per channel).

HMAC verification webhook

Setiap request webhook dari Meta disertai header X-Hub-Signature-256: sha256=<hex> yang dihitung dengan key = META_APP_SECRET. File crates/webhook-ingestor/src/routes.rs memverifikasi signature ini sebelum memforward payload ke Kafka. Kalau secret salah set, anda akan melihat log "signature mismatch" di webhook-ingestor-* dan response 401 ke Meta.

Rotasi token

message-sender-* dan api-gateway mem-poll tabel integrations setiap 30 detik. Anda dapat merotasi access_token lewat UI Settings → Integrations tanpa restart — perubahan akan efektif di polling berikutnya. Nilai .env tetap berfungsi sebagai fallback saat tidak ada row aktif di tabel.

Troubleshooting cepat

• signature mismatch di webhook-ingestor log → META_APP_SECRET tidak cocok dengan App Secret di Meta dashboard.
• 403 challenge fail di setup webhook → META_VERIFY_TOKEN tidak cocok.
• 401 Invalid OAuth access token dari Graph API → token kadaluwarsa, rotasi via UI.
• Rate limit Meta (429 atau 80004) → turunkan max_concurrent_chats atau tambahkan backoff di custom scheduler; message-sender sudah memakai retry eksponensial.