Overview

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no The /api/message/* module covers sending every format supported by WhatsApp, text, media, sticker, location, contact, reaction, poll, carousel, buttons, list, form, PIX and status (stories). All routes validate instance ownership and accept either TokenAccount or TokenInstance.

To fetch a message by ID use GET /api/chat/getMessage/:instance; that endpoint no longer belongs to the messages module.

Available endpoints

Method	Path	Type
POST	`/api/message/text/:instance`	Text
POST	`/api/message/media/:instance`	Image / video / audio / document
POST	`/api/message/sticker/:instance`	Sticker (WebP)
POST	`/api/message/location/:instance`	Location
POST	`/api/message/contact/:instance`	Contact (vCard)
POST	`/api/message/reaction/:instance`	Reaction (emoji)
POST	`/api/message/poll/:instance`	Poll
POST	`/api/message/carousel/:instance`	Card carousel
POST	`/api/message/button/:instance`	Interactive buttons
POST	`/api/message/list/:instance`	List (sections)
POST	`/api/message/form/:instance`	Form (Native Flow)
POST	`/api/message/pix/:instance`	PIX (BR payment)
POST	`/api/message/status/:instance`	Status (stories)

Common structure

Recipient (`number` or `to`)

Most endpoints accept the recipient in the number field. Supported formats:

Plain number: "5511999999999" (preferred).
Private JID: "5511999999999@s.whatsapp.net".
Hidden JID (@lid): "123456789012345@lid", anonymous identifier WhatsApp uses in groups/channels when the real number is not exposed.
Group JID: "120363406289005073@g.us".
Newsletter JID: "120363422585881117@newsletter".
Status broadcast: "status@broadcast".

Brazilian number behavior

For numbers starting with 55 (Brazil), the service automatically tries variations:

With 9 (5511999999999)
Without 9 (551199999999)

This works around a long-standing inconsistency in older area codes. If the number is not found in any of the variations, the handler returns 400 Number is not registered on WhatsApp.

Common optional fields

Field	Type	Applies to	Description
`delay`	int (seconds)	almost all	Wait time before sending. During the interval the server sends “typing…” and then “paused”.
`replyTo`	string	almost all	ID of the original message to quote. The message must belong to the same instance and exist in the database.
`replyPrivate`	bool	almost all	When the quoted message is from a group, redirects the reply to the author’s private chat (keeping the quote).
`mention`	string[]	text / media	Numbers (or JIDs) to mention. Group chats only. Limit of 10 per message.
`mentionAll`	bool	text / media	Mentions every member of the group (`@everyone`). Group chats only.
`linkPreview`	bool	text	When `true`, fetches Open Graph metadata from the first URL and sends as `ExtendedTextMessage` with a card. Default `false`.
`source`	string	all	Origin identifier for traceability (e.g., `crm`, `n8n`). Default: `"api"`.

delay is in seconds (not milliseconds). A value of 3 = 3 s of “typing”.

Reactions (/api/message/reaction/:instance) do not support delay/replyTo/mention, the payload is minimal (messageId, reaction, participant). Status (/api/message/status/:instance) also does not use number/replyTo (it always goes to status@broadcast).

Standard response (200)

All send endpoints return the same MessageSentDetails envelope:

{
  "success": true,
  "message": "Message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "outgoing",
    "messageType": "text",
    "content":     "Ola!",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}

Optional fields in data: mentions (when there is a mention), replyTo (when there is a quote), chat.groupName (when it is a group), mediaUrl/mediaMimeType/mediaSize/fileName (when it is media), vcard (when it is a contact). status ∈

sent | disconnected | invalid_number | mentions_not_supported | reply_message_not_found | reply_message_instance_mismatch | private_reply_failed | send_failed | media_download_failed | media_upload_failed | media_validation_failed | unsupported_media_type | image_conversion_failed | sticker_upload_failed | audio_conversion_failed | invalid_message_id | missing_participant | invalid_request

Common errors

Status	Message
400	`Instance name is required`
400	`Invalid request body: <detail>`
400	`Number is required`
400	`Message is required` (and per-endpoint variants: `MediaURL is required`, `Question is required`, etc.)
400	`Mentions are only supported in group chats`
400	`Original message not found (ID: ...)`
400	`Original message does not belong to this instance`
404	`Instance not found`
503	`Instance is not connected to WhatsApp`
500	`Failed to send message: <reason>`

Error envelope:

{
  "success": false,
  "error": { "message": "Number is not registered on WhatsApp" }
}

Observed limits

Resource	Limit
Text	~65k characters (messages > 4096 may be truncated by some clients)
Image / video / audio	up to 16 MB
Document	up to 100 MB
Buttons	max 3 per message
List	max 10 sections × 10 rows
Carousel	max 10 cards
Poll	2 to 12 options

Next steps

Send text

The most-used endpoint, ideal as a “Hello World”.

Send media

Image, video, audio and document by URL or base64.

Fetch message by ID

Retrieves a specific message from the history.

Webhooks

Receive message.exchange events in real time.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Available endpoints

Common structure

Recipient (`number` or `to`)

Brazilian number behavior

Common optional fields

Standard response (200)

Common errors

Observed limits

Next steps

Send text

Send media

Fetch message by ID

Webhooks

​Available endpoints

​Common structure

​Recipient (number or to)

​Brazilian number behavior

​Common optional fields

​Standard response (200)

​Common errors

​Observed limits

​Next steps

Send text

Send media

Fetch message by ID

Webhooks

Available endpoints

Common structure

Recipient (`number` or `to`)

Brazilian number behavior

Common optional fields

Standard response (200)

Common errors

Observed limits

Next steps