Copy page

Integrasi

Ikhtisar Integrasi

Ikhtisar Integrasi

Halaman Integrations adalah pusat kendali tempat admin menghubungkan OmniStream ke saluran pesan eksternal: WhatsApp Cloud API, Instagram Login, dan SMTP email. Setiap saluran disimpan sebagai baris pada tabel integrations di PostgreSQL dan dipakai oleh webhook-ingestor maupun message-sender saat runtime.

Halaman ini membahas alur umum yang berlaku untuk semua saluran. Detail spesifik per saluran tersedia di:

• Integrasi WhatsApp — Meta WhatsApp Cloud API
• Integrasi Instagram — Instagram Login OAuth per akun
• Integrasi Facebook Messenger — Messenger via halaman Facebook
• Integrasi Email — SMTP + webhook masuk

Peran: Hanya pengguna dengan peran Admin atau Supervisor yang dapat membuka dan menyunting halaman Integrations. Agent tidak memiliki akses.

Cara mengakses

1. Masuk ke OmniStream sebagai admin.
2. Pada sidebar kiri, klik Integrations (rute frontend /integrations).
3. Halaman menampilkan daftar semua saluran yang sudah terdaftar beserta status aktif/nonaktif.

Konsep inti

Integration vs Integration Account

OmniStream memisahkan dua tingkat konfigurasi:

• Integration — satu baris per saluran (whatsapp, instagram, messenger, email). Berisi setelan global untuk saluran tersebut, seperti META_APP_SECRET untuk keluarga Meta.
• Integration Account — akun konkret di saluran itu, misalnya satu nomor telepon WhatsApp atau satu akun Instagram. Satu saluran dapat memiliki banyak akun (multi-tenant).

Webhook masuk dipetakan ke Integration Account berdasarkan identitas pada payload (misalnya phone_number_id untuk WhatsApp atau user_id untuk Instagram). Ini memastikan setiap kejadian webhook diatribusikan ke akun yang benar walaupun Meta mengirim satu request berisi banyak entri.

Sumber konfigurasi: database atau .env

Setiap integrasi dapat dikonfigurasi melalui:

1. Database — lewat UI Integrations; nilai disimpan di kolom config (JSONB) dan dibaca ulang setiap 30 detik oleh message-sender dan webhook-ingestor.
2. File .env — nilai di .env berfungsi sebagai fallback bila belum ada konfigurasi di DB. Variabel META_APP_SECRET dan META_VERIFY_TOKEN selalu dibaca dari .env karena Meta hanya mengizinkan satu verify token global per aplikasi.

Lihat daftar lengkap variabel di halaman Environment Variables.

Hot-reload 30 detik

Setelah admin menyunting konfigurasi di UI dan menyimpannya, tidak perlu me-restart webhook-ingestor atau message-sender. Kedua layanan menjalankan background poller yang:

1. Membaca seluruh baris aktif dari tabel integrations setiap 30 detik.
2. Membandingkan fingerprint konfigurasi dengan versi terakhir yang diingat.
3. Memutakhirkan secrets di memori hanya jika ada perubahan.

Artinya setiap perubahan di UI akan aktif paling lambat 30 detik kemudian. Implementasi poller dibagikan melalui omni_common::ConfigPoller sehingga seluruh layanan memakai logika yang identik.

Catatan teknis: Poller menggunakan Integration::fetch_active() yang hanya mengembalikan baris dengan is_active = true. Menonaktifkan integrasi berarti layanan segera berhenti memakainya pada siklus polling berikutnya — cara aman untuk memadamkan saluran tanpa menghapus konfigurasinya.

Status per integrasi

Setiap baris integrasi memiliki beberapa indikator pada UI:

Indikator	Arti
Active	Baris dipakai oleh layanan saat ini. Setel is_active = false untuk mematikan.
Channel	Salah satu dari whatsapp, instagram, messenger, email.
Updated at	Stempel waktu perubahan terakhir. Setelah menyimpan, tunggu sampai 30 detik sebelum menguji.
Config fields	Bidang rahasia (access_token, app_secret, password) otomatis di-mask pada respons API list/get.

Rahasia tidak pernah dikembalikan dalam bentuk utuh melalui API GET /api/integrations atau GET /api/integrations/{channel}. Jika admin perlu memverifikasi nilai, buka baris integrasi dan masukkan kembali — UI akan menampilkan field placeholder yang menandakan nilai sudah ada tetapi tersembunyi.

Langkah umum untuk menambah integrasi baru

1. Siapkan prasyarat eksternal (Meta App, akun Instagram, kredensial SMTP). Detailnya berbeda per saluran — lihat halaman khusus saluran.
2. Di UI, klik + Add Integration dan pilih channel.
3. Masukkan kredensial dan setelan wajib.
4. Klik Save. Sistem menyimpan baris baru ke tabel integrations dengan is_active = true.
5. Tunggu maksimum 30 detik agar webhook-ingestor dan message-sender memuat ulang konfigurasi.
6. Kirim pesan uji (lihat halaman saluran masing-masing) untuk memvalidasi alur masuk dan keluar.

Menonaktifkan sementara

Untuk memadamkan saluran tanpa menghapusnya:

1. Buka halaman Integrations.
2. Cari baris yang ingin dimatikan.
3. Alihkan toggle Active ke off.
4. Simpan perubahan.

Dalam 30 detik, baris akan hilang dari hasil Integration::fetch_active() dan layanan akan berhenti memakai kredensialnya. Webhook masuk dari saluran tersebut tetap akan diterima HTTP (karena port tetap terbuka), tetapi tidak akan dipetakan ke Integration Account sehingga diabaikan atau dicatat sebagai audit tanpa pemrosesan lebih lanjut.

Hubungan dengan API Reference

Semua endpoint REST untuk manajemen integrasi ada di bawah tag Integrations pada API Reference. Endpoint utama:

• GET /api/integrations — daftar seluruh integrasi (config di-mask)
• GET /api/integrations/{channel} — ambil satu integrasi
• PUT /api/integrations/{channel} — upsert integrasi (admin/supervisor)
• DELETE /api/integrations/{channel} — hapus integrasi

Endpoint Integration Accounts (per saluran) juga tersedia untuk manajemen multi-akun.

Catatan