# Broadcasts


## Broadcast vs Kampanye

OmniStream memiliki dua fitur pengiriman massal yang berbeda tujuan:

| | **Broadcast** | **Kampanye** |
|---|---|---|
| Pesan | Teks bebas (`message_content`) | Template WhatsApp yang sudah disetujui Meta |
| Kanal | WhatsApp, Instagram, **Email** | WhatsApp saja |
| Penerima | Kontak di kanal yang dipilih, difilter opsional by tag | Kontak ditambah manual, by ID, atau by tag — dengan variabel per penerima |
| Kasus penggunaan | Pengumuman cepat, notifikasi internal, update multi-kanal | Kampanye pemasaran berulang dengan personalisasi variabel per penerima |

Lihat [Kampanye Broadcast](/panduan/admin/kampanye-broadcast) untuk detail fitur kampanye.

:::note
Hak akses: fitur Broadcasts memerlukan permission **`campaigns.manage`** — berlaku untuk role **admin** dan **supervisor**.
:::

---

## Cara membuat broadcast

1. Buka menu **Broadcasts**.
2. Klik tombol **New Broadcast**.
3. Isi formulir:
   - **Name** — label internal untuk broadcast ini (wajib).
   - **Message Content** — teks pesan yang akan dikirim ke semua penerima (wajib).
   - **Channel** — pilih `WhatsApp`, `Instagram`, atau `Email`.
   - **Filter by Tags** — opsional; satu atau lebih tag dipisah koma (contoh: `vip, premium`).
   - **Schedule** — opsional; isi datetime untuk penjadwalan otomatis.
4. Klik **Create**.

Broadcast baru dibuat dengan status **draft**. Jumlah penerima dihitung otomatis saat ini berdasarkan kanal dan filter tag yang dipilih.

---

## Memilih penerima (audience)

Penerima ditentukan secara **dinamis** saat broadcast dibuat atau diperbarui — bukan daftar kontak statis.

Sistem menghitung semua kontak di tabel `contacts` yang:
- `channel_source` sesuai kanal yang dipilih, **dan**
- memiliki setidaknya satu tag yang cocok (jika filter tag diisi).

```json
// Contoh audience_filter — hanya kontak berkanal whatsapp dengan tag "vip" atau "premium"
{ "tags": ["vip", "premium"] }
```

Jika field **Filter by Tags** dikosongkan, broadcast dikirim ke **semua kontak** di kanal tersebut.

:::warning
Jumlah penerima (`total_recipients`) dihitung pada saat broadcast dibuat atau diedit — bukan pada saat pengiriman. Jika kontak baru ditambahkan setelah broadcast dibuat, mereka tidak otomatis masuk kecuali broadcast diedit ulang.
:::

---

## Pesan

Broadcast menggunakan **teks bebas** yang diisi di field **Message Content**. Tidak ada variabel per-penerima dan tidak memerlukan approval Meta. Pesan yang sama dikirim identik ke semua penerima.

:::tip
Untuk WhatsApp, gunakan Broadcast hanya saat Anda sudah memiliki sesi aktif (24-jam window) dengan kontak. Di luar window tersebut, pesan teks bebas akan ditolak oleh Meta API — gunakan fitur [Kampanye](/panduan/admin/kampanye-broadcast) dengan template approved untuk menjangkau kontak lama.
:::

---

## Penjadwalan

Broadcast dapat dikirim segera atau dijadwalkan untuk masa depan:

- **Kirim langsung** — klik **Send Now** dari daftar (status berpindah ke `sending` seketika).
- **Jadwalkan** — isi field **Schedule** saat membuat/mengedit, atau gunakan endpoint `POST /api/broadcasts/{id}/schedule`. Status berubah ke `scheduled`, dan background scheduler memproses pengiriman saat waktu tiba.
- **Batalkan jadwal** — gunakan endpoint `POST /api/broadcasts/{id}/cancel-schedule`; broadcast kembali ke status `draft`.

```json
// Body untuk endpoint schedule
{ "scheduled_at": "2026-07-01T09:00:00Z" }
```

`scheduled_at` harus selalu di masa depan — server memvalidasi ini saat schedule di-set.

---

## Status broadcast

| Status | Keterangan |
|---|---|
| **draft** | Baru dibuat atau dibatalkan jadwalnya; bisa diedit, dikirim, dijadwalkan, atau dihapus |
| **scheduled** | Dijadwalkan; akan diproses otomatis oleh background scheduler |
| **sending** | Pengiriman sedang berjalan di background |
| **completed** | Semua pesan berhasil diproses |
| **failed** | Pengiriman gagal |

:::note
Hanya broadcast berstatus **draft** yang bisa diedit, dikirim, dijadwalkan, atau dihapus. Broadcast yang sudah `sending` atau `completed` tidak dapat diubah.
:::

---

## Memantau hasil

Di halaman **Broadcasts**, setiap card menampilkan:

- **Total recipients** — jumlah kontak yang ditarget.
- **Sent** — pesan yang berhasil terkirim (`sent_count`).
- **Failed** — pesan yang gagal (`failed_count`), ditampilkan hanya jika > 0.

Filter tab atas (**All / Draft / Sending / Completed**) membantu mempersempit tampilan.

---

## Endpoint API

| Aksi | Endpoint |
|---|---|
| List broadcasts | `GET /api/broadcasts` |
| Detail | `GET /api/broadcasts/{id}` |
| Buat | `POST /api/broadcasts` |
| Perbarui draft | `PATCH /api/broadcasts/{id}` |
| Kirim sekarang | `POST /api/broadcasts/{id}/send` |
| Jadwalkan | `POST /api/broadcasts/{id}/schedule` |
| Batalkan jadwal | `POST /api/broadcasts/{id}/cancel-schedule` |
| Hapus draft | `DELETE /api/broadcasts/{id}` |

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

---

## Rute terkait

- [Kampanye Broadcast](/panduan/admin/kampanye-broadcast) — pengiriman massal dengan template WhatsApp dan variabel per penerima
- [API Reference](/api) — skema request/response lengkap