Skip to main content
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

​
id
string
Unique identifier for the broadcast, prefixed with bc_.
​
name
string
The internal name you gave the broadcast.
​
status
string
Current broadcast status. One of draft, scheduled, sending, sent, or failed.
​
stats
object
Delivery statistics for the broadcast. Populated after the broadcast starts sending.
​
created_at
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.
​
name
string
required
An internal label for this broadcast (for example, “April re-engagement campaign”).
​
channel
string
required
The channel to send on. One of whatsapp, instagram, messenger, or webchat.
​
audience
object
required
Defines which contacts receive the broadcast. Provide at least one of tags, lifecycle_stage, or all.
​
message
object
required
The message to send. Provide either content (for text type) or template_name and template_params (for template type).
​
scheduled_at
string
ISO 8601 datetime string specifying when to send the broadcast. Omit to send immediately. Must be at least 5 minutes in the future.
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"]
    }
  }'
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.
​
page
number
default:"1"
Page number to retrieve.
​
limit
number
default:"20"
Number of broadcasts per page. Maximum is 100.
​
status
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'
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.
​
id
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'
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}.