# Botões de resposta WhatsApp

Botões de resposta colocam até três opções clicáveis abaixo de uma mensagem WhatsApp, para que o destinatário responda com um toque em vez de texto livre. Use-os para uma decisão rápida, como confirmar ou cancelar uma reserva. Para mais de três opções, use [menus de lista](/docs/guides/whatsapp/message-types/interactive/list-menus).

## Enviar botões de resposta

Defina `interactive.type` como `button`, com um `body_text` e de um a três `buttons`, cada um sendo um `quick_reply`:

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "button",
    body_text: "Your gardening workshop is scheduled for 9am tomorrow.",
    buttons: [{ type: "quick_reply", quick_reply: { slug: "change-booking", text: "Change" } }],
  },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/message-types/interactive/reply-buttons.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/message-types/interactive/reply-buttons.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/message-types/interactive/reply-buttons.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/message-types/interactive/reply-buttons.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/message-types/interactive/reply-buttons.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/message-types/interactive/reply-buttons.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/message-types/interactive/reply-buttons.curl.md)

`from` é obrigatório em toda mensagem de serviço: um número que o seu espaço de trabalho possui, não um gerenciado por Bird. A estrutura completa adiciona um cabeçalho opcional, rodapé, uma citação de uma mensagem anterior e um segundo botão:

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "button",
    "header": {
      "type": "image",
      "url": "https://cdn.example.com/banners/workshop.png"
    },
    "body_text": "Your gardening workshop is scheduled for 9am tomorrow.",
    "footer_text": "Lucky Shrub, your gateway to succulents",
    "buttons": [
      { "type": "quick_reply", "quick_reply": { "slug": "change-booking", "text": "Change" } },
      { "type": "quick_reply", "quick_reply": { "slug": "cancel-booking", "text": "Cancel" } }
    ]
  },
  "tags": [{ "name": "category", "value": "booking" }],
  "metadata": { "order_id": "A-1" }
}
```

`in_reply_to_message_id` cita uma mensagem anterior na mesma conversa. Consulte no hub [citar uma mensagem para correlacionar uma resposta](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply) para saber como a resolução funciona e o que ela pode perder.

Esse tipo envia apenas botões `quick_reply`. Um botão `cta_url` pertence a um `interactive.type` separado e não pode aparecer junto com `buttons`; consulte a seção [botões](/docs/guides/whatsapp/message-types/interactive#buttons) do hub para a estrutura compartilhada de botão.

## Cabeçalhos e rodapés

O cabeçalho é opcional e tem uma de quatro formas:

```text
"header": { "type": "text",     "text": "New workshop dates" }
"header": { "type": "image",    "url": "https://cdn.example.com/a.png" }
"header": { "type": "video",    "url": "https://cdn.example.com/a.mp4" }
"header": { "type": "document", "url": "https://cdn.example.com/a.pdf" }
```

Um cabeçalho de mídia (`image`, `video` ou `document`) carrega seu arquivo como uma URL `https` pública que WhatsApp busca no momento do envio, em vez de um handle de mídia enviado por upload. `footer_text` é opcional e adiciona uma linha abaixo dos botões.

## Limites

| Campo                      | Limite                                            |
| -------------------------- | ------------------------------------------------- |
| `buttons`                  | 1 a 3 entradas, cada uma sendo um `quick_reply`   |
| `quick_reply.slug`         | obrigatório, 1 a 256 caracteres                   |
| `quick_reply.text` (label) | obrigatório, 1 a 20 caracteres, único na mensagem |
| `body_text`                | obrigatório, 1 a 1.024 caracteres                 |
| `footer_text`              | opcional, 1 a 60 caracteres                       |
| `header.text`              | 1 a 60 caracteres                                 |

Bird verifica se os labels dos botões (`quick_reply.text`) são únicos, mas não verifica se os valores de `slug` são únicos, mesmo que cada slug sirva para identificar um botão. Dois botões que compartilham um slug são enviados e entregues normalmente, e suas respostas voltam indistinguíveis.

## Lendo a resposta

Um toque chega como sua própria mensagem de entrada, contendo `interactive_reply`:

```json
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive_reply": {
    "type": "button",
    "button": {
      "slug": "cancel-booking",
      "text": "Cancel"
    }
  },
  "created_at": "2026-08-25T09:04:11Z"
}
```

O `slug` que você definiu no envio volta exatamente igual, então você pode usá-lo diretamente para ramificar a lógica sem uma tabela de consulta. Você vê essa resposta pela lista de mensagens ou por `GET /v1/whatsapp/messages/{id}`; consulte no hub [lendo uma resposta](/docs/guides/whatsapp/message-types/interactive#reading-a-reply) para o caminho completo.

## Limites e casos especiais

- **A janela de atendimento ao cliente precisa estar aberta.** Botões de resposta são uma mensagem de serviço, entregável apenas dentro de uma janela aberta; consulte no hub [janela de atendimento ao cliente](/docs/guides/whatsapp/message-types#the-customer-service-window). A verificação da janela falha de forma permissiva, então um `202` não é prova de que a janela estava de fato aberta quando o envio é disparado.
- **`from` deve ser um número que o seu espaço de trabalho possui.** Omiti-lo, ou informar um número que não é um remetente conectado, é rejeitado antes de o envio ser criado.
- **Os labels devem ser únicos, ou o envio é recusado.** Dois botões com o mesmo `quick_reply.text` falham com `422` [`E15056`](/docs/api/errors/E15056) `WhatsAppInteractiveDuplicateLabel`, porque a Meta rejeitaria a duplicata depois que o envio já tivesse sido aceito e cobrado.
- **O label é o que o destinatário vê; o slug nunca é.** Colocar texto voltado ao usuário em `slug` é um no-op silencioso, já que apenas `text` é renderizado no chat.
- **Uma URL de cabeçalho de mídia que WhatsApp não consegue buscar falha após o envio ser aceito.** Bird não valida a `url` do cabeçalho da mesma forma que valida a URL de uma mensagem de mídia, então uma URL `http://` ou que retorna um erro passa pela solicitação e depois falha de forma assíncrona, com `media_rejected` no `last_error` da mensagem.
- **Enviar os próprios nomes de campo da Meta falha a solicitação.** Esse tipo rejeita propriedades desconhecidas diretamente, então JSON copiado da referência Cloud API da Meta, como um objeto `body` ou um wrapper `action.buttons`, precisa ser reestruturado nos campos planos de Bird primeiro.

Uma citação que não é resolvida falha a solicitação antes de qualquer coisa ser criada ou cobrada: `404` [`E15071`](/docs/api/errors/E15071) quando o id não corresponde a nenhuma mensagem que esse espaço de trabalho possui, `422` [`E15072`](/docs/api/errors/E15072) quando corresponde a uma que não pode ser citada. Para os erros que qualquer envio WhatsApp pode encontrar, uma janela fechada, um remetente ausente ou inválido, ou um destinatário inválido, consulte no hub [erros](/docs/guides/whatsapp/message-types/interactive#errors) e [Enviando mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp).

## Próximos passos

- [Mensagens interativas WhatsApp](/docs/guides/whatsapp/message-types/interactive): o que todos os seis tipos interativos têm em comum
- [Menus de lista](/docs/guides/whatsapp/message-types/interactive/list-menus): para mais de três opções
- [Enviando mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp): a estrutura da solicitação, o modelo `202` e tentativas seguras de reenvio

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)