WhatsApp

VirtuAI se conecta a WhatsApp mediante Twilio. Twilio recibe cada mensaje y lo reenvía al webhook de tu agente. Luego, el agente responde a través de Twilio desde tu número de remitente de WhatsApp.

Antes de comenzar

• Un rol del espacio de trabajo que pueda editar Settings y Agents
• Una cuenta de Twilio con un remitente de WhatsApp aprobado para tu número
• Un agente ya creado en VirtuAI. Consulta Crea tu primer agente.

1. Agrega tus credenciales de Twilio

En Settings, en el mismo espacio de trabajo que el agente, configura lo siguiente:

• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN

Ambos valores están en el panel de tu Twilio Console.

2. Elige el número de remitente

1. Abre Telephony > Messaging.
2. Selecciona Fetch Phone Numbers. VirtuAI muestra los números de tu cuenta de Twilio.
3. En WhatsApp-Capable Numbers, selecciona Set as WhatsApp Number en el número que es tu remitente de WhatsApp.

Luego, la página lo muestra como Active WhatsApp Number. Se guarda como TWILIO_WHATSAPP_NUMBER en Settings, y todos los agentes del espacio de trabajo responden desde ese número.

Nota

La lista muestra todos los números de la cuenta que admiten SMS. VirtuAI no puede saber cuáles aprobó Twilio para WhatsApp, así que elige el que registraste como remitente de WhatsApp.

3. Activa WhatsApp para el agente

Edita el agente. En Channels, activa WhatsApp. En AI Model Configuration, elige el modelo y, luego, guarda.

4. Copia la URL del webhook

En la sección Integration URLs del agente, copia WhatsApp Webhook. Tiene este formato y pertenece solo a este agente:

https://<your-virtuai-host>/whatsapp/webhook/<agent-id>

Para poner otro agente en otro número de WhatsApp, apunta el webhook de ese número a la URL del otro agente.

5. Configura el webhook en Twilio

En Twilio, abre la configuración de tu remitente de WhatsApp. Pega la URL como webhook para los mensajes entrantes, mantén el método HTTP POST y guarda.

Pega la URL exactamente como aparece en Integration URLs, sin agregar ni cambiar nada. Twilio firma cada solicitud con esa URL, y VirtuAI verifica la firma con la misma dirección.

6. Cómo verifica VirtuAI a Twilio

Twilio firma cada solicitud del webhook con el token de autenticación de la cuenta de Twilio a la que pertenece el número, y envía la firma en el encabezado X-Twilio-Signature. VirtuAI verifica esa firma en cada mensaje y rechaza con 403 cualquier solicitud que no esté firmada correctamente.

Para que la verificación funcione:

• La URL del webhook en Twilio debe ser exactamente la URL de WhatsApp Webhook de la sección Integration URLs del agente.
• TWILIO_AUTH_TOKEN en Settings debe ser el token de autenticación de la cuenta de Twilio a la que pertenece el número de WhatsApp. Si cambias el token de autenticación en Twilio, actualízalo también en Settings.

WhatsApp no usa claves de integración: la firma de Twilio las reemplaza, y Key Enforcement no afecta a WhatsApp.

7. Prueba

1. Envía un saludo desde WhatsApp a tu número.
2. Haz una pregunta real sobre un producto o de soporte.
3. Envía una pregunta larga y verifica que una respuesta larga llegue completa.
4. Verifica que la conversación aparezca en Conversations.

Cómo se comportan los mensajes

• Cada número de teléfono tiene una conversación en curso con el agente, así que el agente recuerda los mensajes anteriores de la misma persona.
• El agente responde con una sola respuesta. No hay indicador de escritura ni mensaje de progreso mientras trabaja.
• Las respuestas de más de 1,600 caracteres llegan como varios mensajes de WhatsApp, en orden.
• Solo se procesa texto. Las fotos, el audio y otros archivos multimedia no se procesan. Un mensaje con archivos multimedia recibe una respuesta breve y fija que lo indica.

Solución de problemas

No hay respuesta en WhatsApp : Verifica TWILIO_ACCOUNT_SID y TWILIO_AUTH_TOKEN, y el Active WhatsApp Number en Telephony > Messaging. Verifica que el webhook de Twilio apunte a la URL de este agente.

El depurador de Twilio muestra que el webhook falla con 403 : VirtuAI no pudo verificar la firma de Twilio. O bien la URL del webhook en Twilio no coincide con la URL de WhatsApp Webhook de Integration URLs (revisa el esquema, el host y el ID del agente, y que no se haya agregado nada), o bien TWILIO_AUTH_TOKEN en Settings no es el token de autenticación de la cuenta de Twilio a la que pertenece el número. Vuelve a copiar ambos y guarda.

Twilio indica que la llamada al webhook se realizó correctamente, pero no llega ninguna respuesta : VirtuAI primero acepta el mensaje y responde por separado. Si falta una credencial o el número de remitente, o si alguno es incorrecto, la respuesta falla. Vuelve a revisar los pasos 1 y 2.

Un error de credenciales en la página Messaging : Agrega TWILIO_ACCOUNT_SID y TWILIO_AUTH_TOKEN en Settings para este espacio de trabajo.

Responde el agente equivocado : El webhook de Twilio tiene el ID de otro agente. Vuelve a copiarlo desde la sección Integration URLs del agente correcto.