Mensagens interativas com a WhatsApp Cloud API

Matheus Cardoso·8 de maio de 2026

A API oficial do WhatsApp — Cloud API da Meta — permite enviar botões, listas e carrosséis nativos sem BSP intermediário. Aqui vai o essencial para integrar e o padrão que mantém o estado da conversa fora do servidor.

Os 4 tipos de mensagem

Todos usam POST /messages com "messaging_product": "whatsapp". A janela de 24h conta a partir da última mensagem enviada pelo usuário.

POST https://graph.facebook.com/v23.0/{PHONE_NUMBER_ID}/messages
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

Botões interativos

O campo reply.id é retornado exato no webhook — use-o para identificar a ação sem estado no servidor.

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": { "text": "Como prefere receber o pedido?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "delivery", "title": "🛵 Entrega" } },
        { "type": "reply", "reply": { "id": "pickup",   "title": "🏠 Retirada" } }
      ]
    }
  }
}

IDs como máquina de estado

A forma mais limpa de gerenciar fluxo de conversa é codificar a ação direto no id do botão com prefixos. No webhook, parse o prefixo e execute a ação — o botão carrega a intenção, o servidor não precisa guardar nada.

restaurant:<uuid>    → selecionar restaurante
category:<uuid>      → filtrar cardápio
item:<uuid>          → adicionar ao carrinho
cart:view            → mostrar carrinho
cart:checkout        → iniciar checkout
cart:remove:<n>      → remover item n
confirm:yes          → confirmar ação
order:<uuid>         → status do pedido

Checklist essencial

• Credenciais em variáveis de ambiente, nunca no código
• Responder ao webhook com HTTP 200 imediatamente — a Meta retenta se não receber em 20s
• Deduplicar por message.id — a Meta pode entregar a mesma mensagem mais de uma vez
• Envolver sends interativos em try/catch com fallback para texto simples
• Carrossel: mínimo 2 cards, todos com o mesmo número de botões, imagens JPEG 1:1

Referência completa

O arquivo cobre todos os payloads com limites exatos, estrutura do webhook para cada tipo (incluindo a diferença do carousel quick_reply), estratégia de fallback e regras de imagem para carrossel.