# Ikhtisar Integrasi


Halaman **Integrations** adalah pusat kendali tempat admin menghubungkan OmniStream ke saluran pesan eksternal: WhatsApp Cloud API, Instagram Login, dan SMTP email.

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

- [Integrasi WhatsApp](./whatsapp) — Meta WhatsApp Cloud API
- [Integrasi Instagram](./instagram) — Instagram Login OAuth per akun
- [Integrasi Facebook Messenger](./messenger) — Messenger via halaman Facebook
- [Integrasi Email](./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.

![Halaman Integrations](/screenshots/integrations.png)

## 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

Setiap integrasi dapat dikonfigurasi melalui:

1. **UI Integrations** — cara yang disarankan untuk admin. Perubahan aktif dalam 30 detik tanpa perlu restart layanan.
2. **Konfigurasi server** — beberapa nilai seperti **Meta App Secret** dan **Meta Verify Token** perlu dikonfigurasi di level server oleh administrator, karena Meta hanya mengizinkan satu verify token global per aplikasi.

### Hot-reload 30 detik

Setelah admin menyunting konfigurasi di UI dan menyimpannya, **tidak perlu me-restart** layanan apapun. Setiap perubahan di UI akan aktif paling lambat 30 detik kemudian.

> Menonaktifkan integrasi (toggle **Active** ke off) akan menghentikan layanan memakainya pada siklus 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**.
5. Tunggu maksimum 30 detik agar konfigurasi aktif.
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, layanan akan berhenti memakai kredensial saluran tersebut. Webhook masuk masih akan diterima tetapi tidak akan diproses.

## Hubungan dengan API Reference

Semua endpoint REST untuk manajemen integrasi ada di bawah tag **Integrations** pada [API Reference](/api). 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

:::warning
**WhatsApp Embedded Signup**

Alur pendaftaran in-app via Facebook Login (commit `6f5f4dd`) ditangguhkan dari dokumentasi v1. Lihat [Integrasi WhatsApp](./whatsapp) untuk opsi manual yang didukung di v1.
:::