Google Chat

Tu agente responde como una app de Google Chat. Google Chat envía cada mensaje al webhook del agente, y VirtuAI publica la respuesta a través de la API de Google Chat.

Antes de comenzar

• Un rol del espacio de trabajo que pueda editar Settings y Agents
• Un proyecto de Google Cloud con la API de Google Chat habilitada y permiso para configurar una app de Chat en tu Google Workspace
• Una cuenta de servicio en ese proyecto, con una clave JSON
• Un agente ya creado en VirtuAI. Consulta Crea tu primer agente.

1. Agrega la cuenta de servicio

En Settings, configura GOOGLE_CHAT_SERVICE_ACCOUNT_JSON con el contenido completo de la clave JSON de la cuenta de servicio. VirtuAI la usa para publicar respuestas y descargar archivos adjuntos de audio.

Luego, revisa GOOGLE_CHAT_PROJECT_NUMBER, el número del proyecto de Google Cloud donde está configurada la app de Chat. VirtuAI lo usa para verificar que cada solicitud provenga realmente de tu app de Chat (consulta el paso 6):

• Cuando guardas el JSON de la cuenta de servicio, VirtuAI busca el número del proyecto y lo completa. Para eso, la cuenta de servicio necesita el permiso resourcemanager.projects.get en su proyecto, por ejemplo, mediante el rol Browser (roles/browser).
• Si la configuración sigue vacía después de guardar, la cuenta de servicio no puede leer su proyecto. Escribe el número tú mismo: aparece como Project number en el panel del proyecto en la consola de Google Cloud. La búsqueda solo se ejecuta cuando cambia el JSON, así que volver a guardar el mismo JSON no la repite.

La cuenta de servicio debe pertenecer al mismo proyecto que la app de Chat.

De manera opcional, cambia lo que las personas ven mientras el agente trabaja:

Configuración	Qué hace
GOOGLE_CHAT_WAITING_MESSAGE	El texto del mensaje de espera. El valor predeterminado está en español, así que configura el tuyo si tus usuarios no hablan español.
GOOGLE_CHAT_WAITING_IMAGE_URL	Una imagen o un GIF animado que se muestra con el mensaje de espera

2. Activa Google Chat para el agente

Edita el agente. En Channels, asegúrate de que Google Chat esté activado. Está activado de forma predeterminada, y la tarjeta muestra Responds in Google Chat spaces. En AI Model Configuration, elige el modelo y, luego, guarda.

3. Copia la URL del webhook

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

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

4. Configura la app de Chat

En la consola de Google Cloud, abre la configuración de la API de Google Chat de tu proyecto:

1. Asígnale a la app un nombre, un avatar y una descripción.
2. En la configuración de conexión, elige un extremo HTTP y pega la URL del webhook.
3. Configura Authentication audience como Project number. VirtuAI solo acepta solicitudes cuyo token se emitió para el número de tu proyecto.
4. Elige quién puede encontrar y usar la app en tu Google Workspace.
5. Guarda.

5. Agrega comandos de barra (opcional)

El agente entiende cinco comandos. Para que aparezcan en el menú de comandos de Google Chat, agrégalos en la configuración de la API de Chat con estos IDs de comando:

Comando	ID de comando	Qué hace
/new [title]	1	Inicia una conversación nueva, con un título opcional
/resume	2	Muestra tus últimas 5 conversaciones. /resume 2 cambia a la segunda.
/status	3	Te indica si el agente sigue trabajando y desde hace cuánto
/cancel	4	Detiene la tarea en ejecución
/help	5	Muestra los comandos

6. Revisa la verificación de las solicitudes

Google Chat firma cada solicitud que envía a tu app con un token emitido para tu proyecto. VirtuAI verifica ese token con GOOGLE_CHAT_PROJECT_NUMBER y rechaza con 401 cualquier solicitud que no lleve un token válido para ese proyecto. Si ejecutas la app como complemento de Google Workspace, VirtuAI verifica en cambio que la solicitud provenga del agente de servicio de complementos de tu proyecto, y no hay nada más que configurar.

Antes del lanzamiento, verifica lo siguiente:

• GOOGLE_CHAT_PROJECT_NUMBER está configurado en Settings.
• El Authentication audience de la app de Chat es Project number.

Google Chat no usa claves de integración: una vez configurado el número del proyecto, el token de Google las reemplaza.

7. Prueba

1. Escríbele a la app directamente y envía un saludo.
2. Haz una pregunta real del negocio.
3. Agrega la app a un espacio, menciónala con @ y vuelve a preguntar.
4. Verifica que la conversación aparezca en Conversations.

Cómo se comportan los mensajes

• Mensaje de espera. La app primero publica el mensaje de espera. Mientras un agente Deep trabaja, muestra una tarjeta con el plan y cada paso, que se actualiza en el lugar.
• Conversaciones. Cada persona tiene su propia conversación con el agente en cada espacio o mensaje directo. Usa /new para empezar de cero.
• Agente ocupado. Si escribes mientras un agente Deep sigue trabajando, la app responde “Got it — I’ll respond once I finish your current request.” y procesa tu mensaje a continuación.
• Respuestas a mensajes. Cuando respondes o citas un mensaje, el texto citado se envía al agente como contexto.
• Archivos adjuntos. Los archivos adjuntos de audio se pasan al agente. Los demás archivos adjuntos, como imágenes y documentos, se ignoran.
• Tus cuentas. Si el correo electrónico de Google del remitente coincide con un miembro de tu espacio de trabajo de VirtuAI, el agente usa las cuentas conectadas de ese miembro, por ejemplo, su Gmail o Drive.
• Presupuestos. Si el espacio de trabajo agotó su presupuesto, la app responde con el mensaje de presupuesto en lugar de una respuesta.
• Canal desactivado. Si Google Chat está desactivado para el agente, la app responde “This agent is not available on Google Chat.”

Solución de problemas

No hay respuesta en Google Chat : Verifica GOOGLE_CHAT_SERVICE_ACCOUNT_JSON, que Google Chat esté activado para el agente y que el extremo de la app sea la URL del webhook de este agente. Luego, revisa la verificación de las solicitudes del paso 6.

Las solicitudes se rechazan con 401 : VirtuAI no pudo verificar el token de Google. Verifica que el Authentication audience de la app de Chat sea Project number y no HTTP endpoint URL, y que GOOGLE_CHAT_PROJECT_NUMBER en Settings sea el número del proyecto donde está configurada la app de Chat.

Aparece el mensaje de espera, pero no llega ninguna respuesta : El agente falló mientras trabajaba. Revisa el modelo y las herramientas del agente en el chat web y, luego, consulta la conversación en Conversations.

Errores de autenticación o de permisos al publicar : La cuenta de servicio debe pertenecer al proyecto donde está configurada la app de Chat.

Responde el agente equivocado : El extremo de la app tiene el ID de otro agente. Vuelve a copiar la URL desde la sección Integration URLs del agente correcto.