Skip to main content
TypeScript

Authorizations

Authorization
string
header
required

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

x-phone
string

Optional. Scope results to a single phone: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to return data across all phones the API token can access.

Example:

"919876543210"

Body

application/json
chat_ids

Recipients of the broadcast, as an array of chat ids (or a single comma-separated string). For group chats, the chat_id ending with @g.us; for 1-1 chats, country code + number of the contact, optionally suffixed with @c.us (e.g. 911111111111 or 911111111111@c.us). Duplicates are removed. Either chat_ids or label is required.

Example:
label
string

Name of a chat label — when chat_ids is empty, the broadcast is sent to every chat carrying this label. Ignored when chat_ids is provided.

Example:

"newsletter"

message
string

The text body of the message, or the caption when media is provided. Supports the basic WhatsApp markdown formatting (bold, italic, strikethrough, monospace).

Example:

"Hello World"

media
object

Media to send — a document, image, video, audio file or voice note. Provide either a public url or base64 filedata. The message text, when given, becomes the caption.

poll
object

Poll to send instead of a plain message. The resulting message has message_type poll_creation.

reply_to
string

message_id of an existing message in the chat to reply to. The sent message quotes it.

Example:

"true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

options
object

Additional sending options

variables
object[]

Per-chat values for the {{placeholders}} used in the message. Required when the message contains placeholders: every recipient chat must have an entry covering exactly the placeholder names — missing or extra keys are rejected.

Example:
scheduled_at
string

UTC date and time to start the broadcast at, in ISO 8601 format. Must be in the future. Omit to start immediately.

Example:

"2026-02-06T11:21:00Z"

delay
number

Time interval between consecutive messages, in seconds (0-60). Defaults to about 1 second when omitted.

Required range: 0 <= x <= 60
Example:

10

org_phones
string[]

Org phones to send the broadcast from — recipients are distributed across them. Takes precedence over the x-phone header. When neither is given, every available phone of the org is used.

Example:

Response

The created broadcast

broadcast_id
string

Id of the created broadcast. Use it to track progress via POST /message/queues or to cancel/stop via DELETE /message/broadcast/{broadcast_id}. Messages produced by the broadcast carry it as broadcast_id.

Example:

"00000000-0000-0000-0000-000000000000"

hint
string

Human-readable pointer on how to track the broadcast

Example:

"You can track broadcast status by making a POST request to /messages/queues with { \"broadcast_id\": \"00000000-0000-0000-0000-000000000000\" } as body"