# WA Insights


## Ringkasan

**WA Insights** (`/wa-insights`) menampilkan metrik performa WhatsApp Business langsung dari **Meta Graph API** — bukan dari database internal OmniStream. Tiga kategori metrik tersedia secara bersamaan:

1. **Message Delivery** — pengiriman pesan harian (sent, delivered, read, failed)
2. **Conversation Billing** — jumlah percakapan yang dikenai tagihan Meta, dikelompokkan per tipe dan arah
3. **Template Performance** — statistik delivery + engagement per template yang terkirim

:::note
**Hak akses:** Halaman ini hanya dapat diakses oleh peran **supervisor** dan **admin** (izin `wa_insights.view`). Agent reguler akan mendapat respons `403 Forbidden`.
:::

:::warning
Data bergantung sepenuhnya pada ketersediaan Meta Graph API. Jika akun WhatsApp Business belum terhubung di **Integrations**, halaman ini akan menampilkan pesan *"No WhatsApp Account Connected"* dan tidak akan ada data yang dimuat.
:::

## Sumber data

Ketiga endpoint backend (`GET /api/wa-insights/messages`, `/conversations`, `/templates`) **tidak membaca PostgreSQL atau MongoDB** — setiap request langsung meneruskan panggilan ke Meta Graph API menggunakan WABA ID dan access token dari tabel `integration_accounts`. Jika tidak ada akun spesifik yang dipilih, sistem jatuh kembali ke variabel lingkungan `META_WABA_ID` dan `META_ACCESS_TOKEN`.

## Filter yang tersedia

| Filter | Nilai | Keterangan |
|---|---|---|
| **Date Range** | `7d`, `30d`, `90d` | Preset otomatis dihitung mundur dari hari ini |
| **Custom Range** | tanggal `start` + `end` | Format `YYYY-MM-DD`; klik **Apply** setelah memilih |
| **Account** | dropdown akun aktif | Hanya muncul jika ada lebih dari satu akun WhatsApp aktif; akun default dipilih otomatis |

Tanggal dikirim ke Meta API sebagai **Unix timestamp UTC** (konversi dilakukan di backend).

## Metrik yang tersedia

### A. Message Delivery

Data harian dari `analytics` Meta Graph API dengan granularitas `DAY` dan metrik `SENT, DELIVERED, READ, FAILED`.

| Metrik | Deskripsi |
|---|---|
| **Total Sent** | Total pesan terkirim dalam periode |
| **Delivery Rate** | `delivered / sent × 100%` — dihitung di frontend dari agregat harian |
| **Read Rate** | `read / delivered × 100%` |
| **Failed** | Pesan yang gagal terkirim |

Bar chart harian menumpuk tiga layer: **Sent** (biru muda), **Delivered** (hijau), **Read** (ungu) — proporsi dihitung relatif terhadap nilai `sent` tertinggi dalam periode.

### B. Conversation Billing

Data dari `conversation_analytics` Meta Graph API, granularitas `DAILY`, dimensi `CONVERSATION_TYPE` dan `CONVERSATION_DIRECTION`.

| Metrik | Deskripsi |
|---|---|
| **Total Conversations** | Semua percakapan dalam periode |
| **User-Initiated** | Percakapan yang dimulai oleh pelanggan (`direction` mengandung `user`) |
| **Business-Initiated** | Selisih total dikurangi user-initiated |

Breakdown per **tipe percakapan** ditampilkan sebagai badge berwarna:

| Tipe | Warna | Keterangan |
|---|---|---|
| `MARKETING` | Oranye | Kampanye promosi |
| `UTILITY` | Biru | Notifikasi transaksional |
| `SERVICE` | Hijau | Balasan dalam jendela layanan 24 jam |
| `AUTHENTICATION` | Ungu | OTP / verifikasi |
| `FREE_TIER` | Abu | Di bawah batas gratis bulanan |
| `FREE_ENTRY_POINT` | Abu muda | Masuk dari iklan Click-to-WhatsApp |

:::tip
Tipe `FREE_TIER` dan `FREE_ENTRY_POINT` tidak dikenai biaya Meta. Pantau proporsi tipe `MARKETING` karena kategori ini memiliki tarif tertinggi.
:::

### C. Template Performance

Data dari endpoint `/{waba_id}/template_analytics` Meta Graph API, granularitas `DAILY`, metrik `SENT, DELIVERED, READ, CLICKED`.

| Kolom | Deskripsi |
|---|---|
| **Template** | Nama template |
| **Sent** | Total terkirim dalam periode |
| **Delivered** | Berhasil diterima perangkat tujuan |
| **Read** | Dibuka oleh penerima |
| **Clicked** | Tombol CTA diklik |
| **Click Rate** | `clicked / sent × 100%` |

Klik judul kolom (**Sent**, **Delivered**, **Read**, **Clicked**) untuk mengurutkan secara descending atau ascending.

## Cara membaca data

- **Delivery Rate rendah** (< 85%) biasanya menandakan banyak nomor tidak aktif atau pesan terblokir di sisi penerima. Periksa log `FAILED` harian di chart untuk melihat lonjakan.
- **Read Rate tinggi tapi Click Rate rendah** pada template: konten CTA perlu direvisi, atau tombol tidak relevan dengan konteks percakapan.
- **Lonjakan `MARKETING`** di Conversation Billing tanpa campaign yang berjalan: kemungkinan ada pengiriman template marketing yang tidak tercatat di OmniStream — periksa halaman [Kampanye Broadcast](/panduan/admin/kampanye-broadcast).
- **Data kosong / semua nol**: pastikan WABA ID dan access token di akun integrasi masih valid. Token Meta bisa kedaluwarsa; perbarui di halaman **Channels → WhatsApp**.

## Endpoint backend

| Tujuan | Endpoint | Sumber data |
|---|---|---|
| Pengiriman pesan harian | `GET /api/wa-insights/messages` | Meta Graph API — `analytics` |
| Billing percakapan | `GET /api/wa-insights/conversations` | Meta Graph API — `conversation_analytics` |
| Performa template | `GET /api/wa-insights/templates` | Meta Graph API — `template_analytics` |

Parameter kueri untuk ketiga endpoint:

| Parameter | Tipe | Wajib | Keterangan |
|---|---|---|---|
| `start` | `string` | Ya | Tanggal awal format `YYYY-MM-DD` |
| `end` | `string` | Ya | Tanggal akhir format `YYYY-MM-DD` |
| `integration_account_id` | `uuid` | Tidak | Jika tidak dikirim, backend pakai konfigurasi global |

Contoh pemanggilan langsung:

```bash
curl -H "Authorization: Bearer $JWT" \
  "http://localhost:3000/api/wa-insights/messages?start=2026-05-01&end=2026-05-31"
```

```bash
curl -H "Authorization: Bearer $JWT" \
  "http://localhost:3000/api/wa-insights/templates?start=2026-05-01&end=2026-05-31&integration_account_id=<uuid>"
```

Skema respons lengkap tersedia di [API Reference](/api).

## Rute terkait

- [Analytics & Laporan](/panduan/supervisor/analytics) — metrik operasional internal (percakapan, agent, CSAT)
- [Kampanye Broadcast](/panduan/admin/kampanye-broadcast) — pengiriman template WhatsApp massal
- [Kebijakan SLA](/panduan/admin/kebijakan-sla) — aturan waktu respons per kanal