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

Phone to send from: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Required for 1-1 chats. For group chats it can be omitted — a connected phone that is in the group is selected automatically, within the token's phone scopes.

Example:

"919876543210"

Body

application/json
chat_id
string
required

Chat to send the message to. 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).

Minimum string length: 1
Example:

"911111111111@c.us"

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

Response

The queued message

status
enum<string>

Always queued — messages are not sent synchronously, they are queued on the phone and submitted in the background

Available options:
queued
unique_id
string

Provisional id of the message. Use it with GET /message/{unique_id}/status to track delivery, or with GET /message/{message_id} once processed. The resulting message record carries it as unique_id.

Example:

"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

queue_id
string

Id of the queue job on the phone. The resulting message record carries it as sent_message_id, and the queue endpoints accept it as queue_id.

Example:

"00000000-0000-0000-0000-000000000000"

queue_position
number

Position of the job in the send queue at the moment it was enqueued (0 = next in line)

Example:

0

track_by
object

Convenience pointers for tracking the message