REST API endpoints for broadcasts

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

string

Unique identifier for the broadcast, prefixed with bc_.

string

The internal name you gave the broadcast.

string

Current broadcast status. One of draft, scheduled, sending, sent, or failed.

object

Delivery statistics for the broadcast. Populated after the broadcast starts sending.

Show properties

number

Total number of messages sent.

number

Number of messages confirmed delivered to recipients’ devices.

number

Number of messages read by recipients.

number

Number of contacts who replied to the broadcast message.

number

Number of messages that failed to deliver.

string

ISO 8601 timestamp of when the broadcast was created.

Create a broadcast

POST /broadcasts

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

string

required

An internal label for this broadcast (for example, “April re-engagement campaign”).

string

required

The channel to send on. One of whatsapp, instagram, messenger, or webchat.

object

required

Defines which contacts receive the broadcast. Provide at least one of tags, lifecycle_stage, or all.

Show properties

string[]

Send to contacts that have any of these tags.

string

Send to contacts in this lifecycle stage (for example, lead or customer).

boolean

When true, send to all contacts in your account. Cannot be combined with tags or lifecycle_stage.

object

required

The message to send. Provide either content (for text type) or template_name and template_params (for template type).

Show properties

string

required

Message type. Either text or template.

string

Text body. Required when type is text.

string

Name of the approved WhatsApp template. Required when type is template.

string[]

Ordered array of values for template variable placeholders.

string

ISO 8601 datetime string specifying when to send the broadcast. Omit to send immediately. Must be at least 5 minutes in the future.

Send immediately
Schedule for later

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"]
    }
  }'

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();

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()

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"
  }'

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();

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()

Response

{
  "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.

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.

List broadcasts

GET /broadcasts

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

number

default:"1"

Page number to retrieve.

number

default:"20"

Number of broadcasts per page. Maximum is 100.

string

Filter by broadcast status. One of draft, scheduled, sending, sent, or failed.

curl --request GET \
  --url 'https://api.waply.io/v1/broadcasts?status=sent&limit=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'

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();

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()

Response

{
  "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/

Returns a single broadcast including its full delivery statistics.

string

required

The ID of the broadcast to retrieve.

curl --request GET \
  --url https://api.waply.io/v1/broadcasts/bc_01HDEF \
  --header 'Authorization: Bearer YOUR_API_KEY'

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();

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()

Response

{
  "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"
}

Subscribe to the broadcast.completed webhook event to receive a notification as soon as a broadcast finishes sending, rather than polling GET /broadcasts/{id}.

API

Endpoints

REST API endpoints for broadcasts — Waply API

The Broadcast object

Create a broadcast

POST /broadcasts

List broadcasts

GET /broadcasts

Get a broadcast

GET /broadcasts/

​The Broadcast object

​Create a broadcast

​POST /broadcasts

​List broadcasts

​GET /broadcasts

​Get a broadcast

​GET /broadcasts/

The Broadcast object

Create a broadcast

POST /broadcasts

List broadcasts

GET /broadcasts

Get a broadcast

GET /broadcasts/