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

sync_timeout
integer

How long to wait for the send confirmation, in seconds (1-60). When the message is not confirmed within this window the response falls back to the asynchronous shape. Defaults to 20.

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

20

Response

The sent message when confirmed within sync_timeout, otherwise the queued response

The sent message when confirmed within sync_timeout, otherwise the asynchronous queued response

status
enum<string>

The message was confirmed sent within the wait window

Available options:
sent
unique_id
string

Provisional id assigned when the message was queued

Example:

"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

message
object

A WhatsApp message record. Responses may include additional raw fields of the underlying record (id, author, links, location, vcards, is_forwarded, has_media, message_ticket_id, ...).