import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
phone: '919876543210', // the phone to act with (x-phone)
});
async function main() {
const response = await client.queue.getBroadcastStatus({
broadcast_id: '00000000-0000-0000-0000-000000000000',
});
console.log(response);
}
main();curl -X GET 'https://api.periskope.app/v1/queue/broadcast?broadcast_id=00000000-0000-0000-0000-000000000000' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210'{
"broadcast_id": "00000000-0000-0000-0000-000000000000",
"org_id": "00000000-0000-0000-0000-000000000000",
"message_payload": {
"body": "Hello from Periskope!",
"message_type": "chat"
},
"created_at": "2026-01-15T09:30:00.000Z",
"broadcast_status": "completed",
"total_chats": 25,
"sent_chats": 22,
"failed_chats": 1,
"pending_chats": 2,
"total_delivered_count": 180,
"total_read_count": 120,
"total_member_count": 200,
"delivered_percentage": 90,
"read_percentage": 60,
"performed_by": "api",
"performed_at": "2026-01-15T09:31:00.000Z",
"scheduled_at": null,
"due_at": "2026-01-15T09:31:00.000Z",
"retry_count": 0,
"previous_retries": null,
"parent_broadcast_id": null,
"repeat_config": null,
"is_active": null,
"next_occurrence_at": null,
"occurrence_count": null,
"logs": [
{
"broadcast_id": "00000000-0000-0000-0000-000000000000",
"org_id": "00000000-0000-0000-0000-000000000000",
"chat_id": "120363000000000000@g.us",
"org_phone": "911111111111@c.us",
"message_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"is_success": true,
"remarks": null,
"member_count": 12,
"delivered_count": 10,
"read_count": 7,
"delivery_info": null,
"poll_results": null,
"created_at": "2026-01-15T09:30:00.000Z",
"completed_at": "2026-01-15T09:31:00.000Z"
}
]
}{
"code": "ERROR",
"message": "Broadcast not found — no broadcast with the given broadcast_id exists in the workspace",
"status": 400
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Get Broadcast Status
Returns the aggregate delivery status of a broadcast: sent, failed and pending counts, delivered/read percentages, and scheduling info.
import { PeriskopeApi } from '@periskope/periskope-client';
const client = new PeriskopeApi({
authToken: 'YOUR_API_KEY',
phone: '919876543210', // the phone to act with (x-phone)
});
async function main() {
const response = await client.queue.getBroadcastStatus({
broadcast_id: '00000000-0000-0000-0000-000000000000',
});
console.log(response);
}
main();curl -X GET 'https://api.periskope.app/v1/queue/broadcast?broadcast_id=00000000-0000-0000-0000-000000000000' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210'{
"broadcast_id": "00000000-0000-0000-0000-000000000000",
"org_id": "00000000-0000-0000-0000-000000000000",
"message_payload": {
"body": "Hello from Periskope!",
"message_type": "chat"
},
"created_at": "2026-01-15T09:30:00.000Z",
"broadcast_status": "completed",
"total_chats": 25,
"sent_chats": 22,
"failed_chats": 1,
"pending_chats": 2,
"total_delivered_count": 180,
"total_read_count": 120,
"total_member_count": 200,
"delivered_percentage": 90,
"read_percentage": 60,
"performed_by": "api",
"performed_at": "2026-01-15T09:31:00.000Z",
"scheduled_at": null,
"due_at": "2026-01-15T09:31:00.000Z",
"retry_count": 0,
"previous_retries": null,
"parent_broadcast_id": null,
"repeat_config": null,
"is_active": null,
"next_occurrence_at": null,
"occurrence_count": null,
"logs": [
{
"broadcast_id": "00000000-0000-0000-0000-000000000000",
"org_id": "00000000-0000-0000-0000-000000000000",
"chat_id": "120363000000000000@g.us",
"org_phone": "911111111111@c.us",
"message_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
"is_success": true,
"remarks": null,
"member_count": 12,
"delivered_count": 10,
"read_count": 7,
"delivery_info": null,
"poll_results": null,
"created_at": "2026-01-15T09:30:00.000Z",
"completed_at": "2026-01-15T09:31:00.000Z"
}
]
}{
"code": "ERROR",
"message": "Broadcast not found — no broadcast with the given broadcast_id exists in the workspace",
"status": 400
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}POST /message/queues with broadcast_id in the request body insteadAuthorizations
Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.
Headers
Phone to act with: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). The phone must be connected to the org and accessible by the API token.
1"919876543210"
Query Parameters
Id of the broadcast to fetch (a UUID), as returned when the broadcast was created
1"00000000-0000-0000-0000-000000000000"
Response
The status of the broadcast with its per-chat logs
Aggregate delivery status of a broadcast — chat and recipient counts, delivery/read percentages, scheduling info and the per-chat delivery logs.
Unique id of the broadcast (a UUID)
"00000000-0000-0000-0000-000000000000"
Id of the organization that owns the broadcast
"00000000-0000-0000-0000-000000000000"
The message content and metadata the broadcast was created with. null when not recorded.
{ "body": "Hello from Periskope!", "message_type": "chat" }
When the broadcast was created, as an ISO 8601 timestamp
"2026-01-15T09:30:00.000Z"
Current status of the broadcast: one of inprogress, completed, stopped, expired. null when the status has not been set yet.
inprogress, completed, stopped, expired "completed"
Total number of chats targeted by the broadcast. null when the broadcast has no target chat list.
25
Number of chats the broadcast was successfully sent to
22
Number of chats where the broadcast failed to send
1
Number of chats where the broadcast is queued but not yet sent
2
Total number of recipients the broadcast was delivered to, across all chats. null while no delivery info has been received.
180
Total number of recipients that read the broadcast, across all chats. null while no read info has been received.
120
Total number of members across all targeted chats — the denominator for the percentages. null when no per-chat member counts exist yet.
200
Percentage of members the broadcast was delivered to, as an integer 0-100. 0 when no member counts are available.
0 <= x <= 10090
Percentage of members that read the broadcast, as an integer 0-100. 0 when no member counts are available.
0 <= x <= 10060
Who initiated the broadcast: the member's email, or "api" when initiated via the API. null for scheduled broadcasts that have not run yet.
"api"
When the broadcast was executed, as an ISO 8601 timestamp. null while it has not run yet.
"2026-01-15T09:31:00.000Z"
When the broadcast is scheduled to run, as an ISO 8601 timestamp. null for broadcasts sent immediately.
null
When the broadcast ran or is due to run: performed_at when executed, otherwise scheduled_at, otherwise created_at. ISO 8601 timestamp.
"2026-01-15T09:31:00.000Z"
How many times the broadcast has been retried
0
Details of previous retry runs of the broadcast. null when it has never been retried.
null
broadcast_id of the original broadcast when this broadcast is a retry or a repeat occurrence. null otherwise.
null
Repeat configuration when the broadcast is recurring. null for one-off broadcasts.
null
Whether the recurring schedule is active. null for one-off broadcasts.
null
When the next occurrence of a recurring broadcast will run, as an ISO 8601 timestamp. null for one-off broadcasts.
null
How many occurrences of a recurring broadcast have run. null for one-off broadcasts.
null
Per-chat delivery log — one entry for every chat targeted by the broadcast
Show child attributes
Show child attributes
Was this page helpful?