> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Send Sync Message > Sends a message like POST /message/send (including automatic phone selection for group chats when x-phone is omitted), then waits up to sync_timeout seconds (default 20) for WhatsApp to accept or reject the message. When accepted in time the response carries the sent message record (status sent). When the send fails in time — WhatsApp rejected it (ack -1), or the phone gave up before it reached WhatsApp, for example because the number is not on WhatsApp — the request fails with a 400 MESSAGE_SEND_FAILED error carrying the reason, so the caller can retry — typically from another phone via the x-phone header. Otherwise it falls back to the asynchronous queued response. ## OpenAPI ````yaml api-reference/openapi-generated.json POST /v1/message/send-sync openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/message/send-sync: post: tags: - Messages summary: Send a message and wait for confirmation description: >- Sends a message like POST /message/send (including automatic phone selection for group chats when x-phone is omitted), then waits up to sync_timeout seconds (default 20) for WhatsApp to accept or reject the message. When accepted in time the response carries the sent message record (status sent). When the send fails in time — WhatsApp rejected it (ack -1), or the phone gave up before it reached WhatsApp, for example because the number is not on WhatsApp — the request fails with a 400 MESSAGE_SEND_FAILED error carrying the reason, so the caller can retry — typically from another phone via the x-phone header. Otherwise it falls back to the asynchronous queued response. operationId: sendMessageSync parameters: - schema: type: string example: '919876543210' description: >- 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. required: false description: >- 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. name: x-phone in: header requestBody: content: application/json: schema: type: object properties: chat_id: type: string minLength: 1 description: >- 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). example: 911111111111@c.us message: type: string description: >- 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: type: object properties: type: type: string enum: - image - video - document - audio - ptt description: >- Kind of media being sent: 'image', 'video', 'document', 'audio', or 'ptt' (push-to-talk voice note). Determines the message_type of the resulting message. example: image url: type: string description: >- Publicly accessible URL that hosts the content to be sent. Provide either url or filedata, not both. example: https://example.com/files/image.png filedata: type: string description: >- Raw bytes of the file, encoded as base64. Alternative to url — provide either url or filedata, not both. example: iVBORw0KGgoAAAANSUhEUgAA... mimetype: type: string description: >- MIME type of the media file (e.g. image/png, video/mp4, text/csv). Recommended when sending filedata. example: image/png filename: type: string description: >- Filename of the media, shown in the chat (mainly relevant for document messages). Defaults to the last path segment of url. example: image.png required: - type description: >- 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: type: object properties: pollName: type: string minLength: 1 description: The question or title of the poll example: Which day suits everyone for the demo? pollOptions: type: array items: type: string minItems: 2 maxItems: 12 description: >- The answer options of the poll — between 2 and 12 entries example: - Monday - Wednesday - Friday options: type: object properties: allowMultipleAnswers: type: boolean description: >- When true, respondents can select multiple options. Defaults to single choice. example: true pollId: type: string description: >- Optional unique identifier of the poll — useful to correlate the same poll sent across multiple chats example: poll-2026-demo-day description: Additional options of the poll required: - pollName - pollOptions description: >- Poll to send instead of a plain message. The resulting message has message_type poll_creation. reply_to: type: string description: >- message_id of an existing message in the chat to reply to. The sent message quotes it. example: >- true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA options: type: object properties: hide_url_preview: type: boolean description: >- When true, disables the automatic link preview for URLs contained in the message example: true description: Additional sending options sync_timeout: type: integer minimum: 1 maximum: 60 description: >- 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. example: 20 required: - chat_id responses: '200': description: >- The sent message when WhatsApp accepted it within sync_timeout, otherwise the queued response content: application/json: schema: anyOf: - type: object properties: status: type: string enum: - sent description: >- WhatsApp accepted the message within the wait window (message.ack is 1 or higher) unique_id: type: string description: Provisional id assigned when the message was queued example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA message: $ref: '#/components/schemas/Message' description: Accepted within the wait window - type: object properties: status: type: string enum: - queued description: >- Always queued — messages are not sent synchronously, they are queued on the phone and submitted in the background unique_id: type: string description: >- 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: type: string description: >- 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: type: number description: >- Position of the job in the send queue at the moment it was enqueued (0 = next in line) example: 0 track_by: type: object properties: unique_id: type: string description: >- Ready-to-use path for tracking the message by unique_id example: >- GET /messages/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/status description: Convenience pointers for tracking the message description: >- Neither accepted nor rejected within sync_timeout — identical to the POST /message/send response; track via GET /message/{unique_id}/status. A rejection or send failure within the window is a 400 MESSAGE_SEND_FAILED error, not a response branch. description: >- The sent message when WhatsApp accepted it within sync_timeout, otherwise the asynchronous queued response examples: default: summary: Response body value: status: sent unique_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA message: message_id: >- true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA unique_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA org_id: 00000000-0000-0000-0000-000000000000 org_phone: 911111111111@c.us chat_id: 120363000000000000@g.us body: Hello World message_type: chat timestamp: '2026-01-15T09:30:00+00:00' from_me: true ack: '3' performed_by: api sender_phone: 911111111111@c.us quoted_message_id: null broadcast_id: null is_deleted: null media: path: https://example.com/files/image.png mimetype: image/png filename: image.png size: 24576 dimensions: width: null height: null ar: null thumbnail: null mentioned_ids: [] prev_body: null sent_message_id: 00000000-0000-0000-0000-000000000000 delivery_info: delivered: 911111111111@c.us: 1737967705196 read: 911111111111@c.us: 1737967704763 pending: [] delivered_count: 1 read_count: 1 poll_info: {} poll_results: {} flag_status: null updated_at: '2026-01-15T09:35:38.221+00:00' reactions: - reaction_id: true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAA message_id: >- true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA unique_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA chat_id: 911111111111@c.us org_id: 00000000-0000-0000-0000-000000000000 org_phone: 911111111111@c.us sender_id: 911111111111@c.us reaction: 😄 read: true timestamp: '2026-01-15T09:31:57.008+00:00' '400': description: >- The phone is off or its server is unreachable — or the send failed within the wait window (code MESSAGE_SEND_FAILED): WhatsApp rejected the message (ack -1), or the phone gave up before it reached WhatsApp, for example because the number is not on WhatsApp. details carry unique_id, org_phone, chat_id, ack -1 and the failure reason when one was reported, plus message_id when a message record exists. Retry from another phone via the x-phone header. content: application/json: examples: error: summary: >- The phone is off or its server is unreachable — or the send failed within the wait window (code MESSAGE_SEND_FAILED): WhatsApp rejected the message (ack -1), or the phone gave up before it reached WhatsApp, for example because the number is not on WhatsApp. details carry unique_id, org_phone, chat_id, ack -1 and the failure reason when one was reported, plus message_id when a message record exists. Retry from another phone via the x-phone header. value: code: ERROR message: >- The phone is off or its server is unreachable — or the send failed within the wait window (code MESSAGE_SEND_FAILED): WhatsApp rejected the message (ack -1), or the phone gave up before it reached WhatsApp, for example because the number is not on WhatsApp. details carry unique_id, org_phone, chat_id, ack -1 and the failure reason when one was reported, plus message_id when a message record exists. Retry from another phone via the x-phone header. status: 400 schema: type: object properties: code: type: string example: ERROR message: type: string example: >- The phone is off or its server is unreachable — or the send failed within the wait window (code MESSAGE_SEND_FAILED): WhatsApp rejected the message (ack -1), or the phone gave up before it reached WhatsApp, for example because the number is not on WhatsApp. details carry unique_id, org_phone, chat_id, ack -1 and the failure reason when one was reported, plus message_id when a message record exists. Retry from another phone via the x-phone header. status: type: integer example: 400 example: code: ERROR message: >- The phone is off or its server is unreachable — or the send failed within the wait window (code MESSAGE_SEND_FAILED): WhatsApp rejected the message (ack -1), or the phone gave up before it reached WhatsApp, for example because the number is not on WhatsApp. details carry unique_id, org_phone, chat_id, ack -1 and the failure reason when one was reported, plus message_id when a message record exists. Retry from another phone via the x-phone header. status: 400 '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '404': description: >- x-phone omitted and the group chat was not found on any phone of the org content: application/json: examples: error: summary: >- x-phone omitted and the group chat was not found on any phone of the org value: code: NOT_FOUND_ERROR message: >- x-phone omitted and the group chat was not found on any phone of the org status: 404 schema: type: object properties: code: type: string example: NOT_FOUND_ERROR message: type: string example: >- x-phone omitted and the group chat was not found on any phone of the org status: type: integer example: 404 example: code: NOT_FOUND_ERROR message: >- x-phone omitted and the group chat was not found on any phone of the org status: 404 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- 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.messages.sendMessageSync({ chat_id: '911111111111@c.us', }); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X POST 'https://api.periskope.app/v1/message/send-sync' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'x-phone: 919876543210' \ -H 'Content-Type: application/json' \ -d '{ "chat_id": "911111111111@c.us" }' components: schemas: Message: type: object properties: message_id: type: string description: >- WhatsApp message id, in the form __. Accepted wherever a message_id path parameter is expected. example: true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA unique_id: type: string description: >- Provisional id assigned when the message was queued via the API — the same value returned by POST /message/send. Also accepted wherever a message_id path parameter is expected. null for messages that did not originate from the API. example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA org_id: type: string description: Id of the organization the message belongs to example: 00000000-0000-0000-0000-000000000000 org_phone: type: string description: >- Org phone (WhatsApp account) the message was sent or received on, suffixed with @c.us example: 911111111111@c.us chat_id: type: string description: >- Chat the message belongs to — @c.us for 1-1 chats, @g.us for group chats example: 120363000000000000@g.us body: type: string description: >- Text content of the message, or the caption for media messages. null when the message has no text. example: Hello World message_type: type: string description: >- Content type of the message: 'chat' for text, or e.g. 'image', 'video', 'document', 'audio', 'ptt', 'poll_creation', 'location', 'vcard' example: chat timestamp: type: string description: When the message was sent, as an ISO 8601 timestamp example: '2026-01-15T09:30:00+00:00' from_me: type: boolean description: >- Whether the message was sent by the org phone (true) or received from the contact (false) example: true ack: type: string description: >- Delivery acknowledgement level as a string: '-1' failed, '0' pending, '1' sent, '2'/'3' delivered, '4' read, '5' played. null when unknown. example: '3' performed_by: type: string description: >- Who triggered the message from Periskope: a member's email, or 'api' when sent via the API. null for messages sent from the phone itself. example: api sender_phone: type: string description: >- chat_id of the actual sender — in group chats this is the participant who sent the message example: 911111111111@c.us quoted_message_id: type: string description: >- message_id of the message this one replies to (set via reply_to when sending). null when not a reply. example: null broadcast_id: type: string description: >- Id of the broadcast that produced this message, when it was sent via POST /message/broadcast. null otherwise. example: null is_deleted: type: boolean description: >- Whether the message has been deleted for everyone. null when never deleted. example: null media: $ref: '#/components/schemas/MessageMedia' mentioned_ids: type: array items: type: string description: chat_ids of the participants mentioned in the message example: [] prev_body: type: string description: >- Previous text content, kept when the message was edited. null when never edited. example: null sent_message_id: type: string description: >- Internal queue job id (queue_id) that produced this message when it was sent through the message queue. null otherwise. example: 00000000-0000-0000-0000-000000000000 delivery_info: $ref: '#/components/schemas/MessageDeliveryInfo' poll_info: type: object description: >- The poll definition ({pollName, pollOptions, options}) for poll_creation messages. null otherwise. poll_results: type: object description: >- Votes cast on the poll, as a map of option name to voters. null for non-poll messages. flag_status: type: boolean description: >- Whether the message is currently flagged for follow-up in Periskope. null when never flagged. example: null updated_at: type: string description: When the message record was last updated, as an ISO 8601 timestamp example: '2026-01-15T09:35:38.221+00:00' reactions: type: array items: $ref: '#/components/schemas/MessageReaction' description: >- Reactions placed on the message. Present on GET /message/{message_id}; an empty array when there are none. description: >- 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, ...). MessageMedia: type: object properties: path: type: string description: URL of the media content example: https://example.com/files/image.png mimetype: type: string description: MIME type of the media file example: image/png filename: type: string description: >- Filename of the media — the filename provided when sending, or one derived from the url example: image.png size: type: number description: Size of the media file in bytes, when known example: 24576 dimensions: type: object properties: width: type: number description: Width in pixels height: type: number description: Height in pixels ar: type: number description: Aspect ratio (width / height) description: Pixel dimensions of the media, for images and videos thumbnail: type: string description: Thumbnail of the media, when generated description: Media attached to the message. null for text-only messages. MessageDeliveryInfo: type: object properties: delivered: type: object additionalProperties: type: number description: >- Map of recipient chat_id to the epoch-millisecond timestamp the message was delivered to them example: 911111111111@c.us: 1737967705196 read: type: object additionalProperties: type: number description: >- Map of recipient chat_id to the epoch-millisecond timestamp they read the message example: 911111111111@c.us: 1737967704763 pending: type: array items: type: string description: chat_ids of recipients the message has not reached yet example: [] delivered_count: type: number description: Number of recipients the message was delivered to example: 1 read_count: type: number description: Number of recipients who read the message example: 1 description: >- Per-recipient delivery and read receipts. null when no receipts have been recorded. MessageReaction: type: object properties: reaction_id: type: string description: Unique id of the reaction (a WhatsApp message_id) example: true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAA message_id: type: string description: message_id of the message the reaction belongs to example: true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA unique_id: type: string description: >- unique_id of the message the reaction belongs to. null when not known. example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA chat_id: type: string description: Chat the reaction happened in example: 911111111111@c.us org_id: type: string description: Id of the organization the reaction belongs to example: 00000000-0000-0000-0000-000000000000 org_phone: type: string description: >- Org phone (WhatsApp account) that observed the reaction, suffixed with @c.us example: 911111111111@c.us sender_id: type: string description: chat_id of the person who reacted example: 911111111111@c.us reaction: type: string description: >- The reaction emoji. An empty string or null means the reaction was removed. example: 😄 read: type: boolean description: Whether the reaction has been seen. null when unknown. example: true timestamp: type: string description: When the reaction happened, as an ISO 8601 timestamp example: '2026-01-15T09:31:57.008+00:00' description: A reaction placed on a message securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.