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.scheduledMessages.createScheduledMessage({
chat_id: '120363000000000000@g.us',
scheduled_at: '2026-02-01T09:00:00Z',
});
console.log(response);
}
main();curl -X POST 'https://api.periskope.app/v1/message/scheduled' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "120363000000000000@g.us",
"scheduled_at": "2026-02-01T09:00:00Z"
}'{
"scheduled_id": "00000000-0000-0000-0000-000000000000",
"org_id": "00000000-0000-0000-0000-000000000000",
"org_phone": "911111111111@c.us",
"chat_id": "120363000000000000@g.us",
"message_payload": {
"message": "Weekly reminder: submit your report",
"media": {}
},
"scheduled_at": "2026-02-01T09:00:00.000Z",
"is_repeat": true,
"repeat_config": {
"repeat_interval": "week",
"repeat_value": 1,
"repeat_days": [
"monday",
"friday"
],
"repeat_ends": "2026-12-31T00:00:00Z"
},
"status": "scheduled",
"skip_next": false,
"paused_at": null,
"updated_at": null,
"performed_by": "api",
"created_at": "2026-01-15T09:30:00.000Z"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "NOT_FOUND_ERROR",
"message": "Chat not found — no chat with the given chat_id exists for the phone",
"status": 404
}{
"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
}Schedule a Message
Schedules a message (text and/or media) to be sent to a chat from the phone in the x-phone header at scheduled_at — once, or repeating per repeat_config. The send itself happens in the background at run time.
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.scheduledMessages.createScheduledMessage({
chat_id: '120363000000000000@g.us',
scheduled_at: '2026-02-01T09:00:00Z',
});
console.log(response);
}
main();curl -X POST 'https://api.periskope.app/v1/message/scheduled' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210' \
-H 'Content-Type: application/json' \
-d '{
"chat_id": "120363000000000000@g.us",
"scheduled_at": "2026-02-01T09:00:00Z"
}'{
"scheduled_id": "00000000-0000-0000-0000-000000000000",
"org_id": "00000000-0000-0000-0000-000000000000",
"org_phone": "911111111111@c.us",
"chat_id": "120363000000000000@g.us",
"message_payload": {
"message": "Weekly reminder: submit your report",
"media": {}
},
"scheduled_at": "2026-02-01T09:00:00.000Z",
"is_repeat": true,
"repeat_config": {
"repeat_interval": "week",
"repeat_value": 1,
"repeat_days": [
"monday",
"friday"
],
"repeat_ends": "2026-12-31T00:00:00Z"
},
"status": "scheduled",
"skip_next": false,
"paused_at": null,
"updated_at": null,
"performed_by": "api",
"created_at": "2026-01-15T09:30:00.000Z"
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "NOT_FOUND_ERROR",
"message": "Chat not found — no chat with the given chat_id exists for the phone",
"status": 404
}{
"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
}Authorizations
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"
Body
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
1"120363000000000000@g.us"
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.
"2026-02-01T09:00:00Z"
Text content to send. Required unless media is provided; becomes the caption when media is also given.
"Weekly reminder: submit your report"
Attachment to send. Required unless message is provided.
Show child attributes
Show child attributes
Whether the message repeats. Requires repeat_config.repeat_interval when true. Defaults to false (send once).
false
How a repeating scheduled message recurs. All times are computed in UTC.
Show child attributes
Show child attributes
Response
The created scheduled message
A scheduled message — content sent to a chat at scheduled_at, once or on a repeating series
Unique id of the scheduled message
"00000000-0000-0000-0000-000000000000"
Id of the organization the scheduled message belongs to
"00000000-0000-0000-0000-000000000000"
Org phone (WhatsApp account) the message is sent from, as country code + number suffixed with @c.us
"911111111111@c.us"
Chat the message is sent to — @c.us for 1-1 chats, @g.us for group chats
"120363000000000000@g.us"
Content sent on every run — same shape as POST /message/send
Show child attributes
Show child attributes
When the next run happens, as an ISO 8601 timestamp. For repeating messages this advances after every run.
"2026-02-01T09:00:00.000Z"
Whether the message repeats or sends once
true
How the message recurs. null for one-time messages.
Show child attributes
Show child attributes
Lifecycle status: 'scheduled' (waiting for the next run), 'paused' (runs are skipped) or 'completed'
scheduled, paused, completed "scheduled"
When true, the next run is skipped once and the series continues
false
When the schedule was paused, as an ISO 8601 timestamp. null while not paused.
When the schedule completed (one-time message sent, or series ended), as an ISO 8601 timestamp. null while pending.
Who created the schedule: a member email, or "api"
"api"
When the schedule was created, as an ISO 8601 timestamp
"2026-01-15T09:30:00.000Z"
Was this page helpful?