# Campaign WhatsApp


## Ringkasan

Modul **Campaigns** (`/campaigns`) memungkinkan supervisor merancang dan mengirim pesan broadcast WhatsApp berbasis **template resmi** yang sudah disetujui Meta. Berbeda dengan pesan percakapan biasa yang bebas bentuk, broadcast WhatsApp di luar jendela 24 jam layanan hanya boleh menggunakan template terdaftar — karena itu halaman ini terbagi jadi dua tab: **Templates** (sinkron dari Meta) dan **Campaigns** (perencanaan eksekusi).

Pengiriman dijalankan oleh scheduler backend yang memeriksa setiap 30 detik untuk kampanye yang waktunya sudah tiba, lalu mengirimkan pesan satu per satu ke Meta Graph API.

:::info
**Hak akses:** Kampanye hanya dapat dikelola oleh **supervisor** dan **admin**. Untuk mengirim kampanye, peran harus memiliki flag `can_broadcast = true` pada record agent-nya.
:::

## Alur kerja kampanye

```
Template disetujui Meta
        ↓
Sinkronisasi ke OmniStream (tab Templates)
        ↓
Supervisor buat campaign (pilih template + nama)
        ↓
Tambah penerima (manual / dari kontak / dari tag / CSV)
        ↓
Review (opsional jadwalkan ke waktu tertentu)
        ↓
Send Now / Schedule
        ↓
Sistem mengeksekusi → pesan dikirim ke Meta
        ↓
Status per-recipient dicatat dan dapat dipantau
```

## Langkah-langkah: mengirim kampanye baru

### 1. Siapkan template

1. Buka `/campaigns`, klik tab **Templates**.
2. Klik tombol **Sync from Meta** untuk menarik semua template WhatsApp Business yang sudah disetujui Meta ke database OmniStream. Endpoint yang dipanggil: `POST /api/wa-templates/sync` (tag **WA Templates**).
3. Pastikan template yang ingin dipakai berstatus **APPROVED** dan memiliki `category` (UTILITY, MARKETING, AUTHENTICATION).

:::warning
Jangan gunakan template yang masih **PENDING** atau **REJECTED** — Meta akan mengembalikan error saat pengiriman dan seluruh kampanye bisa gagal.
:::

### 2. Buat campaign

1. Di tab **Campaigns**, klik **+ New Campaign**.
2. Isi form:
   - **Name** (wajib) — nama internal, mis. `Promo Lebaran 2026 - WhatsApp VIP`
   - **Template** — pilih template dari daftar hasil sync
3. (Opsional) Aktifkan **Schedule** dan pilih tanggal + jam pengiriman. Tanpa jadwal, kampanye tetap berstatus `draft` hingga Anda klik **Send Now**.
4. Klik **Create**. Campaign tercipta dengan status `draft`.

### 3. Tambah penerima

Ada 4 cara menambah penerima:

| Mode | Cara kerja |
|---|---|
| **Contacts** | Pilih kontak yang sudah ada di database |
| **Tags** | Semua kontak yang memiliki tag tertentu (mis. `vip`, `newsletter`) |
| **Manual** | Input nomor telepon secara manual, satu per baris |
| **CSV** | Upload file CSV dengan kolom `phone` + variabel template |

Jika template mengandung variabel (`{{1}}`, `{{2}}`), Anda wajib memetakan nilai per kontak pada langkah ini.

### 4. Review dan kirim

1. Klik tab **Review** di modal campaign.
2. Periksa:
   - Jumlah total penerima
   - Preview WhatsApp lengkap dengan format (bold `*text*`, italic `_text_`, strikethrough `~text~`)
   - Ringkasan jadwal (jika ada)
3. Klik **Send Now** untuk pengiriman langsung, atau biarkan scheduler yang menanganinya pada waktu yang dijadwalkan.

![Screenshot halaman campaigns](/screenshots/campaigns.png)

## Memantau campaign yang sedang berjalan

1. Di tab **Campaigns**, klik baris campaign untuk melihat detail.
2. Panel detail menampilkan:
   - **Status** keseluruhan: `draft`, `scheduled`, `sending`, `completed`, `failed`, `cancelled`
   - **Progress**: `X of Y sent` (live update)
   - **Recipients breakdown**: queued / sent / delivered / read / failed
3. Untuk menghentikan kampanye yang sedang berjalan, klik **Cancel Campaign**. Hanya penerima yang belum diproses yang akan di-skip; yang sudah terkirim tidak bisa ditarik.

## Endpoint (tag **Campaigns**)

| Aksi | Endpoint |
|---|---|
| List campaign | `GET /api/campaigns` |
| Detail campaign | `GET /api/campaigns/{id}` |
| Buat campaign | `POST /api/campaigns` |
| Update campaign | `PUT /api/campaigns/{id}` |
| Cancel campaign | `POST /api/campaigns/{id}/cancel` |
| Kirim sekarang | `POST /api/campaigns/{id}/send` |
| Tambah penerima | `POST /api/campaigns/{id}/recipients` |
| List penerima | `GET /api/campaigns/{id}/recipients` |

Endpoint lengkap di [API Reference — Campaigns](/api) dan [API Reference — WA Templates](/api).

## Praktik terbaik

- **Test dengan 1 penerima dulu** — kirim ke nomor internal sebelum blast ke ribuan kontak.
- **Gunakan kategori template yang tepat** — jangan pakai MARKETING untuk pesan layanan; Meta akan menurunkan kualitas pengiriman.
- **Patuhi jam operasional** — broadcast di luar jam biasanya berdampak negatif pada response rate dan meningkatkan opt-out.
- **Monitor failed recipients** — nomor yang gagal berulang kali sebaiknya dihapus dari daftar kontak untuk melindungi sender score.
- **Cek metric di [Analytics](/panduan/supervisor/analytics)** — lonjakan pesan harian biasanya mencerminkan kampanye baru.

## Rute terkait

- [Dashboard Supervisor](/panduan/supervisor/dashboard) — pantau volume pesan saat kampanye aktif
- [Analytics](/panduan/supervisor/analytics) — lihat tren pesan per hari