Mensajes interactivos con la WhatsApp Cloud API

Matheus Cardoso

La API oficial de WhatsApp — Cloud API de Meta — permite enviar botones, listas y carruseles nativos sin BSP intermediario. Aquí va lo esencial para integrar y el patrón que mantiene el estado de conversación fuera del servidor.

Los 4 tipos de mensaje

Todos usan POST /messages con "messaging_product": "whatsapp". La ventana de 24h comienza desde el último mensaje del usuario.

Texto simpleSoporta *negrita*, _cursiva_, `código`Cualquier hora
BotonesMáx 3 botones, title hasta 20 chars24h
Lista4-10 opciones en secciones con modal24h
Carrusel2-10 cards con imagen + botón24h, ≥ 2 cards
POST https://graph.facebook.com/v23.0/{PHONE_NUMBER_ID}/messages
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

Botones interactivos

El campo reply.id se devuelve exacto en el webhook — úsalo para identificar la acción sin estado en el 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

La forma más limpia de gestionar el flujo de conversación es codificar la acción directamente en el id del botón con prefijos. En el webhook, parsea el prefijo y ejecuta la acción — el botón lleva la intención, el servidor no necesita 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 esencial

  • Credenciales en variables de entorno, nunca en el código
  • Responder al webhook con HTTP 200 inmediatamente — Meta reintenta si no recibe respuesta en 20s
  • Deduplicar por message.id — Meta puede entregar el mismo mensaje más de una vez
  • Envolver sends interactivos en try/catch con fallback a texto simple
  • Carrusel: mínimo 2 cards, todos con el mismo número de botones, imágenes JPEG 1:1

Referencia completa

El archivo cubre todos los payloads con límites exactos, estructura del webhook para cada tipo (incluida la diferencia del carousel quick_reply), estrategia de fallback e imágenes para carrusel.

Descargar referencia (.md)