Saltar al contenido principal

📱 WhatsApp Cloud API

WhatsApp se conecta a través de la API Cloud de Meta — la API oficial, disponible en nivel gratuito, que te permite enviar y recibir mensajes de WhatsApp desde tu propio servidor. No se requiere un BSP (Proveedor de Soluciones Empresariales) de terceros.

Requisitos Previos​

  1. Una cuenta de desarrollador de Meta en developers.facebook.com
  2. Una cuenta Meta Business (también conocida como Business Manager)
  3. Un número de teléfono para WhatsApp que no esté registrado en WhatsApp personal (puedes usar una SIM, un número virtual o un teléfono fijo)

Pasos de Configuración​

1. Crear una App de Meta​

  1. Ve a developers.facebook.com/apps
  2. Haz clic en Crear App
  3. Elige el tipo Business
  4. Completa un nombre y conecta tu cuenta Business

2. Agregar el Producto WhatsApp​

  1. En el panel de tu app, desplázate a Agregar Productos a Tu App
  2. Haz clic en Configurar en WhatsApp
  3. Selecciona tu cuenta Business

3. Obtener Tus Credenciales​

Navega a WhatsApp → Configuración de API en el panel de tu app:

CredencialDónde Encontrarla
Phone Number IDListado en la sección "From" — un ID numérico como 123456789012345
Access TokenEl token temporal mostrado en esta página. Para producción, genera un token permanente vía System Users.
App SecretPanel de la App → Configuración → Básica → App Secret
Verify TokenUna cadena que tú inventas — cualquier cadena aleatoria, ej. my_secret_verify_token_2024

4. Agregar el Canal en PulseHub​

  1. Ve a Canales → Agregar Canal
  2. Selecciona WhatsApp
  3. Completa los cuatro campos
  4. Haz clic en Guardar Canal
  5. Copia la URL del Webhook mostrada en la tarjeta del canal

5. Configurar el Webhook en Meta​

  1. En tu app de Meta, ve a WhatsApp → Configuración
  2. Haz clic en Editar junto a la sección de Webhook
  3. URL de Callback: pega tu URL de webhook de PulseHub
  4. Verify Token: ingresa la misma cadena que pusiste en PulseHub
  5. Haz clic en Verificar y Guardar

Meta hará una solicitud GET a tu URL de webhook con ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... PulseHub verifica el token y devuelve el challenge.

  1. En Campos de Webhook, suscríbete a: messages

6. Probar​

Envía un mensaje de WhatsApp a tu número de negocio. Debería aparecer como una nueva conversación en la bandeja de PulseHub en segundos.

Verificación de Firma​

Meta incluye un header X-Hub-Signature-256 en cada webhook:

X-Hub-Signature-256: sha256=abc123...

PulseHub lo verifica usando HMAC-SHA256 con tu App Secret. Si la verificación falla, el webhook devuelve 401 Signature mismatch.

Envío de Mensajes​

Cuando un agente envía una respuesta desde la bandeja, PulseHub llama a la API de WhatsApp Cloud:

POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
  "messaging_product": "whatsapp",
  "to": "{recipient_phone}",
  "type": "text",
  "text": {"body": "Tu respuesta aquí"}
}

Acceso a Producción​

La app de Meta por defecto está en modo Development — solo puede enviar mensajes a números agregados como números de prueba. Para salir en vivo:

  1. Completa la Verificación de Negocio en Meta Business Manager
  2. Envía tu caso de uso de WhatsApp para la revisión de Meta
  3. Una vez aprobado, tu app obtiene acceso para enviar mensajes a todos los usuarios de WhatsApp

Problemas Comunes​

SíntomaCausa Probable
La verificación falla durante la configuración del webhookEl verify_token en PulseHub no coincide con lo que ingresaste en Meta
Error de firma no coincidente en los logsapp_secret incorrecto — cópialo desde Configuración de la App → Básica, no desde Configuración de API
Los mensajes no lleganEl campo de webhook messages no está suscrito en el panel de Meta
Invalid phone number al enviarEl formato del número debe ser E.164 sin + (ej. 15551234567)
Error de app en modo DevelopmentSolo los números de prueba verificados pueden recibir mensajes en modo dev