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
required

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.

Minimum string length: 1
Example:

"919876543210"

Body

application/json
chat_id
string
required

Chat to send to. For groups, the chat_id ending with @g.us; for 1-1 chats, country code + number of the contact, optionally suffixed with @c.us

Minimum string length: 1
Example:

"120363000000000000@g.us"

scheduled_at
string
required

When to send (the first run for repeating messages), as an ISO 8601 timestamp in the future. Send it in UTC (e.g. 2026-02-01T09:00:00Z); recurrence for repeating messages is computed in UTC.

Example:

"2026-02-01T09:00:00Z"

message
string

Text content to send. Required unless media is provided; becomes the caption when media is also given.

Example:

"Weekly reminder: submit your report"

media
object

Attachment to send. Required unless message is provided.

is_repeat
boolean

Whether the message repeats. Requires repeat_config.repeat_interval when true. Defaults to false (send once).

Example:

false

repeat_config
object

How a repeating scheduled message recurs. All times are computed in UTC.

Response

The created scheduled message

A scheduled message — content sent to a chat at scheduled_at, once or on a repeating series

scheduled_id
string

Unique id of the scheduled message

Example:

"00000000-0000-0000-0000-000000000000"

org_id
string

Id of the organization the scheduled message belongs to

Example:

"00000000-0000-0000-0000-000000000000"

org_phone
string

Org phone (WhatsApp account) the message is sent from, as country code + number suffixed with @c.us

Example:

"911111111111@c.us"

chat_id
string

Chat the message is sent to — @c.us for 1-1 chats, @g.us for group chats

Example:

"120363000000000000@g.us"

message_payload
object

Content sent on every run — same shape as POST /message/send

scheduled_at
string

When the next run happens, as an ISO 8601 timestamp. For repeating messages this advances after every run.

Example:

"2026-02-01T09:00:00.000Z"

is_repeat
boolean

Whether the message repeats or sends once

Example:

true

repeat_config
object

How the message recurs. null for one-time messages.

status
enum<string>

Lifecycle status: 'scheduled' (waiting for the next run), 'paused' (runs are skipped) or 'completed'

Available options:
scheduled,
paused,
completed
Example:

"scheduled"

skip_next
boolean

When true, the next run is skipped once and the series continues

Example:

false

paused_at
string

When the schedule was paused, as an ISO 8601 timestamp. null while not paused.

updated_at
string

When the schedule completed (one-time message sent, or series ended), as an ISO 8601 timestamp. null while pending.

performed_by
string

Who created the schedule: a member email, or "api"

Example:

"api"

created_at
string

When the schedule was created, as an ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"