> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waply.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API endpoints for broadcasts — Waply API

> Create, schedule, list, and retrieve broadcast campaigns via the Waply API. Includes audience targeting, the Broadcast object schema, and delivery stats.

Broadcasts let you send a single message to a large audience of contacts at once. You can target contacts by tag, lifecycle stage, or your entire contact list. Broadcasts can be sent immediately or scheduled for a future time. After a broadcast completes, the API returns delivery statistics for each message status.

## The Broadcast object

<ResponseField name="id" type="string">
  Unique identifier for the broadcast, prefixed with `bc_`.
</ResponseField>

<ResponseField name="name" type="string">
  The internal name you gave the broadcast.
</ResponseField>

<ResponseField name="status" type="string">
  Current broadcast status. One of `draft`, `scheduled`, `sending`, `sent`, or `failed`.
</ResponseField>

<ResponseField name="stats" type="object">
  Delivery statistics for the broadcast. Populated after the broadcast starts sending.

  <Expandable title="properties">
    <ResponseField name="sent" type="number">
      Total number of messages sent.
    </ResponseField>

    <ResponseField name="delivered" type="number">
      Number of messages confirmed delivered to recipients' devices.
    </ResponseField>

    <ResponseField name="read" type="number">
      Number of messages read by recipients.
    </ResponseField>

    <ResponseField name="replied" type="number">
      Number of contacts who replied to the broadcast message.
    </ResponseField>

    <ResponseField name="failed" type="number">
      Number of messages that failed to deliver.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the broadcast was created.
</ResponseField>

***

## Create a broadcast

### POST /broadcasts

Creates a broadcast and either sends it immediately or schedules it. Omit `scheduled_at` to send immediately.

<ParamField body="name" type="string" required>
  An internal label for this broadcast (for example, "April re-engagement campaign").
</ParamField>

<ParamField body="channel" type="string" required>
  The channel to send on. One of `whatsapp`, `instagram`, `messenger`, or `webchat`.
</ParamField>

<ParamField body="audience" type="object" required>
  Defines which contacts receive the broadcast. Provide at least one of `tags`, `lifecycle_stage`, or `all`.

  <Expandable title="properties">
    <ParamField body="tags" type="string[]">
      Send to contacts that have any of these tags.
    </ParamField>

    <ParamField body="lifecycle_stage" type="string">
      Send to contacts in this lifecycle stage (for example, `lead` or `customer`).
    </ParamField>

    <ParamField body="all" type="boolean">
      When `true`, send to all contacts in your account. Cannot be combined with `tags` or `lifecycle_stage`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="message" type="object" required>
  The message to send. Provide either `content` (for `text` type) or `template_name` and `template_params` (for `template` type).

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      Message type. Either `text` or `template`.
    </ParamField>

    <ParamField body="content" type="string">
      Text body. Required when `type` is `text`.
    </ParamField>

    <ParamField body="template_name" type="string">
      Name of the approved WhatsApp template. Required when `type` is `template`.
    </ParamField>

    <ParamField body="template_params" type="string[]">
      Ordered array of values for template variable placeholders.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="scheduled_at" type="string">
  ISO 8601 datetime string specifying when to send the broadcast. Omit to send immediately. Must be at least 5 minutes in the future.
</ParamField>

<Tabs>
  <Tab title="Send immediately">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://api.waply.io/v1/broadcasts \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "name": "Spring sale announcement",
          "channel": "whatsapp",
          "audience": {
            "tags": ["newsletter", "customer"]
          },
          "message": {
            "type": "template",
            "template_name": "spring_sale",
            "template_params": ["30%", "April 30"]
          }
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch('https://api.waply.io/v1/broadcasts', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          name: 'Spring sale announcement',
          channel: 'whatsapp',
          audience: {
            tags: ['newsletter', 'customer'],
          },
          message: {
            type: 'template',
            template_name: 'spring_sale',
            template_params: ['30%', 'April 30'],
          },
        }),
      });
      const broadcast = await response.json();
      ```

      ```python Python theme={null}
      import requests, os

      response = requests.post(
          'https://api.waply.io/v1/broadcasts',
          headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
          json={
              'name': 'Spring sale announcement',
              'channel': 'whatsapp',
              'audience': {'tags': ['newsletter', 'customer']},
              'message': {
                  'type': 'template',
                  'template_name': 'spring_sale',
                  'template_params': ['30%', 'April 30'],
              },
          },
      )
      broadcast = response.json()
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Schedule for later">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://api.waply.io/v1/broadcasts \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
          "name": "Re-engagement — churned customers",
          "channel": "whatsapp",
          "audience": {
            "lifecycle_stage": "churned"
          },
          "message": {
            "type": "template",
            "template_name": "winback_offer",
            "template_params": ["20%"]
          },
          "scheduled_at": "2026-04-20T09:00:00Z"
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch('https://api.waply.io/v1/broadcasts', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          name: 'Re-engagement — churned customers',
          channel: 'whatsapp',
          audience: { lifecycle_stage: 'churned' },
          message: {
            type: 'template',
            template_name: 'winback_offer',
            template_params: ['20%'],
          },
          scheduled_at: '2026-04-20T09:00:00Z',
        }),
      });
      const broadcast = await response.json();
      ```

      ```python Python theme={null}
      import requests, os

      response = requests.post(
          'https://api.waply.io/v1/broadcasts',
          headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
          json={
              'name': 'Re-engagement — churned customers',
              'channel': 'whatsapp',
              'audience': {'lifecycle_stage': 'churned'},
              'message': {
                  'type': 'template',
                  'template_name': 'winback_offer',
                  'template_params': ['20%'],
              },
              'scheduled_at': '2026-04-20T09:00:00Z',
          },
      )
      broadcast = response.json()
      ```
    </CodeGroup>
  </Tab>
</Tabs>

**Response**

```json theme={null}
{
  "id": "bc_01HDEF",
  "name": "Spring sale announcement",
  "status": "sending",
  "stats": {
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "replied": 0,
    "failed": 0
  },
  "created_at": "2026-04-16T11:00:00Z"
}
```

For a scheduled broadcast, `status` is `scheduled` and the broadcast starts sending at the `scheduled_at` time.

<Warning>
  WhatsApp requires pre-approved templates for broadcast messages. Sending a broadcast with an unapproved or rejected template will result in a `422` error. Confirm your templates are approved in Settings > Message Templates before creating a broadcast.
</Warning>

***

## List broadcasts

### GET /broadcasts

Returns a paginated list of broadcasts, ordered by creation date descending.

<ParamField query="page" type="number" default="1">
  Page number to retrieve.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of broadcasts per page. Maximum is `100`.
</ParamField>

<ParamField query="status" type="string">
  Filter by broadcast status. One of `draft`, `scheduled`, `sending`, `sent`, or `failed`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.waply.io/v1/broadcasts?status=sent&limit=10' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ status: 'sent', limit: 10 });
  const response = await fetch(`https://api.waply.io/v1/broadcasts?${params}`, {
    headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
  });
  const { data, total, page } = await response.json();
  ```

  ```python Python theme={null}
  import requests, os

  response = requests.get(
      'https://api.waply.io/v1/broadcasts',
      headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
      params={'status': 'sent', 'limit': 10},
  )
  result = response.json()
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "data": [
    {
      "id": "bc_01HDEF",
      "name": "Spring sale announcement",
      "status": "sent",
      "stats": {
        "sent": 1840,
        "delivered": 1792,
        "read": 1201,
        "replied": 87,
        "failed": 48
      },
      "created_at": "2026-04-16T11:00:00Z"
    }
  ],
  "total": 14,
  "page": 1
}
```

***

## Get a broadcast

### GET /broadcasts/{id}

Returns a single broadcast including its full delivery statistics.

<ParamField path="id" type="string" required>
  The ID of the broadcast to retrieve.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.waply.io/v1/broadcasts/bc_01HDEF \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.waply.io/v1/broadcasts/bc_01HDEF', {
    headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
  });
  const broadcast = await response.json();
  ```

  ```python Python theme={null}
  import requests, os

  response = requests.get(
      'https://api.waply.io/v1/broadcasts/bc_01HDEF',
      headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
  )
  broadcast = response.json()
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "id": "bc_01HDEF",
  "name": "Spring sale announcement",
  "status": "sent",
  "stats": {
    "sent": 1840,
    "delivered": 1792,
    "read": 1201,
    "replied": 87,
    "failed": 48
  },
  "created_at": "2026-04-16T11:00:00Z"
}
```

<Tip>
  Subscribe to the `broadcast.completed` [webhook event](/api-reference/webhooks) to receive a notification as soon as a broadcast finishes sending, rather than polling `GET /broadcasts/{id}`.
</Tip>