Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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étodoRutaTipo
POST/api/message/text/:instanceTexto
POST/api/message/media/:instanceImagen / video / audio / documento
POST/api/message/sticker/:instanceSticker (WebP)
POST/api/message/location/:instanceUbicación
POST/api/message/contact/:instanceContacto (vCard)
POST/api/message/reaction/:instanceReacción (emoji)
POST/api/message/poll/:instanceEncuesta
POST/api/message/carousel/:instanceCarrusel de tarjetas
POST/api/message/button/:instanceBotones interactivos
POST/api/message/list/:instanceLista (secciones)
POST/api/message/form/:instanceFormulario (Native Flow)
POST/api/message/pix/:instancePIX (pago BR)
POST/api/message/status/:instanceStatus (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

CampoTipoAplica aDescripción
delayint (segundos)casi todosTiempo de espera antes de enviar. Durante el intervalo el servidor envía “escribiendo…” y luego “pausado”.
replyTostringcasi todosID del mensaje original a citar. El mensaje debe pertenecer a la misma instancia y existir en la base de datos.
replyPrivateboolcasi todosCuando el mensaje citado es de un grupo, redirige la respuesta al chat privado del autor (manteniendo la cita).
mentionstring[]text / mediaNúmeros (o JIDs) a mencionar. Solo en chats de grupo. Límite de 10 por mensaje.
mentionAllbooltext / mediaMenciona a todos los miembros del grupo (@everyone). Solo en chats de grupo.
linkPreviewbooltextCuando es true, obtiene metadatos Open Graph de la primera URL y envía como ExtendedTextMessage con una tarjeta. Default false.
sourcestringtodosIdentificador 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

StatusMensaje
400Instance name is required
400Invalid request body: <detail>
400Number is required
400Message is required (y variantes por endpoint: MediaURL is required, Question is required, etc.)
400Mentions are only supported in group chats
400Original message not found (ID: ...)
400Original message does not belong to this instance
404Instance not found
503Instance is not connected to WhatsApp
500Failed to send message: <reason>
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "Number is not registered on WhatsApp" }
}

​
Límites observados

RecursoLímite
Texto~65k caracteres (mensajes > 4096 pueden ser truncados por algunos clientes)
Imagen / video / audiohasta 16 MB
Documentohasta 100 MB
Botonesmáx. 3 por mensaje
Listamáx. 10 secciones × 10 filas
Carruselmáx. 10 tarjetas
Encuesta2 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.