WhatsApp Business API

---
name: whatsapp-business-api
description: mensajes operativos por el canal que tus clientes en LATAM sí abren.
---

# WhatsApp Business API

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
envíes o recibas mensajes con la plataforma oficial de WhatsApp Business.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El negocio confirma pedidos, citas, entregas o pagos por WhatsApp.
- Un equipo atiende conversaciones iniciadas por clientes desde un mismo número.
- Necesitas plantillas aprobadas, estados de entrega o respuestas automáticas.
- WhatsApp es parte del flujo principal y un enlace `wa.me` ya no basta.

Si solo necesitas abrir una conversación manual, usa un enlace `wa.me` con texto
precargado. No conectes la API, verificación comercial y webhooks para un botón.

## Cómo armarla

Usa **WhatsApp Cloud API de Meta** directamente. Agrega un BSP oficial solo si necesitas
onboarding administrado de muchos negocios, soporte contractual o una bandeja que no vas
a construir.

1. Crea la app de Meta, la cuenta de WhatsApp Business y un número real. Completa la
   verificación que Meta solicite antes de prometer una fecha de salida.
2. Guarda `phoneNumberId`, `wabaId` y el token de sistema cifrado en el servidor. Nunca
   expongas el token en el navegador ni uses el token temporal del tutorial en producción.
3. Normaliza destinatarios a E.164 y conserva por separado el número que escribió el
   usuario. No inventes códigos de país ni corrijas un número ambiguo en silencio.
4. Registra el consentimiento con fecha, origen y finalidad. Separa soporte, avisos
   operativos y marketing; una aceptación para un pedido no autoriza campañas eternas.
5. Crea pocas plantillas, con variables nombradas y ejemplos reales. Envía texto libre
   solo dentro de la ventana de atención vigente de Meta; fuera de ella usa una plantilla
   aprobada para la categoría correcta.
6. Verifica el challenge inicial y la firma de cada webhook. Responde rápido, encola el
   evento y procesa de forma idempotente por el id de mensaje.
7. Guarda estados `queued`, `sent`, `delivered`, `read` y `failed`, junto con el código
   del proveedor. La respuesta 200 al envío no significa que el teléfono lo recibió.
8. Implementa derivación a una persona: pausa el bot, muestra el contexto y deja una
   marca inequívoca de quién controla la conversación.

## En qué te vas a trabar

- **La aprobación no es instantánea.** El negocio, el nombre visible, el número y las
  plantillas pueden requerir revisión; empieza con el número de prueba, pero no confundas
  esa prueba con producción.
- **El costo cambia por mercado y tipo de plantilla.** Meta y un BSP pueden cobrar por
  separado. Consulta la tarifa vigente para cada país objetivo y registra costo por
  mensaje entregado antes de fijar el precio de tu plan.
- **Los webhooks llegan repetidos, tarde o fuera de orden.** Modela estados monotónicos y
  no dispares dos pedidos porque recibiste dos veces el mismo mensaje.
- **La operación humana sigue existiendo.** Automatizar soporte sin horario, cola y
  responsable solo mueve el caos a otro canal.

## Qué NO hacer

- No automatices WhatsApp Web ni uses librerías que simulan un teléfono. Arriesgas el
  número del negocio y construyes sobre un protocolo no soportado.
- No compres listas ni envíes marketing sin consentimiento y baja efectiva.
- No hagas depender un pedido solo de que el mensaje muestre `sent`.
- No metas reglas comerciales dentro del texto de una plantilla; guarda la lógica en
  código y manda a la plantilla únicamente los valores finales.

## Checklist

- [ ] El número de producción y el nombre visible están aprobados.
- [ ] Los tokens viven cifrados en el servidor y tienen rotación documentada.
- [ ] Cada destinatario tiene consentimiento trazable y mecanismo de baja.
- [ ] Los webhooks validan firma, toleran duplicados y conservan el payload crudo.
- [ ] Una plantilla aprobada funciona fuera de la ventana de atención.
- [ ] Los estados de entrega y los fallos aparecen en una vista operativa.
- [ ] Una conversación puede pasar del bot a una persona sin respuestas dobles.