Conecta el agente a WhatsApp mediante la Meta Cloud API o Twilio.
Roberty admite dos proveedores para la integración con WhatsApp:
- Meta Cloud API (recomendado): directo con Meta, sin intermediarios.
- Twilio: para organizaciones que ya usan la infraestructura de Twilio.
Accede desde el icono Configuración → pestaña Integraciones → tarjeta WhatsApp.
Activar la integración
Activa el interruptor de la tarjeta de WhatsApp. Los campos de configuración aparecen una vez activado.
Activar el interruptor no basta. Mientras los campos de abajo (Phone Number ID, Access Token, App Secret y Verify Token, en el caso de la Meta Cloud API) estén vacíos, la integración aparece como «activada» pero el webhook de Meta falla siempre en la verificación: es la causa más común del error «No se pudo validar la URL de devolución de llamada o el token de verificación» en el panel de Meta for Developers. Rellena los cuatro campos y espera el indicador de guardado antes de hacer clic en Verify and Save en Meta.
Cómo funciona
- El proveedor envía un webhook cuando llega un mensaje.
- Roberty valida la firma (cuando la hay) y resuelve el agente.
- El agente se ejecuta y la respuesta vuelve por la API de salida del proveedor.
El endpoint base es:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID>
Usa Copiar ID, en la parte superior de la pestaña Integraciones, para obtener el AGENT_ID.
Proveedor
Elige el proveedor que envía los mensajes:
| Proveedor | Cuándo usarlo |
|---|---|
| Meta Cloud API | Una integración directa con WhatsApp Business a través de Meta: recomendada en la mayoría de los casos |
| Twilio | Cuando tu organización ya usa Twilio para mensajería |
Proveedor: Meta Cloud API
Los campos de configuración
| Campo | Qué es |
|---|---|
| Phone Number ID | El identificador del número de teléfono registrado en Meta |
| Access Token | Un access token permanente generado en el Meta Developer Portal |
| App Secret | El app secret de la aplicación de Meta (habilita la validación HMAC de las peticiones) |
| Verify Token | Una cadena de verificación: debe coincidir con la configurada en el webhook de Meta |
Requisitos previos
- Una cuenta en Meta for Developers.
- Una app de tipo Business con el producto WhatsApp habilitado.
- Un número de teléfono de prueba (o de producción) vinculado a la app.
1. Configura antes el agente en Roberty
Antes de ir a Meta, rellena aquí los cuatro campos. Eso evita el error de handshake, porque Meta solo valida el webhook si el Verify Token ya está guardado en el agente en el momento en que haces clic en «Verify and Save» del lado de Meta.
| Campo | Dónde encontrarlo en Meta | Tutorial oficial (enlace directo a la sección) |
|---|---|---|
| Phone Number ID | El panel de la app → WhatsApp → API Setup. Aparece debajo del número seleccionado en «From». | Get Started — Step 3. Send and receive messages |
| Access Token (permanente) | No uses el token temporal que aparece en la pantalla de «API Setup» (caduca en 24 h). Genera uno permanente: Configuración del Business → Usuarios → Usuarios del sistema → crear usuario del sistema → Generar nuevo token, con los permisos whatsapp_business_messaging y whatsapp_business_management y caducidad Nunca. Después, vincula ese usuario a la cuenta de WhatsApp Business en Cuentas → Cuentas de WhatsApp → Añadir personas. | Get Started — Step 5. Create a system user and generate a permanent access token |
| App Secret | El panel de la app → Configuración → Básica → el campo «Clave secreta de la app» → Mostrar (pide tu contraseña). | App Dashboard — App Secret |
| Verify Token | No viene de Meta: es una cadena que eliges tú (generada con openssl rand -hex 24, por ejemplo). Tiene que ser idéntica en los dos lados: aquí en Roberty y en el campo «Verificar token» del webhook de Meta (el paso siguiente). | Webhooks — Verification Requests |
Rellena los cuatro y espera el indicador de guardado del Studio antes de continuar.
2. Configura el webhook en Meta
En el panel de la app, en WhatsApp → Configuration → Webhook:
- Callback URL:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID> - Verify Token: pega exactamente el valor que ya guardaste en el campo Verify Token de Roberty.
- Haz clic en Verify and Save. Roberty responde al challenge automáticamente siempre que el Verify Token coincida con el configurado en el agente.
Después, en Webhook fields, suscríbete al menos a messages.
Validación de seguridad
Con App Secret configurado, Meta envía la cabecera X-Hub-Signature-256: sha256=<hmac>, y Roberty recalcula HMAC-SHA256(appSecret, rawBody) y lo compara con timingSafeEqual.
Con App Secret en blanco, esa validación queda desactivada: no es aconsejable en producción.
Proveedor: Twilio
Los campos de configuración
| Campo | Qué es |
|---|---|
| Account SID | El SID de tu cuenta de Twilio |
| Auth Token | El auth token de tu cuenta de Twilio |
Requisitos previos
- Una cuenta de Twilio con un número de WhatsApp habilitado (sandbox, o un sender aprobado).
- Un número de envío configurado (
whatsapp:+14155238886, por ejemplo).
1. Configura el webhook en Twilio
En la consola de Twilio, en Messaging → Settings → WhatsApp Senders (o en el sandbox), define:
- When a message comes in:
https://agent-backend.roberty.app/integrations/whatsapp/<AGENT_ID>(método POST). - Content-Type:
application/x-www-form-urlencoded(el de Twilio por defecto).
2. Configura el agente en Roberty
Elige el proveedor Twilio y rellena Account SID y Auth Token.
La versión actual no valida la cabecera X-Twilio-Signature. Recomendamos restringir el endpoint por IP, o usar una ruta dedicada por agente y no publicar el AGENT_ID.
Solución de problemas
| Síntoma | Causa probable |
|---|---|
| Meta dice «No se pudo validar la URL de devolución de llamada o el token de verificación», incluso con el interruptor de WhatsApp activado en Roberty | Los campos Phone Number ID / Access Token / App Secret / Verify Token están vacíos en Roberty: activar el interruptor no rellena nada. Rellena los cuatro (ver la tabla de arriba), espera a que guarde y solo entonces haz clic en Verify and Save en Meta. |
| El handshake de Meta falla (incluso con los campos rellenos) | El verifyToken del agente no coincide exactamente con el introducido en el webhook: revisa si se coló un espacio o un salto de línea al pegar en cualquiera de los dos lados. |
401 Invalid signature (Meta) | El appSecret es incorrecto, o no se preservó el raw body. |
| El mensaje llega pero el agente no responde | El proveedor configurado es el equivocado (Meta recibiendo el payload form-encoded de Twilio, por ejemplo). |
| Twilio entrega el mensaje dos veces | Twilio reentrega cuando hay un timeout. |