Visão Geral

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não O módulo /api/message/* cobre o envio de todos os formatos suportados pelo WhatsApp, texto, mídias, sticker, localização, contato, reação, enquete, carrossel, botões, lista, formulário, PIX e status (stories). Todas as rotas validam ownership da instância e aceitam TokenAccount ou TokenInstance.

Para buscar uma mensagem por ID use GET /api/chat/getMessage/:instance, esse endpoint deixou de pertencer ao módulo de mensagens.

Endpoints disponíveis

Método	Path	Tipo
POST	`/api/message/text/:instance`	Texto
POST	`/api/message/media/:instance`	Imagem / vídeo / áudio / documento
POST	`/api/message/sticker/:instance`	Sticker (WebP)
POST	`/api/message/location/:instance`	Localização
POST	`/api/message/contact/:instance`	Contato (vCard)
POST	`/api/message/reaction/:instance`	Reação (emoji)
POST	`/api/message/poll/:instance`	Enquete
POST	`/api/message/carousel/:instance`	Carrossel de cards
POST	`/api/message/button/:instance`	Botões interativos
POST	`/api/message/list/:instance`	Lista (sections)
POST	`/api/message/form/:instance`	Formulário (Native Flow)
POST	`/api/message/pix/:instance`	PIX (pagamento BR)
POST	`/api/message/status/:instance`	Status (stories)

Estrutura comum

Destinatário (`number` ou `to`)

A maioria dos endpoints aceita o destinatário no campo number. Os formatos suportados são:

Número simples: "5511999999999" (preferido).
JID privado: "5511999999999@s.whatsapp.net".
JID oculto (@lid): "123456789012345@lid", identificador anônimo usado pelo WhatsApp em grupos/canais quando o número real não está exposto.
JID grupo: "120363406289005073@g.us".
JID newsletter: "120363422585881117@newsletter".
Status broadcast: "status@broadcast".

Comportamento brasileiro do número

Para números começando com 55 (Brasil), o serviço tenta automaticamente variações:

Com 9 (5511999999999)
Sem 9 (551199999999)

Isso resolve um histórico de inconsistências em DDDs antigos. Se o número não for encontrado em nenhuma das variações, o handler retorna 400 Number is not registered on WhatsApp.

Campos opcionais comuns

Campo	Tipo	Aplica-se a	Descrição
`delay`	int (segundos)	quase todos	Tempo de espera antes do envio. Durante o intervalo o servidor envia “digitando…” e depois “paused”.
`replyTo`	string	quase todos	ID da mensagem original a citar. A mensagem precisa pertencer à mesma instância e estar no banco.
`replyPrivate`	bool	quase todos	Quando a mensagem citada é de grupo, redireciona a resposta para o privado do autor (mantém a citação).
`mention`	string[]	text / media	Números (ou JIDs) a mencionar. Apenas em grupos. Limite de 10 por mensagem.
`mentionAll`	bool	text / media	Menciona todos os membros do grupo (`@todos`). Apenas em grupos.
`linkPreview`	bool	text	Quando `true`, busca metadados Open Graph da 1ª URL e envia como `ExtendedTextMessage` com card. Default `false`.
`source`	string	todos	Identificador de origem para rastreabilidade (ex.: `crm`, `n8n`). Default: `"api"`.

delay é em segundos (não milissegundos). Valor 3 = 3 s de “digitando”.

Reactions (/api/message/reaction/:instance) não suportam delay/replyTo/mention, o payload é mínimo (messageId, reaction, participant). Status (/api/message/status/:instance) também não usa number/replyTo (sempre vai para status@broadcast).

Resposta padrão (200)

Todos os endpoints de envio retornam o mesmo envelope MessageSentDetails:

{
  "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"
    }
  }
}

Campos opcionais no data: mentions (quando há menção), replyTo (quando há citação), chat.groupName (quando é grupo), mediaUrl/mediaMimeType/mediaSize/fileName (quando é mídia), vcard (quando é contato). 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

Erros comuns

Status	Mensagem
400	`Instance name is required`
400	`Invalid request body: <detalhe>`
400	`Number is required`
400	`Message is required` (e variantes por endpoint: `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>`

Envelope de erro:

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

Limites observados

Recurso	Limite
Texto	~65k caracteres (mensagens > 4096 podem ser cortadas em alguns clients)
Imagem / vídeo / áudio	até 16 MB
Documento	até 100 MB
Botões	máx 3 por mensagem
Lista	máx 10 sections × 10 rows
Carrossel	máx 10 cards
Enquete	2 a 12 opções

Próximos passos

Enviar texto

Endpoint mais usado, ideal como “Hello World”.

Enviar mídia

Imagem, vídeo, áudio e documento por URL ou base64.

Buscar mensagem por ID

Recupera uma mensagem específica do histórico.

Webhooks

Recebe eventos message.exchange em tempo real.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Endpoints disponíveis

Estrutura comum

Destinatário (`number` ou `to`)

Comportamento brasileiro do número

Campos opcionais comuns

Resposta padrão (200)

Erros comuns

Limites observados

Próximos passos

Enviar texto

Enviar mídia

Buscar mensagem por ID

Webhooks

​Endpoints disponíveis

​Estrutura comum

​Destinatário (number ou to)

​Comportamento brasileiro do número

​Campos opcionais comuns

​Resposta padrão (200)

​Erros comuns

​Limites observados

​Próximos passos

Enviar texto

Enviar mídia

Buscar mensagem por ID

Webhooks

Endpoints disponíveis

Estrutura comum

Destinatário (`number` ou `to`)

Comportamento brasileiro do número

Campos opcionais comuns

Resposta padrão (200)

Erros comuns

Limites observados

Próximos passos