Saltar al contenido principal
POST
/
api
/
message
/
button
/
:instance
Enviar botones
curl --request POST \
  --url https://api.example.com/api/message/button/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "contentText": "<string>",
  "buttons": [
    {}
  ],
  "headerText": "<string>",
  "footerText": "<string>",
  "mediaUrl": "<string>",
  "mediaType": "<string>",
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "source": "<string>"
}
'

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

​
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

HTTPStatus internoMensaje
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
400invalid_numberInvalid phone number format: <detail>
400invalid_request(motivo de la solicitud inválida detectado por el servicio)
404—Instance not found
500send_failedFailed to send buttons message: <reason>
503disconnectedInstance is not connected to WhatsApp
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "Maximum of 3 buttons allowed" }
}