Copy page

Integrasi

Integrasi Instagram

Integrasi Instagram

OmniStream terhubung ke DM Instagram menggunakan Instagram Login OAuth dengan token per akun. Setiap akun Instagram yang ditambahkan admin akan menukar kode otorisasi dengan access token-nya sendiri — tidak ada lagi model satu token Meta App global yang dipakai untuk semua akun.

Pendekatan per-akun ini menggantikan alur Instagram Basic Display lama. Lihat riwayat commit 393f9ae (fix Instagram integration to use Instagram Login OAuth with per-account tokens) dan cd49b7f (remove unused INSTAGRAM_LOGIN_CONFIG_ID config) di CLAUDE.md repo history untuk perubahan terkini.

Peran: Hanya Admin yang dapat menambah atau menghapus integrasi Instagram. Rute frontend: /integrations

Prasyarat

1. Meta App dengan produk Instagram (Instagram Login) aktif.
2. Instagram Business Account yang dihubungkan ke Facebook Page (Meta masih memerlukan hubungan Page meski pengguna tidak pernah membukanya).
3. Instagram App ID dan Instagram App Secret dari Meta App Dashboard.
4. URL callback OAuth yang dapat dijangkau publik: https://<host-omnistream>/integrations/instagram/callback.
5. Akses admin ke OmniStream.

Variabel lingkungan

Nilai berikut diambil dari .env.example bagian Instagram DM (via Instagram Login API):

Variabel	Kegunaan
INSTAGRAM_PAGE_ID	Opsional di .env; biasanya kosong karena integration_accounts yang menyimpan id per akun
INSTAGRAM_APP_ID	App ID dari Meta App → Instagram → Basic Display
INSTAGRAM_APP_SECRET	App Secret dari Meta App → Instagram → Basic Display
META_APP_SECRET	Dipakai untuk verifikasi HMAC webhook masuk (header X-Hub-Signature-256)
META_VERIFY_TOKEN	Handshake verifikasi webhook Meta
FRONTEND_URL	Default http://localhost:4000; dipakai untuk membangun URL redirect OAuth

Catatan: Variabel lama INSTAGRAM_LOGIN_CONFIG_ID sudah dihapus pada commit cd49b7f. Jika Anda melihatnya pada .env lama, hapus dengan aman — kode tidak lagi membacanya.

Alur OAuth per akun

Alur pendaftaran satu akun Instagram adalah sebagai berikut:

1. Admin membuka halaman Integrations (/integrations) dan klik + Add Instagram Account.
2. OmniStream membangun URL otorisasi Instagram Login berdasarkan INSTAGRAM_APP_ID dan callback https://<host>/integrations/instagram/callback.
3. Admin diarahkan ke Instagram, memilih akun yang ingin dihubungkan, dan menerima izin:
   • instagram_business_basic
   • instagram_business_manage_messages
4. Instagram memanggil kembali callback OmniStream dengan ?code=....
5. Backend menukar code dengan access token per akun melalui endpoint Graph (menggunakan INSTAGRAM_APP_ID dan INSTAGRAM_APP_SECRET).
6. Token, user_id, username, dan metadata lain disimpan ke tabel integration_accounts pada baris dengan channel = 'instagram'.
7. message-sender akan mulai memakai token tersebut saat mengirim DM keluar untuk akun itu. webhook-ingestor akan memetakan event masuk ke akun berdasarkan entry[].id (IG user id).

Langkah-langkah setup

1. Konfigurasi Meta App

1. Di developers.facebook.com, buka app Anda.
2. Tambahkan produk Instagram → Instagram Login jika belum.
3. Di Instagram → Basic Display, salin Instagram App ID dan Instagram App Secret. Simpan ke .env:

   Code
   INSTAGRAM_APP_ID=123456789012345
   INSTAGRAM_APP_SECRET=abcdef0123456789

4. Pada Valid OAuth Redirect URIs, tambahkan: https://<host-omnistream>/integrations/instagram/callback serta variannya jika Anda punya environment staging.

2. Konfigurasi webhook Instagram

1. Di Meta App → Instagram → Webhooks, klik Configure.
2. Masukkan Callback URL: https://<host-omnistream>/webhook/instagram
   • webhook-ingestor adalah satu binary yang mendengarkan di WEBHOOK_INGESTOR_PORT (default 3001 di local dev). Port yang sama melayani rute WhatsApp, Instagram, Messenger, dan Email.
3. Masukkan Verify Token sama dengan META_VERIFY_TOKEN.
4. Langganan ke event messages dan messaging_postbacks.

3. Mulai alur OAuth dari UI OmniStream

1. Masuk sebagai admin ke OmniStream.
2. Buka Integrations, klik tab Instagram.
3. Klik + Connect Instagram Account.
4. Pilih halaman/akun pada dialog Meta dan berikan izin.
5. Setelah redirect kembali ke OmniStream, baris baru muncul di tabel Instagram Accounts dengan username yang terdeteksi.

4. Kirim pesan uji

1. Dari akun Instagram lain, kirim DM ke akun yang baru dihubungkan.
2. Percakapan baru akan muncul di Inbox OmniStream.
3. Balas dari Inbox; pesan keluar dikirim memakai access token per-akun yang tersimpan.
4. Jika balasan gagal, buka halaman Integrations dan lakukan Re-authenticate pada akun yang bermasalah — ini memicu siklus OAuth ulang tanpa menghapus riwayat percakapan.

Model per akun: mengapa penting

Sebelum commit 393f9ae, OmniStream menyimpan satu kredensial Instagram global yang dibagi-pakai oleh semua integration account. Akibatnya satu token kedaluwarsa bisa memadamkan seluruh saluran, dan Meta juga tidak mengizinkannya untuk Instagram Login.

Setelah commit tersebut, setiap baris di integration_accounts memiliki access token-nya sendiri pada config. Implikasi operasionalnya:

• Menghapus satu akun tidak mempengaruhi akun Instagram lain.
• Token kedaluwarsa hanya memadamkan satu akun; admin cukup re-authenticate akun tersebut.
• Webhook masuk dipetakan ke akun berdasarkan entry[].id via query: SELECT id FROM integration_accounts WHERE channel = 'instagram' AND config->>'user_id' = $1 AND is_active = true

Troubleshooting

• OAuth redirect ditolak oleh Instagram — pastikan URL callback di Meta App Dashboard tepat sama dengan yang OmniStream pakai, termasuk skema https://. Meta ketat terhadap trailing slash.
• Webhook verification gagal — META_VERIFY_TOKEN tidak cocok. Token ini sama untuk WhatsApp, Instagram, dan Messenger karena satu Meta App.
• HMAC InvalidSignature pada webhook — META_APP_SECRET tidak cocok. Tidak bisa di-hot-reload; restart webhook-ingestor.
• Token kedaluwarsa pada satu akun — buka Integrations, pilih akun, klik Re-authenticate untuk memulai OAuth ulang.

Hubungan dengan API Reference

Tag Integrations pada API Reference menampilkan endpoint untuk mengelola konfigurasi saluran. Endpoint untuk integration_accounts Instagram memungkinkan inspeksi daftar akun yang terhubung, dengan rahasia di-mask pada respons.