Conectar WhatsApp Business API

Actualizado: 2026-03-01 (version runbook por casos)

Esta guia es un runbook para que cualquier cliente pueda pasar de cero a "bot activo" en Zyntia usando BYON (Bring Your Own Number).

1. Resultado esperado

Al terminar, debes tener:

1. Cliente registrado en Zyntia.
2. Bot creado en Zyntia.
3. Canal WhatsApp conectado.
4. Webhook verificado en Meta.
5. Prueba real de mensaje entrante y saliente en estado OK.

2. Requisitos minimos

Antes de iniciar cualquier caso, confirma:

1. Cuenta personal de Facebook del cliente.
2. Acceso admin al negocio en Meta (Business Manager).
3. Acceso OTP del numero (SMS o llamada).
4. Cuenta del cliente en Zyntia y permiso para editar su bot.

3. Flujo base (aplica a todos los casos)

Paso 1: Registro y bot en Zyntia

1. Registrar cliente en Zyntia.
2. Ingresar al dashboard.
3. Crear bot nuevo o seleccionar bot existente.
4. Ir a Canales > WhatsApp.

Paso 2: Preparar app en Meta

1. Ir a developers.facebook.com/apps.
2. Crear app con caso de uso WhatsApp.
3. En WhatsApp > API Setup, ubicar Phone Number ID.

Paso 3: Obtener credenciales correctas

1. PHONE NUMBER ID (desde API Setup).
2. SYSTEM USER ACCESS TOKEN permanente (no temporal).
3. META APP SECRET (desde Configuracion de la app > Basica).

Paso 4: Conectar en Zyntia

1. Pegar credenciales en Canales > WhatsApp.
2. Click en Connect WhatsApp.
3. Copiar Callback URL y Verify Token generados.

Paso 5: Configurar webhook en Meta

1. Ir a WhatsApp > Configuration > Webhook > Edit.
2. Pegar Callback URL y Verify Token.
3. Verificar y guardar.
4. En Manage, suscribir evento messages.

Paso 6: Validar operacion

1. Enviar mensaje de prueba al numero.
2. Confirmar que entra a Zyntia.
3. Responder desde Zyntia y confirmar entrega.

4. Guia por casos (paso a paso)

Caso 1: Ya usas WhatsApp normal (app personal)

Que significa: el numero esta en WhatsApp Messenger.

Paso a paso:

1. Definir decision de negocio:
   • Migrar ese numero a negocio/API, o
   • Abrir numero nuevo para automatizacion.
2. Si el cliente quiere riesgo bajo, usar numero nuevo.
3. Ejecutar Flujo base completo con el numero elegido.
4. Hacer prueba con cliente real y aprobar salida.

Resultado esperado:

• Bot funcionando sin afectar operacion personal del cliente.

Caso 2: Ya usas WhatsApp Business app (Android/iOS)

Que significa: el numero ya opera en app de negocio.

Paso a paso:

1. Validar estado exacto del numero en Meta antes de prometer arquitectura.
2. Definir camino:
   • API puro, o
   • coexistencia (si aplica), o
   • numero nuevo.
3. Ejecutar Flujo base con el camino aprobado.
4. Definir reglas de operacion (humano vs bot) si hay operacion mixta.

Resultado esperado:

• Canal conectado con reglas claras para evitar doble respuesta.

Caso 3: Numero nuevo, sin uso previo

Que significa: numero limpio para canal de negocio.

Paso a paso:

1. Confirmar que el cliente tiene OTP del numero nuevo.
2. Ejecutar Flujo base sin pasos de migracion.
3. Crear pruebas minimas:
   • Inbound OK.
   • Outbound OK.
4. Entrenar al cliente en uso del bot en Zyntia.

Resultado esperado:

• Go-live mas rapido y menor friccion tecnica.

Caso 4: Ya tienes Meta Business Manager y activos creados

Que significa: empresa con estructura previa en Meta.

Paso a paso:

1. Inventariar activos existentes: BM, app, WABA, numero.
2. Validar ownership y permisos admin.
3. Reusar activos correctos (evitar crear duplicados).
4. Ejecutar Flujo base con activos ya aprobados.

Resultado esperado:

• Integracion ordenada, sin duplicar configuraciones.

Caso 5: Ya tienes API con otro proveedor

Que significa: numero productivo en otro BSP.

Paso a paso:

1. Levantar inventario actual:
   • webhook,
   • plantillas,
   • volumen,
   • horarios pico.
2. Definir ventana de corte con fecha/hora.
3. Definir plan de rollback.
4. Ejecutar migracion a Zyntia.
5. Cambiar webhook y validar trafico en tiempo real.
6. Monitorear 24-48h con soporte activo.

Resultado esperado:

• Migracion sin corte relevante de mensajes.

Caso 6: Tienes un numero activo y quieres sumar otro nuevo

Que significa: operacion mixta (continuidad + expansion).

Paso a paso:

1. Mantener numero actual para operacion estable.
2. Configurar numero nuevo en Zyntia para automatizacion.
3. Empezar con casos de uso de bajo riesgo.
4. Medir resultados y ampliar cobertura gradualmente.
5. Decidir despues si conviene consolidar numeros.

Resultado esperado:

• Escalamiento controlado sin interrumpir canal principal.

5. Datos exactos que se pegan en Zyntia

1. PHONE NUMBER ID.
2. SYSTEM USER ACCESS TOKEN permanente con scopes:
   • whatsapp_business_messaging
   • whatsapp_business_management
3. META APP SECRET.

6. Checklist de salida (go-live)

Marca OK en todos antes de cerrar:

1. Cliente puede entrar a Zyntia.
2. Bot creado y visible.
3. Canal WhatsApp conectado.
4. Webhook verificado en Meta.
5. Evento messages suscrito.
6. Prueba inbound OK.
7. Prueba outbound OK.
8. Responsable del cliente capacitado en uso basico.

7. Errores comunes y solucion rapida

1. Error al conectar credenciales:
   • revisar que token sea permanente y no temporal.
2. Webhook no verifica:
   • revisar Callback URL, Verify Token y permisos.
3. No llegan mensajes:
   • confirmar suscripcion de messages y estado del webhook.
4. Proyecto desordenado en Meta:
   • limpiar activos duplicados y documentar un owner tecnico.