Pular para o conteúdo principal
POST
/
api
/
message
/
button
/
:instance
Enviar Botões
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>"
}
'
Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

​
Descrição

Envia uma mensagem com até 3 botões interativos (limite do WhatsApp). Os botões aceitam quatro tipos: REPLY (padrão, retorna o ID quando clicado), URL (abre link), CALL (disca número) e COPY (copia código). O header pode ser texto (headerText) ou mídia (mediaUrl + mediaType). Se mediaUrl for enviado, mediaType é obrigatório e deve ser maiúsculo: IMAGE, VIDEO ou DOCUMENT. Quando há mídia, headerText é ignorado (a mídia substitui o título).

​
Exemplos

​
3 botões REPLY

O botão REPLY serve para responder uma mensagem específica dentro da conversa: quando o cliente toca, o WhatsApp envia uma resposta citando a mensagem original com o texto do botão (displayText), é isso que aparece no chat. Já no webhook/websocket, o que chega para sua aplicação é o id do botão clicado, permitindo identificar a opção sem depender do texto exibido.
Quando REPLY é misturado com outros tipos (URL, CALL, COPY) na mesma mensagem, o botão REPLY não aparece no WhatsApp Web/Desktop, só fica visível no app do smartphone. O ideal é usar apenas botões REPLY ou apenas combinações de URL/CALL/COPY, sem misturar.
Caso clássico de menu rápido. Cada botão retorna seu id no webhook quando clicado. 
curl -X POST "https://ryzeapi.cloud/api/message/button/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "headerText":  "Atendimento RyzeAPI",
    "contentText": "Como podemos ajudar você hoje?",
    "footerText":  "Disponível 24/7",
    "buttons": [
      { "id": "menu_sales",   "displayText": "Falar com vendas",   "type": "REPLY" },
      { "id": "menu_support", "displayText": "Suporte técnico",    "type": "REPLY" },
      { "id": "menu_billing", "displayText": "Financeiro",         "type": "REPLY" }
    ]
  }'

​
Com header de imagem

Quando mediaUrl está presente, mediaType é obrigatório e deve ser maiúsculo (IMAGE, VIDEO, DOCUMENT). headerText é ignorado neste 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": "Promoção relâmpago: 30% OFF nas assinaturas anuais.",
    "footerText":  "Válido até 23h59 de hoje",
    "mediaUrl":    "https://exemplo.com/img/promo.jpg",
    "mediaType":   "IMAGE",
    "buttons": [
      { "id": "promo_subscribe", "displayText": "Assinar agora", "type": "REPLY" },
      { "id": "promo_details",   "displayText": "Ver detalhes",  "type": "REPLY" }
    ]
  }'

​
Mix de URL + CALL + COPY

Combina três tipos diferentes de botão em uma só mensagem. O id carrega 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":  "Pedido #12345 confirmado",
    "contentText": "Escolha como quer prosseguir:",
    "footerText":  "Cupom válido por 24h",
    "buttons": [
      { "id": "https://loja.exemplo.com/pedido/12345", "displayText": "Acompanhar pedido", "type": "URL"  },
      { "id": "+551130000000",                          "displayText": "Falar com SAC",     "type": "CALL" },
      { "id": "RYZE10",                                 "displayText": "Copiar cupom",      "type": "COPY" }
    ]
  }'

​
Resposta de sucesso

O content retorna o contentText enviado, e o messageType é fixo em buttons. A definição dos botões em si não vem na resposta, guarde o messageId para correlacionar os cliques que chegam via webhook.
200 OK
{
  "success": true,
  "message": "Buttons message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1F5F5",
    "direction":   "sent",
    "messageType": "buttons",
    "content":     "Como podemos ajudar você hoje?",
    "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"
    }
  }
}
Quando o usuário toca em um botão REPLY, a resposta chega como mensagem de texto contendo o id do botão clicado, capture isso pelo webhook para encadear o fluxo.

​
Parâmetros de rota

​
instance
string
obrigatório
Nome da instância (ex.: $Instance_Name).

​
Headers

​
token
string
obrigatório
TokenAccount ou TokenInstance.
​
Content-Type
string
obrigatório
application/json

​
Request body

​
number
string
obrigatório
Destino: telefone (5511999999999) ou JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
contentText
string
obrigatório
Texto principal do corpo da mensagem (entre header e botões).
​
buttons
ButtonOption[]
obrigatório
Lista de botões. Mínimo 1, máximo 3 (limite do WhatsApp). Cada botão tem:
  • id (string, obrigatório), semântica varia por type: REPLY retorna esse ID; URL abre essa URL; CALL disca esse número; COPY copia esse código.
  • displayText (string, obrigatório), texto visível no botão.
  • type (string), REPLY (padrão), URL, CALL ou COPY. Outro valor retorna 400 Button N: Type must be one of: REPLY, URL, CALL, COPY.
​
headerText
string
Título exibido no topo da mensagem. Ignorado se mediaUrl for fornecido (a mídia substitui o header).
​
footerText
string
Texto opcional exibido abaixo dos botões.
​
mediaUrl
string
URL de uma mídia (imagem, vídeo ou documento) para usar como header. Quando enviado, mediaType torna-se obrigatório.
​
mediaType
string
Tipo da mídia em mediaUrl. Obrigatório se mediaUrl estiver presente. Aceita apenas IMAGE, VIDEO ou DOCUMENT (maiúsculo). Outro valor retorna 400 MediaType must be one of: IMAGE, VIDEO, DOCUMENT.
​
delay
int
padrão:"0"
Tempo em segundos para aguardar antes de enviar. Durante o intervalo, o servidor envia o indicador de “digitando…” e dispara o “paused” antes do envio real.
​
replyTo
string
ID da mensagem a ser citada (reply). A mensagem original precisa pertencer à mesma instância e ter sido salva no banco.
​
replyPrivate
boolean
padrão:"false"
Quando true e replyTo aponta para uma mensagem originária de um grupo, a mensagem é redirecionada para o privado do autor original (mantendo a citação).
​
source
string
padrão:"api"
Identificador de origem para rastreabilidade (ex.: crm, bot-suporte, n8n). Salvo no registro da mensagem e propagado para webhooks.

​
Notas

  • delay é em segundos (não milissegundos).
  • O WhatsApp aceita no máximo 3 botões por mensagem. Quatro ou mais retornam 400 Maximum of 3 buttons allowed.
  • Se mediaUrl é enviado, headerText é silenciosamente ignorado.
  • mediaType é normalizado para maiúsculo internamente, envie sempre IMAGE, VIDEO ou DOCUMENT.
  • Para botões URL, garanta que o link comece com https:// para evitar bloqueio pelo cliente.
  • Para botões CALL, use formato internacional (+5511...).
  • Aparelhos antigos podem cair em fallback de texto e exibir os botões como mensagem comum.

​
Erros

HTTPStatus internoMensagem
400,Instance name is required
400,Invalid request body: <detalhe>
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: <detalhe>
400invalid_request(motivo do request inválido detectado pelo serviço)
404,Instance not found
500send_failedFailed to send buttons message: <reason>
503disconnectedInstance is not connected to WhatsApp
Envelope de erro: 
{
  "success": false,
  "error": { "message": "Maximum of 3 buttons allowed" }
}