Enviar texto - RyzeAPI

Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

Descripción

Envía un mensaje de texto a un contacto 1 a 1, grupo (@g.us) o canal (@newsletter). Soporta replyTo (cita por ID), replyPrivate (responder privadamente a un mensaje de grupo), mention / mentionAll (solo chats de grupo), linkPreview y delay (en segundos) para simular tipeo real. Es el endpoint más usado y sirve como “Hello World” para validar que la instancia está conectada.

Ejemplos

Mínimo

Envía un mensaje de texto con el payload mínimo (number + message). Sin delay, sin preview, sin citar, útil como “Hello World” para validar que la instancia está conectada.

curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":  "5511999999999",
    "message": "Hello! This is a test of RyzeAPI."
  }'

Con delay y vista previa de enlace

Envía un indicador de “escribiendo…” durante 3 segundos y luego envía el mensaje con una vista previa de la URL detectada.

curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "message":     "Check this out: https://ryzeapi.cloud",
    "delay":       3,
    "linkPreview": true
  }'

Como respuesta

Cita un mensaje existente (replyTo recibe el messageId del original). El mensaje original debe pertenecer a la misma instancia y haber sido guardado en la base de datos (cualquier mensaje que fluya por webhook/envío se guarda automáticamente).

curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":  "5511999999999",
    "message": "Yes, confirmed!",
    "replyTo": "3EB08FCF27E532F1B0F5"
  }'

Como respuesta privada (desde un grupo)

Cuando alguien envía un mensaje en un grupo y quieres responderle privadamente a esa persona (sin enviar la respuesta de vuelta al grupo), usa replyPrivate: true. El number debe apuntar al JID del grupo donde se envió el mensaje original, el servidor extrae al autor original y redirige la respuesta a su chat privado, manteniendo la cita.

curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":       "120363406289005073@g.us",
    "message":      "Replying to you privately so we don't clutter the group.",
    "replyTo":      "3EB08FCF27E532F1B0F5",
    "replyPrivate": true
  }'

Con menciones a miembros (grupo)

Agrega menciones visibles con @5511... en el cuerpo del mensaje y lista los números en el array mention. El texto y el array deben ser consistentes, WhatsApp solo convierte en enlace clicable lo que está en mention.

curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":  "120363406289005073@g.us",
    "message": "Heads up @5511888888888 and @5511777777777, meeting at 2pm.",
    "mention": ["5511888888888", "5511777777777"]
  }'

Mención oculta (grupo)

Notifica a todos los miembros del grupo sin listar los @ en el texto, usando mentionAll: true. El texto mostrado se mantiene limpio, pero los participantes reciben la notificación de mención. Útil para anuncios silenciosos. Para mencionar a personas específicas de forma oculta, usa simplemente mention: ["..."] sin colocar @número en el texto, también recibirán la notificación sin aparecer etiquetadas.

curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":     "120363406289005073@g.us",
    "message":    "General notice: meeting confirmed for tomorrow at 2pm.",
    "mentionAll": true
  }'

Respuesta exitosa

La respuesta incluye el messageId (úsalo en replyTo para citar este mensaje en envíos futuros), direction: "outgoing" y los marcadores de chat/sender. Los campos mentions y replyTo solo aparecen cuando aplican, y chat.groupName se incluye en mensajes de grupo.

200 OK

{
  "success": true,
  "message": "Message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "outgoing",
    "messageType": "text",
    "content":     "Hello! This is a test of RyzeAPI.",
    "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"
    },
    "mentions": {
      "mentionedUsers": ["5511888888888"],
      "mentionAll":     false,
      "totalMentions":  1
    },
    "replyTo": {
      "messageId": "3EB08FCF27E532F1A1A1",
      "content":   "Are we good for tomorrow?"
    }
  }
}

Parámetros de ruta

instance

string

requerido

Nombre de la instancia (p. ej., $Instance_Name).

Cabeceras

token

string

requerido

TokenAccount o TokenInstance.

Content-Type

string

requerido

application/json

Cuerpo de la solicitud

number

string

requerido

Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

message

string

requerido

Texto del cuerpo. No puede estar vacío.

delay

int

predeterminado:"0"

Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor envía el indicador “escribiendo…” al destinatario y dispara “pausado” antes del envío real.

linkPreview

boolean

predeterminado:"false"

Cuando es true, el servidor extrae la primera URL de message, obtiene los metadatos Open Graph (título, descripción, miniatura) y envía el mensaje como ExtendedTextMessage con la tarjeta de vista previa incrustada. Cuando es false u omitido, la URL aparece como texto plano.

replyTo

string

ID del mensaje a citar (respuesta). El mensaje original debe pertenecer a la misma instancia y haber sido guardado en la base de datos. Posibles errores: reply_message_not_found, reply_message_instance_mismatch.

replyPrivate

boolean

predeterminado:"false"

Cuando es true y replyTo apunta a un mensaje originado en un grupo, la respuesta se redirige al chat privado del autor original (manteniendo la cita). Útil para responder preguntas individualmente sin saturar el grupo. Ignorado si el mensaje original no es de un grupo.

mention

string[]

Lista de números (o JIDs) a mencionar. Solo en chats de grupo (@g.us). Límite de 10 menciones por mensaje; los números excedentes se ignoran con una advertencia. Para aparecer como enlace clicable, incluye @5511... en message. Sin eso, se vuelven menciones ocultas (solo notifican).

mentionAll

boolean

predeterminado:"false"

Cuando es true, menciona a todos los miembros del grupo (excepto la propia instancia). Equivalente a @everyone. El servidor consulta la lista de participantes e inyecta cada JID en el MentionedJID del contexto, sin alterar el texto mostrado. Solo en chats de grupo.

source

string

predeterminado:"api"

Identificador de origen para trazabilidad (p. ej., crm, bot-suporte, n8n). Guardado en el registro del mensaje en la base de datos y propagado a los webhooks. Cuando se omite, el default es "api".

Notas

delay es en segundos (a diferencia de muchas APIs que usan ms). Un valor de 3 = 3 segundos de “escribiendo”.
En grupos, el texto con @5511... solo no se vuelve clicable, es el array mention lo que WhatsApp procesa. Mantenlos consistentes.
mention y mentionAll son exclusivos de grupos. Si se envían a un DM/canal, la respuesta es 400 Mentions are only supported in group chats.
Para números BR (que comienzan con 55), el servicio prueba automáticamente variaciones con y sin el 9° dígito, evitando la inconsistencia histórica en códigos de área antiguos.
linkPreview requiere que el servidor pueda obtener los metadatos Open Graph de la URL; los sitios con bloqueo de bots pueden caer a texto plano sin error visible.
Los mensajes enviados vía replyPrivate: true aparecen en el chat privado del destinatario con la tarjeta del mensaje de grupo citado, pueden ver de qué conversación vino.

Errores

HTTP	Status interno	Mensaje
400	,	`Instance name is required`
400	,	`Invalid request body: <detail>`
400	,	`Number is required`
400	,	`Message is required`
400	`invalid_number`	`Invalid phone number format: <detail>`
400	`mentions_not_supported`	`Mentions are only supported in group chats`
400	`reply_message_not_found`	`Original message not found (ID: ...)`
400	`reply_message_instance_mismatch`	`Original message does not belong to this instance`
400	`private_reply_failed`	(motivo del error de redirección privada)
404	,	`Instance not found`
500	`send_failed`	`Failed to send message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envoltorio de error:

{
  "success": false,
  "error": { "message": "Message is required" }
}

​Descripción

​Ejemplos

​Mínimo

​Con delay y vista previa de enlace

​Como respuesta

​Como respuesta privada (desde un grupo)

​Con menciones a miembros (grupo)

​Mención oculta (grupo)

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Mínimo

Con delay y vista previa de enlace

Como respuesta

Como respuesta privada (desde un grupo)

Con menciones a miembros (grupo)

Mención oculta (grupo)

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores