# `KapsoEx.Platform.Broadcasts`
[🔗](https://github.com/rocket4ce/kapso_ex/blob/v0.1.0/lib/kapso_ex/platform/broadcasts.ex#L1)

Send an approved template to many recipients, with per-recipient
tracking. See the [Broadcasts API guide](https://docs.kapso.ai/docs/platform/broadcasts/api).

Typical flow:

    {:ok, %{"data" => %{"id" => id}}} =
      Broadcasts.create(client, name: "Black Friday", phone_number_id: pnid, whatsapp_template_id: tid)

    {:ok, _} =
      Broadcasts.add_recipients(client, id, [
        %{phone_number: "+56961567267", components: [%{type: "body", parameters: [%{type: "text", text: "Ana"}]}]}
      ])

    {:ok, _} = Broadcasts.send(client, id)

Kapso paces sends to stay within Meta's throughput limits.

# `result`

```elixir
@type result() :: {:ok, map()} | {:error, KapsoEx.Error.t()}
```

# `add_recipients`

```elixir
@spec add_recipients(KapsoEx.Client.t(), String.t(), [map()]) :: result()
```

Adds up to 1000 recipients to a draft broadcast. Duplicates are skipped.

Each recipient is a map with `phone_number` (E.164) or
`whatsapp_contact_id` and, when the template has parameters,
`components` (see `KapsoEx.WhatsApp.TemplateComponents`).

# `cancel`

```elixir
@spec cancel(KapsoEx.Client.t(), String.t()) :: result()
```

Cancels a scheduled broadcast and returns it to draft.

# `clear_recipients`

```elixir
@spec clear_recipients(KapsoEx.Client.t(), String.t()) :: result()
```

Removes every recipient from a draft or scheduled broadcast.

# `create`

```elixir
@spec create(KapsoEx.Client.t(), map() | keyword()) :: result()
```

Creates a draft broadcast. Attributes: `name`, `phone_number_id` and
`whatsapp_template_id` (all required).

# `get`

```elixir
@spec get(KapsoEx.Client.t(), String.t()) :: result()
```

Gets a broadcast with its delivery counters. Poll it to follow progress.

# `list`

```elixir
@spec list(KapsoEx.Client.t(), map() | keyword()) :: result()
```

Lists broadcasts, most recent first.

Params: `phone_number_id`, `status`, `created_after`, `created_before`,
`page`, `per_page`.

# `list_recipients`

```elixir
@spec list_recipients(KapsoEx.Client.t(), String.t(), map() | keyword()) :: result()
```

Lists recipients with their delivery status. Params: `page`, `per_page`.

# `schedule`

```elixir
@spec schedule(KapsoEx.Client.t(), String.t(), DateTime.t() | String.t()) :: result()
```

Schedules a draft broadcast with recipients. `scheduled_at` is a
`DateTime` or an ISO 8601 string.

# `send`

```elixir
@spec send(KapsoEx.Client.t(), String.t()) :: result()
```

Starts sending now. Sending is asynchronous; poll `get/2` for progress.

# `update_status`

```elixir
@spec update_status(KapsoEx.Client.t(), String.t(), String.t()) :: result()
```

Changes the status of a broadcast: `"stopped"` or back to `"draft"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*