Resumen

Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no El módulo /api/message/* cubre el envío de todos los formatos compatibles con WhatsApp, texto, media, sticker, ubicación, contacto, reacción, encuesta, carrusel, botones, lista, formulario, PIX y status (historias). Todas las rutas validan la propiedad de la instancia y aceptan tanto TokenAccount como TokenInstance.

Para buscar un mensaje por ID usa GET /api/chat/getMessage/:instance; ese endpoint ya no pertenece al módulo de mensajes.

Endpoints disponibles

Método	Ruta	Tipo
POST	`/api/message/text/:instance`	Texto
POST	`/api/message/media/:instance`	Imagen / video / audio / documento
POST	`/api/message/sticker/:instance`	Sticker (WebP)
POST	`/api/message/location/:instance`	Ubicación
POST	`/api/message/contact/:instance`	Contacto (vCard)
POST	`/api/message/reaction/:instance`	Reacción (emoji)
POST	`/api/message/poll/:instance`	Encuesta
POST	`/api/message/carousel/:instance`	Carrusel de tarjetas
POST	`/api/message/button/:instance`	Botones interactivos
POST	`/api/message/list/:instance`	Lista (secciones)
POST	`/api/message/form/:instance`	Formulario (Native Flow)
POST	`/api/message/pix/:instance`	PIX (pago BR)
POST	`/api/message/status/:instance`	Status (historias)

Estructura común

Destinatario (`number` o `to`)

La mayoría de los endpoints aceptan al destinatario en el campo number. Formatos soportados:

Número simple: "5511999999999" (preferido).
JID privado: "5511999999999@s.whatsapp.net".
JID oculto (@lid): "123456789012345@lid", identificador anónimo que WhatsApp usa en grupos/canales cuando el número real no está expuesto.
JID de grupo: "120363406289005073@g.us".
JID de newsletter: "120363422585881117@newsletter".
Status broadcast: "status@broadcast".

Comportamiento de números brasileños

Para números que comienzan con 55 (Brasil), el servicio prueba automáticamente variaciones:

Con 9 (5511999999999)
Sin 9 (551199999999)

Esto soluciona una inconsistencia histórica en los códigos de área antiguos. Si el número no se encuentra en ninguna de las variaciones, el handler retorna 400 Number is not registered on WhatsApp.

Campos opcionales comunes

Campo	Tipo	Aplica a	Descripción
`delay`	int (segundos)	casi todos	Tiempo de espera antes de enviar. Durante el intervalo el servidor envía “escribiendo…” y luego “pausado”.
`replyTo`	string	casi todos	ID del mensaje original a citar. El mensaje debe pertenecer a la misma instancia y existir en la base de datos.
`replyPrivate`	bool	casi todos	Cuando el mensaje citado es de un grupo, redirige la respuesta al chat privado del autor (manteniendo la cita).
`mention`	string[]	text / media	Números (o JIDs) a mencionar. Solo en chats de grupo. Límite de 10 por mensaje.
`mentionAll`	bool	text / media	Menciona a todos los miembros del grupo (`@everyone`). Solo en chats de grupo.
`linkPreview`	bool	text	Cuando es `true`, obtiene metadatos Open Graph de la primera URL y envía como `ExtendedTextMessage` con una tarjeta. Default `false`.
`source`	string	todos	Identificador de origen para trazabilidad (p. ej., `crm`, `n8n`). Default: `"api"`.

delay es en segundos (no milisegundos). Un valor de 3 = 3 s de “escribiendo”.

Las reacciones (/api/message/reaction/:instance) no soportan delay/replyTo/mention, el payload es mínimo (messageId, reaction, participant). Status (/api/message/status/:instance) tampoco usa number/replyTo (siempre va a status@broadcast).

Respuesta estándar (200)

Todos los endpoints de envío retornan el mismo envoltorio 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 opcionales en data: mentions (cuando hay una mención), replyTo (cuando hay una cita), chat.groupName (cuando es un grupo), mediaUrl/mediaMimeType/mediaSize/fileName (cuando es media), vcard (cuando es un contacto). 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

Errores comunes

Status	Mensaje
400	`Instance name is required`
400	`Invalid request body: <detail>`
400	`Number is required`
400	`Message is required` (y 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>`

Envoltorio de error:

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

Límites observados

Recurso	Límite
Texto	~65k caracteres (mensajes > 4096 pueden ser truncados por algunos clientes)
Imagen / video / audio	hasta 16 MB
Documento	hasta 100 MB
Botones	máx. 3 por mensaje
Lista	máx. 10 secciones × 10 filas
Carrusel	máx. 10 tarjetas
Encuesta	2 a 12 opciones

Próximos pasos

Enviar texto

El endpoint más usado, ideal como “Hello World”.

Enviar media

Imagen, video, audio y documento por URL o base64.

Buscar mensaje por ID

Recupera un mensaje específico del historial.

Webhooks

Recibe eventos message.exchange en tiempo real.

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Endpoints disponibles

Estructura común

Destinatario (`number` o `to`)

Comportamiento de números brasileños

Campos opcionales comunes

Respuesta estándar (200)

Errores comunes

Límites observados

Próximos pasos

Enviar texto

Enviar media

Buscar mensaje por ID

Webhooks

​Endpoints disponibles

​Estructura común

​Destinatario (number o to)

​Comportamiento de números brasileños

​Campos opcionales comunes

​Respuesta estándar (200)

​Errores comunes

​Límites observados

​Próximos pasos

Enviar texto

Enviar media

Buscar mensaje por ID

Webhooks

Endpoints disponibles

Estructura común

Destinatario (`number` o `to`)

Comportamiento de números brasileños

Campos opcionales comunes

Respuesta estándar (200)

Errores comunes

Límites observados

Próximos pasos