Broadcast

Send Broadcast

Send a template message to multiple phone numbers in a single API call. Messages are queued and delivered asynchronously.

POST /api/v1/public/broadcast/send

Parameters

Parameter	Type	Required	Description
`template_name`	`string`	yes	Approved WhatsApp template name
`language`	`string`	yes	Template language code (e.g., "id", "en_US")
`phone_numbers`	`string[]`	yes	Array of recipient phone numbers in E.164 format
`whatsapp_phone_number_id`	`string`	no	WhatsApp phone number ID to send from. If omitted, uses primary number.
`components`	`object`	no	Template body variable values as a flat object: variable number → value, e.g. `{ "1": "John", "2": "INV-1" }`. One key per `{{n}}` placeholder in the template body.

warning

Important: The template must be approved by Meta before use. All recipients receive the same template with the same variable values. Note: components here is a flat object (e.g. { "1": "50%" }) — this differs from the array format used by Send Message.

Example Request

cURL
JavaScript
Python

curl -X POST "https://chat.api.co.id/api/v1/public/broadcast/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "promo_sale",
    "language": "id",
    "phone_numbers": ["+628123456789", "+628987654321"],
    "whatsapp_phone_number_id": "clyyy9876543210",
    "components": { "1": "50%" }
  }'

const response = await fetch("https://chat.api.co.id/api/v1/public/broadcast/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    template_name: "promo_sale",
    language: "id",
    phone_numbers: ["+628123456789", "+628987654321"],
    whatsapp_phone_number_id: "clyyy9876543210",
    components: { "1": "50%" }
  })
});

const { data } = await response.json();
console.log("Broadcast job ID:", data.job_id);

import requests

response = requests.post(
    "https://chat.api.co.id/api/v1/public/broadcast/send",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "template_name": "promo_sale",
        "language": "id",
        "phone_numbers": ["+628123456789", "+628987654321"],
        "whatsapp_phone_number_id": "clyyy9876543210",
        "components": { "1": "50%" }
    }
)

data = response.json()["data"]
print("Broadcast job ID:", data["job_id"])

Response

{
  "success": true,
  "data": {
    "job_id": "bcast_abc123",
    "template_name": "promo_sale",
    "total_recipients": 2,
    "status": "PENDING",
    "created_at": "2026-04-03T10:00:00.000Z"
  }
}

info

Use GET /api/v1/public/broadcast/jobs/:jobId to check the delivery status of your broadcast.

Broadcast Jobs

List, view, and cancel broadcast jobs. Track the delivery status and progress of your broadcasts.

GET /api/v1/public/broadcast/jobs

GET /api/v1/public/broadcast/jobs/:id

POST /api/v1/public/broadcast/jobs/:id/cancel

Query Parameters (List)

Parameter	Type	Required	Description
`limit`	`number`	no	Number of jobs to return (default 20)
`offset`	`number`	no	Number of jobs to skip for pagination (default 0)
`status`	`string`	no	Filter by status: "queued", "processing", "completed", "failed", "cancelled"

List Broadcast Jobs

cURL
JavaScript
Python

curl -X GET "https://chat.api.co.id/api/v1/public/broadcast/jobs?limit=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://chat.api.co.id/api/v1/public/broadcast/jobs?limit=20&status=completed",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

const { data, pagination } = await response.json();
console.log("Jobs:", data);

import requests

response = requests.get(
    "https://chat.api.co.id/api/v1/public/broadcast/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 20, "status": "completed"}
)

result = response.json()
jobs = result["data"]
print("Jobs:", jobs)

List Jobs Response

{
  "success": true,
  "data": [
    {
      "id": "bcast_abc123",
      "template_name": "promo_sale",
      "total_recipients": 150,
      "sent_count": 150,
      "failed_count": 3,
      "status": "completed",
      "created_at": "2026-04-01T08:00:00.000Z",
      "completed_at": "2026-04-01T08:05:30.000Z"
    },
    {
      "id": "bcast_def456",
      "template_name": "welcome_message",
      "total_recipients": 50,
      "sent_count": 25,
      "failed_count": 0,
      "status": "processing",
      "created_at": "2026-04-03T10:00:00.000Z",
      "completed_at": null
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Get Job Detail

cURL
JavaScript
Python

curl -X GET "https://chat.api.co.id/api/v1/public/broadcast/jobs/bcast_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://chat.api.co.id/api/v1/public/broadcast/jobs/bcast_abc123",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

const { data } = await response.json();
console.log("Job status:", data.status);

import requests

response = requests.get(
    "https://chat.api.co.id/api/v1/public/broadcast/jobs/bcast_abc123",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

data = response.json()["data"]
print("Job status:", data["status"])

Job Detail Response

{
  "success": true,
  "data": {
    "id": "bcast_abc123",
    "template_name": "promo_sale",
    "language": "id",
    "total_recipients": 150,
    "sent_count": 150,
    "failed_count": 3,
    "status": "completed",
    "whatsapp_phone_number_id": "clyyy9876543210",
    "created_at": "2026-04-01T08:00:00.000Z",
    "completed_at": "2026-04-01T08:05:30.000Z"
  }
}

Cancel Broadcast Job

cURL
JavaScript
Python

curl -X POST "https://chat.api.co.id/api/v1/public/broadcast/jobs/bcast_def456/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://chat.api.co.id/api/v1/public/broadcast/jobs/bcast_def456/cancel",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
);

const { data } = await response.json();
console.log("Cancelled:", data.status);

import requests

response = requests.post(
    "https://chat.api.co.id/api/v1/public/broadcast/jobs/bcast_def456/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

data = response.json()["data"]
print("Cancelled:", data["status"])

Cancel Response

{
  "success": true,
  "data": {
    "id": "bcast_def456",
    "status": "cancelled",
    "total_recipients": 50,
    "sent_count": 25,
    "failed_count": 0,
    "cancelled_at": "2026-04-03T10:05:00.000Z"
  }
}

warning

Note: Only jobs with status queued or processing can be cancelled. Messages already sent cannot be recalled.

Try it out

tip

Press Try it and paste your API key (kc_live_...) into the API key (Bearer) field. Get the key from API Keys. Requests run against your live account, so endpoints that send, create, or delete act on real data.

POST/api/v1/public/broadcast/sendSend Broadcast
GET/api/v1/public/broadcast/jobsList Broadcast Jobs
GET/api/v1/public/broadcast/jobs/{id}Get Job Detail
POST/api/v1/public/broadcast/jobs/{id}/cancelCancel Broadcast Job

Was this page helpful?

Send Broadcast​

Parameters​

Example Request​

Response​

Broadcast Jobs​

Query Parameters (List)​

List Broadcast Jobs​

List Jobs Response​

Get Job Detail​

Job Detail Response​

Cancel Broadcast Job​

Cancel Response​

Try it out​