Bots con WhatsApp Cloud API: configuración, webhooks, plantillas y la ventana de 24 horas

Solo la API oficial

Hay dos formas legítimas de automatizar WhatsApp: la Cloud API alojada por Meta (recomendada) o un Business Solution Provider que la envuelve. Las bibliotecas que automatizan la app de consumo o WhatsApp Web incumplen los términos de servicio y provocan bloqueos de números. Esta guía cubre la Cloud API.

Configuración

1. Crea una app de desarrollador de Meta de tipo Business y añade el producto WhatsApp.
2. Meta te da un número de prueba y un token temporal. Durante las pruebas puedes escribir hasta a cinco números verificados.
3. Para producción, añade tu propio número (no puede estar registrado a la vez en la app de consumo), verifica tu negocio y elige un nombre visible coherente con tu marca.
4. Crea un System User en Business Manager, asígnale la app y la cuenta de WhatsApp, y genera un token permanente con los permisos whatsapp_business_messaging y whatsapp_business_management. Los tokens temporales caducan en menos de un día.

Guarda el phone number ID (no el número en sí) y el WhatsApp Business Account ID: las llamadas a la API los usan.

Enviar un mensaje

Todas las llamadas van a la Graph API. Sustituye vXX.0 por la versión actual de la Graph API que indica la documentación de Meta.

curl -s "https://graph.facebook.com/vXX.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15551112222",
    "type": "text",
    "text": { "body": "Tu pedido #1042 ya fue enviado." }
  }'

Los números van en formato internacional sin + ni espacios. La respuesta incluye un ID de mensaje (wamid...) que puedes relacionar con los webhooks de estado.

La ventana de atención de 24 horas

• Cuando un usuario te escribe se abre una ventana de 24 horas. Dentro de ella puedes enviar mensajes libres: texto, multimedia, botones interactivos y listas.
• Fuera de la ventana solo puedes enviar plantillas preaprobadas. Cada plantilla pertenece a una categoría (marketing, utilidad o autenticación), que determina las reglas de revisión y el precio.
• Los mensajes de plantilla se cobran por mensaje entregado, según categoría y país del destinatario. Consulta la página de precios vigente de Meta antes de planificar una campaña.

{
  "messaging_product": "whatsapp",
  "to": "15551112222",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": { "code": "es" },
    "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "#1042" }] }]
  }
}

Webhooks

Configura en el panel de la app una URL de callback y un verify token de tu elección, y suscríbete al campo messages.

Verificación: Meta envía GET ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... Si el token coincide, responde 200 con el challenge como texto plano.

Notificaciones: Meta envía POST con la cabecera X-Hub-Signature-256: sha256=<hex>, un HMAC-SHA256 del cuerpo crudo usando tu app secret. Verifícala antes de interpretar el JSON (pruébalo en el probador de webhooks).

import hmac, hashlib, os
from fastapi import FastAPI, Request, Response, HTTPException

app = FastAPI()
APP_SECRET = os.environ["META_APP_SECRET"].encode()

@app.get("/whatsapp")
def verify(request: Request):
    q = request.query_params
    if q.get("hub.mode") == "subscribe" and q.get("hub.verify_token") == os.environ["WA_VERIFY_TOKEN"]:
        return Response(q.get("hub.challenge"), media_type="text/plain")
    raise HTTPException(403)

@app.post("/whatsapp")
async def receive(request: Request):
    raw = await request.body()
    expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Hub-Signature-256", "")):
        raise HTTPException(401)
    payload = await request.json()
    for entry in payload.get("entry", []):
        for change in entry.get("changes", []):
            for msg in change["value"].get("messages", []):
                await enqueue(msg)          # deduplica por msg["id"], responde de forma asíncrona
    return {"ok": True}

El mismo endpoint recibe actualizaciones de estado (sent, delivered, read, failed) en value.statuses. Guárdalas si necesitas informes de entrega.

Mensajes interactivos

Dentro de la ventana puedes enviar botones de respuesta (hasta tres) y mensajes de lista (hasta diez filas), mucho más fiables que pedir que escriban palabras exactas. Marca los mensajes entrantes como leídos y muestra el indicador de escritura para señalar que el bot está trabajando.

Consentimiento, calidad y límites

• Debes obtener el consentimiento (opt-in) antes de enviar mensajes iniciados por la empresa, identificar tu negocio y facilitar la baja (respeta "STOP" o un botón).
• Cada número tiene una calificación de calidad basada en bloqueos y reportes. Una calidad baja reduce cuántos usuarios únicos puedes alcanzar al día y puede desactivar plantillas.
• Los números nuevos empiezan con un número limitado de conversaciones iniciadas por la empresa al día; el nivel sube automáticamente si envías mensajes de calidad.
• Ofrece un camino hacia una persona. Los bots que encierran al usuario en bucles generan bloqueos.

Lee la política de mensajería de WhatsApp Business antes de lanzar: algunos sectores y contenidos están prohibidos.