Conecta un número de WhatsApp Business mediante las credenciales de la API de Meta Cloud y webhooks firmados.
Conecta un número de WhatsApp Business mediante las credenciales de la API de Meta Cloud y webhooks firmados.
Prepara la app de Meta y el número#
Usa la guía de inicio de la API de WhatsApp Cloud oficial de Meta para crear o seleccionar una app de Meta, añadir el producto WhatsApp y asociar una cuenta de WhatsApp Business y un número de teléfono.
Reúne estos tres valores de la misma app y del mismo número:
| Campo de Make Agent Fast | Valor del proveedor | Notas |
|---|---|---|
| ID del número de teléfono | ID numérico del número de teléfono (Phone Number ID) | No es el número visible con + ni el ID de la WABA |
| Token de acceso | Token de acceso de la Cloud API | Los tokens temporales del panel caducan; para producción usa un token de usuario del sistema de larga duración adecuado |
| Secreto de la app | Secreto de la app de Meta | Un secreto hexadecimal de 32 caracteres que se usa para verificar la firma del webhook |
Concede únicamente los permisos necesarios para el número y el flujo de mensajería. Mantén los recursos de desarrollo y pruebas separados del número de producción.
Guarda y valida las credenciales#
Abre la página Canales del agente, selecciona WhatsApp, introduce los tres valores, elige Responder con voz si lo necesitas y selecciona Conectar.
Make Agent Fast valida el número a través de la Graph API usando el token de acceso junto con appsecret_proof; así se detecta un número, un token o un secreto de la app incorrectos antes de que empiece el tráfico del webhook. Después, la tarjeta del conector muestra una URL del webhook y un Token de verificación únicos.
Configura el webhook de Meta#
En la misma app de Meta:
- Abre la configuración del webhook de WhatsApp.
- Pega la URL del webhook del conector como URL de devolución de llamada.
- Pega el Token de verificación del conector exactamente como aparece; distingue entre mayúsculas y minúsculas.
- Completa la verificación.
- Suscribe la cuenta de WhatsApp Business o el número al campo de webhook
messages. - Confirma que la app y los recursos de negocio están disponibles para los usuarios de prueba o de producción previstos.
El token de verificación demuestra la propiedad durante el desafío de verificación GET. Las solicitudes POST en tiempo de ejecución se autentican por separado con la firma del secreto de la app de Meta; no sustituyas una por otra.
Prueba texto y voz#
Envía primero un mensaje desde un número de prueba permitido. En el modo de desarrollo de Meta, es posible que los usuarios no registrados no puedan comunicarse con la app. Confirma el hilo y el canal en Conversaciones y observa Último mensaje en la tarjeta del conector.
Se admiten texto y voz entrantes. Con Responder con voz activado y la voz configurada, Make Agent Fast sube el audio generado a través de la Cloud API y lo envía junto con la respuesta de texto. Las imágenes, ubicaciones, contactos y otros tipos de mensaje no compatibles se ignoran.
Preparación para producción#
Antes de dar a conocer el número, completa la verificación de empresa de Meta, la revisión de la app, el nombre para mostrar, las plantillas y los pasos de la política de mensajería que exija tu caso de uso. Estos requisitos los controla Meta y pueden cambiar con independencia de Make Agent Fast.
Usa una credencial de producción con un responsable definido y un procedimiento de caducidad y rotación. Anota qué app de Meta, usuario del sistema, WABA y Phone Number ID pertenecen a este conector para que un operador pueda rotarlo sin adivinar.
Rota o desconecta#
Crea un token de reemplazo con el mismo acceso a los recursos, actualiza el conector, envía un mensaje de prueba y solo entonces revoca el token anterior. Si cambia el secreto de la app, actualízalo de inmediato en Make Agent Fast o todos los webhooks entrantes firmados fallarán.
Desactivar o eliminar el conector no cancela la suscripción ni borra la configuración del webhook en Meta. Elimina también la suscripción del proveedor cuando des de baja el número de forma definitiva.
Solución de problemas#
| Síntoma | Solución |
|---|---|
| Credenciales rechazadas | Confirma que el token puede leer el Phone Number ID exacto y que el secreto de la app pertenece a la misma app |
| Meta no puede verificar la devolución de llamada | Usa la URL HTTPS copiada y el token de verificación exacto; comprueba que el conector sigue existiendo |
| La verificación se completa, pero no llegan mensajes | Suscribe messages y revisa la asociación de la WABA y el número, el modo de la app, el acceso de los usuarios de prueba y los registros de entrega del proveedor |
| Los webhooks devuelven «unauthorized» | Vuelve a introducir el secreto de la app correcto; las firmas POST de Meta no usan el token de verificación |
| Fallan las respuestas salientes | Revisa la caducidad del token, los permisos del número, la política o ventana del destinatario y los errores de la Graph API |
| El texto funciona, pero el audio falla | Revisa las claves del proveedor de transcripción o de voz y el acceso del token a la subida y descarga de contenido multimedia |
No expongas nunca el token de acceso ni el secreto de la app en código del navegador. Usa la API pública solo desde un servidor de confianza cuando automatices la creación de conectores.