WhatsApp Cloud API
Esta pantalla conecta el WhatsApp Business de tu empresa con FinMova para que puedas enviar cotizaciones por chat (no por link copiado) y ver en tiempo real cuándo el cliente recibió y leyó el mensaje.
Ubicación: Configuración → WhatsApp.
Importante. Cada empresa trae su propio número de WhatsApp Business y su propia App de Meta. FinMova no comparte un número entre clientes — eso te ataría a nuestro límite de tasa y a una sola identidad. El token de acceso se guarda cifrado en nuestra base de datos y nunca se expone al navegador.
Lo que vas a necesitar
- Una cuenta de Meta Business Manager con tu empresa registrada.
- Un número de teléfono verificado para WhatsApp Business (puede ser un fijo o un móvil dedicado; no puede ser uno que ya esté en el WhatsApp app personal).
- Una App de Meta con el producto WhatsApp habilitado.
- Un System User con token permanente (no caduca).
Si nunca lo hiciste, sigue la guía oficial de Meta: developers.facebook.com/docs/whatsapp/cloud-api/get-started (opens in a new tab).
Paso 1 — Conexión
Llena estos cuatro campos en Configuración → WhatsApp:
- Phone Number ID. Lo encuentras en Meta Business Manager → tu App →
WhatsApp → API Setup. Es un número largo (ej.
105954812345678). - WhatsApp Business Account ID (WABA). Mismo sitio, debajo del Phone Number ID.
- Access Token. Genera un System User permanente en Business
Settings → Users → System Users → Generate New Token con el permiso
whatsapp_business_messaging. Pégalo aquí. Se cifra con AES-256-GCM antes de tocar la base de datos. - Webhook Verify Token. Una cadena secreta que tú eliges (mínimo 16 caracteres alfanuméricos). Es la clave que Meta enviará cuando configures el webhook en el paso 3, y FinMova la compara para confirmar que el webhook viene de tu App.
Al guardar, el estado pasa a "Pendiente de verificar".
Paso 2 — Verificar conexión
Pulsa "Verificar conexión". FinMova hace una llamada a la Graph API
de Meta con tu token y, si Meta responde con la metadata del número, el
estado pasa a "Conectado" y se muestra el número en formato
internacional (ej. +18095551234).
Si hay error, verás el mensaje exacto de Meta — los más comunes:
| Error de Meta | Qué significa |
|---|---|
OAuthException (190) | Token expirado o sin el permiso correcto. Genera uno nuevo en Meta. |
Application does not have permission (10) | El System User no tiene whatsapp_business_messaging. |
Object with ID does not exist (100) | Phone Number ID mal copiado o el número aún no está aprobado. |
Paso 3 — Configurar el webhook en Meta
En Meta Business Manager → tu App → WhatsApp → Configuration → Webhooks:
- Callback URL: pega la URL que aparece en la pantalla (botón
"Copiar URL"). El formato es
https://<tu-supabase>.supabase.co/functions/v1/whatsapp-webhook. - Verify Token: pega exactamente la misma cadena que escogiste en el paso 1.
- Pulsa "Verify and Save". Meta hará un GET a la URL; FinMova compara el verify_token y devuelve el challenge si coinciden.
- En Webhook fields, suscríbete a
messages. Eso cubre statuses (entregado/leído) e inbound (mensajes del cliente).
Paso 4 — Habilitar el envío
Cuando el estado esté en "Conectado", aparece el botón "Habilitar". Mientras esté deshabilitado, en cada cotización verás "Conectar WhatsApp" (un CTA hacia esta página); cuando lo habilitas, el botón cambia a "Enviar por WhatsApp".
Puedes deshabilitarlo en cualquier momento sin perder la configuración — útil para pausar mientras renuevas el token o si quieres detener envíos.
Cómo se usa el envío
Desde Cotizaciones → ver detalle → Compartir, verás el botón "Enviar por WhatsApp". Al pulsarlo:
- Se pre-llena el teléfono del cliente (de su ficha) y un mensaje
editable con tres variables:
{{cliente}},{{numero}},{{url}}. - Si el cliente te escribió hace menos de 24h, FinMova manda un texto libre (gratis — ventana de servicio de Meta).
- Si no, FinMova manda un template aprobado por Meta (utility — costo aproximado USD 0.017 en República Dominicana).
- Se registra el envío en el timeline de la cotización (visible en la pestaña Compartir).
- Cuando Meta confirma la entrega y la lectura, el timeline se actualiza automáticamente.
Recordatorios automáticos
Si el cliente no abre la cotización, FinMova manda recordatorios a las 24 horas, 7 días y 14 días del primer envío. Se detienen automáticamente si el cliente lee la cotización, la firma, o la rechaza.
Seguridad
- El access token está cifrado con AES-256-GCM. La misma llave
(
SECRETS_ENCRYPTION_KEY) protege el certificado DGII. - Los webhooks se firman con HMAC-SHA256 usando el App Secret de Meta. Sin firma válida, FinMova rechaza el evento.
- Tu token nunca aparece en logs, ni en la respuesta del servidor, ni en el HTML de la app.
Preguntas frecuentes
¿Puedo usar mi número personal de WhatsApp? No: WhatsApp Cloud API es incompatible con un número ya activo en la app personal de WhatsApp. Necesitas un número dedicado.
¿Cuánto cuesta enviar? Dentro de la ventana de 24h: gratis. Fuera (utility template): ~USD 0.017 por mensaje entregado en República Dominicana. Marketing: ~USD 0.029 (FinMova no usa marketing templates por defecto).
¿Y si rotan el token? Vuelve a esta pantalla, pega el token nuevo y pulsa "Actualizar". El ciphertext anterior se reemplaza en el mismo INSERT.
Última actualización: