Enviar Botões

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" }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/button/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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" }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/button/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "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"}
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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" }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/button/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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" }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/button/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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" }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/button/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "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"}
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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" }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/button/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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" }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/button/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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" }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/button/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "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"}
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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" }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/button/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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 no webhook com message.type igual a template_button_reply e o id do botão clicado em message.content (e também em message.interactive.selectedButtonId). Capture isso pelo webhook para encadear o fluxo.

Parâmetros de rota

string

obrigatório

Nome da instância (ex.: $Instance_Name).

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

string

obrigatório

Destino: telefone (5511999999999) ou JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

string

obrigatório

Texto principal do corpo da mensagem (entre header e botões).

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.

string

Título exibido no topo da mensagem. Ignorado se mediaUrl for fornecido (a mídia substitui o header).

string

Texto opcional exibido abaixo dos botões.

string

URL de uma mídia (imagem, vídeo ou documento) para usar como header. Quando enviado, mediaType torna-se obrigatório.

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.

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.

string

ID da mensagem a ser citada (reply). A mensagem original precisa pertencer à mesma instância e ter sido salva no banco.

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

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

HTTP	Status interno	Mensagem
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`
400	`invalid_number`	`Invalid phone number format: <detalhe>`
400	`invalid_request`	(motivo do request inválido detectado pelo serviço)
404	,	`Instance not found`
500	`send_failed`	`Failed to send buttons message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envelope de erro:

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

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Exemplos

3 botões REPLY

Com header de imagem

Mix de URL + CALL + COPY

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros

​Descrição

​Exemplos

​3 botões REPLY

​Com header de imagem

​Mix de URL + CALL + COPY

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

Descrição

Exemplos

3 botões REPLY

Com header de imagem

Mix de URL + CALL + COPY

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros