WhatsApp Business API

Guía paso a paso para conectar la API de WhatsApp Business de Meta con tu instancia de SIGNOS, desde la creación de la app hasta el primer mensaje recibido.

Requisitos previos

• Cuenta personal de Facebook
• Cuenta en Meta Business Suite
• Número de teléfono libre (no usado en WhatsApp personal ni empresarial)
• Tarjeta de crédito o débito asociada al método de pago de Meta
• Acceso al panel de SIGNOS con rol Admin

1. Crear el Meta Business Manager

Si ya tenés uno, saltá este paso.

1. Accedé a business.facebook.com
2. Clic en Crear cuenta
3. Completá nombre de la empresa, tu nombre y email
4. Verificá el email

2. Crear una App en Meta for Developers

1. Accedé a developers.facebook.com/apps
2. Clic en Crear app
3. Seleccioná tipo: Business
4. Ingresá nombre de la app (ej: "SIGNOS Integration") y email
5. Asociá tu Business Manager
6. Clic en Crear app

3. Agregar el producto WhatsApp

1. Dentro de la app, buscá el panel Agregar productos
2. Encontrá WhatsApp → clic en Configurar
3. Asociá tu Business Manager cuando lo solicite

4. Crear o vincular la cuenta WABA

WABA = WhatsApp Business Account

1. En el panel de la app → WhatsApp → Configuración
2. Seleccioná o creá una cuenta de WhatsApp Business (WABA)
3. Anotá el WABA ID (visible en la URL o en configuración)

5. Agregar y verificar el número de teléfono

1. En WhatsApp → Configuración → Números de teléfono → clic en Agregar número
2. Ingresá el nombre que verán los clientes y el número
3. Elegí método de verificación (SMS o llamada)
4. Ingresá el código OTP recibido
5. Anotá el Phone Number ID que aparece una vez verificado

6. Crear un System User con token permanente

Los Access Tokens temporales expiran en 60 días. Es fundamental crear un System User para obtener un token sin expiración.

1. Ve a Meta Business Settings → panel izquierdo Usuarios → System Users
2. Clic en Agregar:
   • Nombre: signos-integration
   • Rol: Administrador
3. Clic en el System User creado → Agregar activos:
   • Agregá la App (rol Tester o superior)
   • Agregá la cuenta WhatsApp Business (WABA) (rol Administrador parcial)
4. Clic en Generar nuevo token:
   • Seleccioná tu App
   • Habilitá los permisos de mensajería (múltiples si vas a integrar varios canales):
     - Para WhatsApp: whatsapp_business_messaging y whatsapp_business_management.
     - Para Instagram/Messenger (Opcional): instagram_basic, instagram_manage_messages, pages_manage_metadata, pages_read_engagement y pages_messaging.*Para que el token de Meta reconozca Instagram, se requiere previamente vincular el IG a la Página de Facebook y habilitar los Controles de Mensajes en el celular. Ver detalles en la guía de Canales.
   • Expiración: Nunca o Sin fecha de expiración
5. Copiá y guardá el token permanente (empieza con EAA...) en un lugar seguro. Solo se muestra una vez.

7. Configurar el Webhook en Meta

El webhook es la URL que Meta usará para enviarte los mensajes entrantes en tiempo real.

URL del Webhook de SIGNOS

Pedile la URL exacta al soporte de SIGNOS. Tiene el formato:

https://[REGION]-[PROJECT_ID].cloudfunctions.net/whatsappWebhook

Configurar en Meta

1. En tu app → WhatsApp → Configuración → Webhooks → clic en Editar
2. Ingresá:
   • URL de devolución de llamada: la URL del webhook
   • Token de verificación: un string secreto que vos definís
3. Clic en Verificar y guardar
4. En suscripciones, habilitá: ✅ messages

8. Obtener el App Secret

1. En tu app → Configuración → Básico
2. En Clave secreta de la app, clic en Mostrar
3. Copiá el App Secret

9. Configurar el Canal en SIGNOS

1. Ve a Configuración → Canales → + Nuevo Canal
2. Tipo: WhatsApp Business
3. Completá todos los campos
4. Guardá — el canal aparecerá como 🟢 Conectado

10. Probar la integración

1. Creá una Cola y asignale el canal WhatsApp
2. Enviá un mensaje desde un número de WhatsApp al número registrado
3. El mensaje debería aparecer en el Inbox en segundos ✅

11. Crear templates para mensajes outbound

Para enviar campañas o notificaciones proactivas necesitás templates aprobados por Meta.

Crear un template

1. Ve a WhatsApp Manager → Templates de mensaje
2. Clic en Crear template
3. Categoría: Marketing / Utilidad / Autenticación
4. Redactá el contenido. Usá variables dinámicas: {{1}}, {{2}}, etc.
   Ejemplo: Hola {{1}}, tu turno del {{2}} fue confirmado. ✅
5. Agregá ejemplos de las variables
6. Enviá para revisión (Meta tarda 1–24 horas)

Troubleshooting

12. Configurar Twilio para Pre-validación de Números (Recomendado)

Para campañas salientes, es común tener bases de datos con números fijos o inválidos (ej. 0800/0810). Enviarles mensajes de WhatsApp resulta en un cobro por parte de Meta sin llegar a destino. SIGNOS se integra con Twilio Lookup v2 para evitar esto, validando si un número es móvil antes del envío.

Obtener las credenciales de Twilio

1. Registrate o iniciá sesión en la Consola de Twilio.
2. En el Panel Principal (Dashboard), buscá la sección Account Info.
3. Copiá el Account SID (identificador único).
4. Hacé clic en "Mostrar" y copiá el Auth Token (tu contraseña de API).
5. Asegurate de tener saldo cargado, ya que Twilio cobra una tarifa mínima por cada validación.

Configurar Twilio en SIGNOS

1. En SIGNOS, andá a Configuración → Integraciones.
2. Buscá la tarjeta de Twilio y hacé clic en Configurar.
3. Pegá el Account SID y el Auth Token obtenidos.
4. Hacé clic en Guardar. Se marcará como 🟢 Conectado.

Activarlo en una Campaña

1. Al crear o editar una Campaña Saliente, encendé el switch "Pre-validar números con Twilio".
2. SIGNOS descartará gratis los 0800 y validará el resto con Twilio.
3. Los fijos e inválidos se moverán solos a la columna "Sin WhatsApp" en el Kanban, sin gastar saldo de Meta.
4. El resultado queda guardado, por lo que no vas a pagar la validación dos veces por el mismo contacto en futuras campañas.