WhatsApp

Qué vas a lograr: conectar un channel WhatsApp listo para inbound/outbound sin tratarlo como requisito de onboarding.

WhatsApp es un deployment target de producción, no un requisito de onboarding. Construye primero en Sandbox y conecta WhatsApp cuando el cliente ya tenga WABA, método de pago y número listos.

Flujo

1. Crea o selecciona un channel whatsapp en Studio.
2. Ejecuta Embedded Signup desde Studio.
3. Confirma wabaId y phoneNumberId.
4. Tsuzuro intercambia el code por token long-lived, valida el token, suscribe webhooks, registra el número y guarda el token cifrado.
5. Ejecuta readiness:

tsu whatsapp check --channel-id ch_...

Webhooks Meta

Configura en Meta la URL por channel:

https://api.tsuzuro.com/v1/channels/{channelId}/whatsapp/webhook

Tsuzuro valida:

• hub.verify_token en el challenge GET.
• x-hub-signature-256 en POST usando el app secret de la app Meta vinculada al channel.

Mensajes

• Inbound Meta crea/actualiza Threads y Messages neutrales.
• Outbound desde Console/API/agent se entrega con un outbox job durable.
• messages.externalMessageId guarda el wamid.
• Delivery/read receipts generan eventos channel.message.sent, channel.message.delivered, channel.message.read y channel.message.delivery_failed.

Media

Inbound/outbound persisten attachments. El pipeline descarga media de Meta a R2 (tenant-scoped) antes de que Meta lo expire, y usa URLs firmadas de TTL corto en el read path.

Renovación de tokens

Un worker renueva tokens long-lived cercanos a expirar. Si el token no es renovable (p. ej. handoff BYOA de agencia), se emite channel.credential.expiring para que el dueño actúe. tsu whatsapp check refleja el estado.

CI

Tests usan mocks/fixtures de Meta. Nunca uses tokens Meta reales ni números de cliente en CI.

Qué sigue

• BYOA para agencias con app Meta propia.
• Webhook signatures para Stitches (distintos de la firma Meta).