Documento técnico
abdatabase.com
Tres piezas conectadas entre sí. Meta aloja la app y la cuenta de WhatsApp; tu servidor aloja la lógica del bot. La conexión entre ambos es el webhook, y suele ser el punto donde más tiempo se pierde si se salta algún paso.
Todo empieza con una cuenta de Meta for Developers vinculada a un perfil personal de Facebook.
developers.facebook.com con una cuenta de Facebook (personal o de la empresa).La app es el contenedor técnico: aquí viven las credenciales, los permisos y, más adelante, el webhook.
MiApp Bot — y asócialo a un portafolio de empresa (Meta puede crear uno nuevo automáticamente si no tienes ninguno).Con la app creada, se añade el caso de uso de mensajería.
phone_number_id).Para usar un número de teléfono real (no el de pruebas), Meta exige verificar la identidad del negocio.
Con el negocio verificado, ya se puede añadir el número que va a atender de verdad a los clientes.
business.facebook.com/latest/whatsapp_manager), dentro de la cuenta de WhatsApp Business correspondiente, ve a Números de teléfono → Agregar número de teléfono.phone_number_id que aparece junto al número — es distinto del de prueba y es el que se usará en producción.El token temporal de 24 horas que ofrece la propia pantalla de configuración no sirve para producción — hace falta uno que no caduque.
whatsapp_business_messaging y whatsapp_business_management.El webhook necesita dos comportamientos distintos en la misma URL, según el método HTTP: verificación y recepción de mensajes.
GET en la URL del webhook: responde con el valor de hub.challenge si hub.verify_token coincide con un token secreto que tú mismo eliges.POST en la misma URL: aquí llegan los mensajes reales, en formato JSON.# Verificación (una sola vez, cuando registras el webhook)
GET /webhook/whatsapp?hub.mode=subscribe&hub.verify_token=TU_TOKEN_SECRETO&hub.challenge=123456
→ responde "123456" en texto plano, si el token coincide
# Cada mensaje entrante
POST /webhook/whatsapp
Content-Type: application/json
X-Hub-Signature-256: sha256=... ← firma HMAC del cuerpo, verificar antes de procesarCon el servidor ya respondiendo, se le dice a Meta dónde está.
hub.verify_token.GET de verificación contra tu servidor.messages — es el único imprescindible para un bot conversacional básico.Verificar el webhook y activar messages en la app no es suficiente. Falta un paso que no está en ningún sitio visible de la interfaz de configuración: suscribir la propia cuenta de WhatsApp Business a la app.
messages aparece como suscrito, y aun así nunca llega ningún mensaje real al servidor — ni una sola petición POST, por más que se le escriba al número. Es fácil perder horas revisando certificados, firewalls y DNS cuando el problema está en otro sitio.
La comprobación y la corrección se hacen con dos llamadas directas a la Graph API, usando el token permanente del paso 6:
# 1. Comprobar si la WABA ya está suscrita a la app
GET https://graph.facebook.com/v21.0/{waba_id}/subscribed_apps
Authorization: Bearer {token}
# Si la respuesta es {"data": []} -- vacía -- ese es el problema.
# 2. Suscribirla
POST https://graph.facebook.com/v21.0/{waba_id}/subscribed_apps
Authorization: Bearer {token}
# Respuesta esperada: {"success": true}El waba_id (identificador de la cuenta de WhatsApp Business, distinto del phone_number_id) se encuentra en el Administrador de WhatsApp, en la URL o en el selector de cuentas de la parte superior.
POST nueva, con el cuerpo JSON del mensaje.POST /{phone_number_id}/messages usando el mismo token permanente.Todo lo anterior sirve para conectar el número de tu propio negocio. Si el bot se va a ofrecer como servicio a otros negocios (cada uno con su propia marca y número), el modelo correcto no es meter el número de cada cliente dentro de tu propio portafolio — es registrarse como proveedor de tecnología (antes llamado BSP).
Con ese modelo, cada cliente verifica y es dueño de su propia cuenta de WhatsApp Business, y autoriza a tu app a gestionarla vía un flujo de alta alojado por el propio Meta (Embedded Signup). Tu servidor sigue siendo uno solo, pero cada cliente conserva su identidad de marca de cara a Meta y a sus propios usuarios finales, en vez de aparecer como una cuenta más dentro de tu negocio.
| Síntoma | Causa habitual | Cómo resolverlo |
|---|---|---|
| El webhook se verifica bien, pero no llega ningún mensaje real | La WABA nunca se suscribió a la app | Ver §9 — POST /{waba_id}/subscribed_apps |
hub.challenge nunca se acepta al guardar el webhook |
El token de verificación no coincide, o el servidor no responde con texto plano | Comparar el token carácter a carácter; comprobar el Content-Type de la respuesta |
| No se puede registrar el número real | Ese número ya tiene una cuenta activa en la app normal de WhatsApp | Eliminar la cuenta desde el propio móvil antes de darlo de alta |
| El portafolio comercial queda restringido al crearlo, sin explicación | Se creó o navegó con automatización de navegador en el primer acceso | Recrearlo a mano, sin herramientas de automatización, en un navegador limpio |
| El token deja de funcionar a las 24 h | Se usó el token temporal de la pantalla de configuración rápida, no uno permanente | Generar uno de verdad desde un Usuario del sistema (§6) |
| Término | Significado |
|---|---|
App |
Contenedor técnico en Meta for Developers que aloja las credenciales y la configuración del webhook. |
WABA |
WhatsApp Business Account — la cuenta que contiene uno o varios números de teléfono reales. |
phone_number_id |
Identificador técnico de un número concreto dentro de una WABA; distinto del número visible. |
| Usuario del sistema | Identidad técnica (no una persona) usada para generar tokens de acceso permanentes con permisos concretos. |
| Verify token | Cadena secreta, elegida por quien monta el servidor, que Meta envía en la verificación del webhook para confirmar que la URL es legítima. |
| Proveedor de tecnología | Modelo para gestionar, desde una sola app, las cuentas de WhatsApp de varios clientes distintos sin ser dueño de ellas. |