Enviar botones - RyzeAPI

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

Descripción

Envía un mensaje con hasta 3 botones interactivos (límite de WhatsApp). Los botones aceptan cuatro tipos: REPLY (default, retorna el ID al hacer clic), URL (abre un enlace), CALL (marca un número) y COPY (copia un código). El encabezado puede ser texto (headerText) o media (mediaUrl + mediaType). Si se envía mediaUrl, mediaType es requerido y debe estar en mayúsculas: IMAGE, VIDEO o DOCUMENT. Cuando hay media presente, headerText se ignora (la media reemplaza al título).

Ejemplos

3 botones REPLY

El botón REPLY se usa para responder a un mensaje específico dentro de la conversación: cuando el cliente lo toca, WhatsApp envía una respuesta citando el mensaje original con el texto del botón (displayText), eso es lo que aparece en el chat. En el webhook/websocket, lo que llega a tu aplicación es el id del botón clicado, permitiéndote identificar la opción sin depender del texto mostrado.

Cuando REPLY se mezcla con otros tipos (URL, CALL, COPY) en el mismo mensaje, el botón REPLY no aparece en WhatsApp Web/Desktop, solo es visible en la app del smartphone. Lo ideal es usar solo botones REPLY o solo combinaciones de URL/CALL/COPY, sin mezclar.

Caso clásico de un menú rápido. Cada botón retorna su id en el webhook al hacer clic.

curl -X POST "https://ryzeapi.cloud/api/message/button/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "headerText":  "RyzeAPI Support",
    "contentText": "How can we help you today?",
    "footerText":  "Available 24/7",
    "buttons": [
      { "id": "menu_sales",   "displayText": "Talk to sales",    "type": "REPLY" },
      { "id": "menu_support", "displayText": "Technical support", "type": "REPLY" },
      { "id": "menu_billing", "displayText": "Billing",          "type": "REPLY" }
    ]
  }'

Con encabezado de imagen

Cuando hay mediaUrl presente, mediaType es requerido y debe estar en mayúsculas (IMAGE, VIDEO, DOCUMENT). headerText se ignora en ese caso.

curl -X POST "https://ryzeapi.cloud/api/message/button/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "contentText": "Flash sale: 30% OFF on annual subscriptions.",
    "footerText":  "Valid until 11:59pm today",
    "mediaUrl":    "https://example.com/img/promo.jpg",
    "mediaType":   "IMAGE",
    "buttons": [
      { "id": "promo_subscribe", "displayText": "Subscribe now", "type": "REPLY" },
      { "id": "promo_details",   "displayText": "See details",   "type": "REPLY" }
    ]
  }'

Mezcla de URL + CALL + COPY

Combina tres tipos diferentes de botones en un único mensaje. El id transporta valores semánticos distintos por tipo.

curl -X POST "https://ryzeapi.cloud/api/message/button/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "headerText":  "Order #12345 confirmed",
    "contentText": "Choose how you want to proceed:",
    "footerText":  "Coupon valid for 24h",
    "buttons": [
      { "id": "https://store.example.com/order/12345", "displayText": "Track order",   "type": "URL"  },
      { "id": "+551130000000",                          "displayText": "Talk to support", "type": "CALL" },
      { "id": "RYZE10",                                 "displayText": "Copy coupon",   "type": "COPY" }
    ]
  }'

Respuesta exitosa

El content retorna el contentText que enviaste, y messageType es fijo en buttons. Las definiciones de los botones en sí no regresan en la respuesta, guarda el messageId para correlacionar los clics que llegan vía webhook.

200 OK

{
  "success": true,
  "message": "Buttons message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1F5F5",
    "direction":   "sent",
    "messageType": "buttons",
    "content":     "How can we help you today?",
    "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"
    }
  }
}

Cuando el usuario toca un botón REPLY, la respuesta llega como un mensaje de texto que contiene el id del botón clicado, captúralo vía webhook para encadenar el flujo.

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).

contentText

string

requerido

Texto principal del cuerpo del mensaje (entre el encabezado y los botones).

buttons

ButtonOption[]

requerido

Lista de botones. Mínimo 1, máximo 3 (límite de WhatsApp). Cada botón tiene:

id (string, requerido), la semántica varía según type: REPLY retorna este ID; URL abre esta URL; CALL marca este número; COPY copia este código.
displayText (string, requerido), texto visible en el botón.
type (string), REPLY (default), URL, CALL o COPY. Cualquier otro valor retorna 400 Button N: Type must be one of: REPLY, URL, CALL, COPY.

headerText

string

Título mostrado en la parte superior del mensaje. Ignorado si se proporciona mediaUrl (la media reemplaza al encabezado).

footerText

string

Texto opcional mostrado debajo de los botones.

mediaUrl

string

URL de un archivo de media (imagen, video o documento) para usar como encabezado. Cuando se envía, mediaType se vuelve requerido.

mediaType

string

Tipo de la media en mediaUrl. Requerido si mediaUrl está presente. Acepta solo IMAGE, VIDEO o DOCUMENT (mayúsculas). Cualquier otro valor retorna 400 MediaType must be one of: IMAGE, VIDEO, DOCUMENT.

delay

int

predeterminado:"0"

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

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.

replyPrivate

boolean

predeterminado:"false"

Cuando es true y replyTo apunta a un mensaje originado en un grupo, el mensaje se redirige al chat privado del autor original (manteniendo la cita).

source

string

predeterminado:"api"

Identificador de origen para trazabilidad (p. ej., crm, bot-suporte, n8n). Guardado en el registro del mensaje y propagado a los webhooks.

Notas

delay es en segundos (no milisegundos).
WhatsApp acepta hasta 3 botones por mensaje. Cuatro o más retornan 400 Maximum of 3 buttons allowed.
Si se envía mediaUrl, headerText se ignora silenciosamente.
mediaType se normaliza a mayúsculas internamente, envía siempre IMAGE, VIDEO o DOCUMENT.
Para botones URL, asegúrate de que el enlace comience con https:// para evitar ser bloqueado por el cliente.
Para botones CALL, usa el formato internacional (+5511...).
Los dispositivos antiguos pueden caer a texto y mostrar los botones como un mensaje regular.

Errores

HTTP	Status interno	Mensaje
400	,	`Instance name is required`
400	,	`Invalid request body: <detail>`
400	,	`Number is required`
400	,	`ContentText is required`
400	,	`At least one button is required`
400	,	`Maximum of 3 buttons allowed`
400	,	`MediaType is required when MediaURL is provided`
400	,	`MediaType must be one of: IMAGE, VIDEO, DOCUMENT`
400	,	`Button N: ID is required`
400	,	`Button N: DisplayText is required`
400	,	`Button N: Type must be one of: REPLY, URL, CALL, COPY`
400	`invalid_number`	`Invalid phone number format: <detail>`
400	`invalid_request`	(motivo de la solicitud inválida detectado por el servicio)
404	,	`Instance not found`
500	`send_failed`	`Failed to send buttons message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envoltorio de error:

{
  "success": false,
  "error": { "message": "Maximum of 3 buttons allowed" }
}

​Descripción

​Ejemplos

​3 botones REPLY

​Con encabezado de imagen

​Mezcla de URL + CALL + COPY

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

3 botones REPLY

Con encabezado de imagen

Mezcla de URL + CALL + COPY

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores