Integración con Google Chat

Conecta tu agent a Google Chat para una comunicación fluida dentro de Google Workspace.

Descripción General

La integración con Google Chat ofrece:

• Mensajes directos con tu bot
• Soporte de Spaces de Google Workspace con activación por @menciones
• Enrutamiento de agent a nivel de Space — asigna distintos agents a distintos Spaces
• Respuestas en texto con memoria de conversación y conciencia opcional del contexto del Space
• Procesamiento asíncrono con confirmación inmediata
• Seguridad lista para empresas con aislamiento por dominio

Requisitos Previos

• Un AI agent activo (creado en la sección Agents)
• Una cuenta de Google Workspace (las cuentas personales de Gmail no son compatibles)
• Un dominio verificado — verifica la propiedad de tu dominio en Settings > Domains antes de conectar

Pasos de Configuración

1. Verificar tu Dominio (Configuración Única)

Antes de conectar Google Chat, verifica la propiedad de tu dominio:

1. Ve a Settings desde la barra lateral
2. Haz clic en la pestaña Domains
3. Tu dominio se detecta automáticamente a partir del email de tu cuenta
4. Agrega un TXT record en tu proveedor de DNS con los valores indicados:
   • Type: TXT
   • Name: _cuneiform-verify (o el valor completo mostrado)
   • Content: La cadena de verificación que se muestra (por ejemplo, cuneiform-verify=abc123...)
5. Haz clic en Verify Now — los cambios de DNS pueden tardar hasta 48 horas en propagarse
6. Cuando el estado cambie a Verified, procede a crear la integración

En la tarjeta de verificación se muestran enlaces rápidos a proveedores de DNS habituales (Cloudflare, GoDaddy, Namecheap, Route 53, DigitalOcean, Hostinger).

2. Crear la Integración con Google Chat

1. Ve a Integrations desde la barra lateral
2. En “Google Chat Bots”, haz clic en Connect Bot
3. Selecciona el Agent que será el predeterminado para los DMs y los Spaces sin vinculación
4. Ingresa un Bot Name (para tu referencia en el panel de administración)
5. Haz clic en Connect Bot
6. Copia el Verification Code que se muestra (formato: VERIFY-XXXXXX)

3. Completar la Verificación del Bot

Tras crear la integración, recibirás un código de verificación:

1. Abre Google Chat
2. Haz clic en Start a chat → Find apps
3. Busca el bot de la plataforma
4. Inicia un mensaje directo con el bot
5. Envía el código de verificación (por ejemplo, VERIFY-ABC123)
6. El bot confirmará: “Setup complete! Your workspace (yourdomain.com) is now connected. Send a message to start chatting!”

El estado de tu integración cambiará de “Pending Verification” a “Active”.

Usar el Bot

Mensajes Directos

Los usuarios pueden iniciar una conversación:

1. Abre Google Chat
2. Haz clic en Start a chat → Find apps
3. Busca el nombre de tu bot
4. Comienza a chatear con naturalidad — el bot responde a todos los mensajes en DMs

Los DMs siempre los maneja el agent predeterminado.

En Spaces

Agrega el bot a un Space:

1. Abre el Space
2. Haz clic en el nombre del Space → Manage apps
3. Agrega tu bot
4. Menciona al bot con @Cuneiform Chat para interactuar — el bot solo responde a @menciones en Spaces

Enrutamiento de Agent a Nivel de Space

Cada Space puede usar opcionalmente un agent distinto al predeterminado. Usa estos comandos del bot dentro de un Space (requiere @mención):

Cómo funciona el enrutamiento:

• DMs → siempre usan el agent predeterminado
• Space con agent personalizado → usa el agent asignado
• Space sin agent personalizado → vuelve al agent predeterminado

Conciencia del Historial de Threads

Por defecto, el bot solo ve el mensaje que lo @mencionó directamente. Si los miembros del equipo envían primero mensajes de contexto (en otros threads o más arriba en el Space) y luego @mencionan al bot, no tendrá ese contexto — a menos que un gestor del Space ejecute /connect.

Cómo Funciona

1. Un gestor del Space envía @Cuneiform Chat /connect en el Space
2. El bot envía un enlace de autorización único (expira en 10 minutos)
3. El gestor hace clic en el enlace e inicia sesión con su cuenta de Google Workspace
4. El bot ahora puede leer los mensajes enviados en el Space dentro de los últimos 15 minutos antes de cada @mención

Una vez conectado, en cada @mención el bot lee automáticamente los mensajes recientes del Space como contexto — entendiendo lo que el equipo discutía antes de ser @mencionado.

Ejemplo: Los miembros del equipo publican “¿cuáles son los planes de precios?” y “¿qué incluye el starter?” y luego @mencionan al bot con “¿puedes ayudar?” — el bot ve los tres mensajes y responde con el contexto completo.

Requisitos y Privacidad

• Solo los gestores del Space (no los miembros regulares) pueden ejecutar /connect
• La autorización es por Space — cada Space necesita su propio /connect
• El token de OAuth de Google del gestor del Space está cifrado y almacenado de forma segura
• Solo se pueden leer los mensajes visibles para la cuenta de ese gestor
• Eliminar el bot de un Space borra automáticamente el token almacenado

Re-autorización

Si el bot pierde el acceso (por ejemplo, el token fue revocado en tu cuenta de Google), notificará al Space:

⚠️ Thread history access has expired. A space manager should run /connect to restore it.

Vuelve a ejecutar /connect para restaurar el acceso.

Funcionalidades

Respuestas Asíncronas

Cuando envías un mensaje, el bot responde de inmediato con una breve confirmación (por ejemplo, “Working on it…”) y luego entrega la respuesta completa una vez finalizado el procesamiento. Esto suele tardar entre 3 y 8 segundos según la complejidad de tu pregunta.

Memoria de Conversación

El bot recuerda el contexto dentro de una sesión, por lo que puedes hacer preguntas de seguimiento sin tener que repetirte.

Conciencia del contexto del Space (opt-in): Después de que un gestor del Space ejecute /connect, el bot lee los mensajes enviados en el Space dentro de los últimos 15 minutos antes de cada @mención — para que entienda lo que el equipo ya estaba discutiendo sin que tengas que repetir el contexto. Consulta Conciencia del Historial de Threads abajo para los pasos de configuración.

Cola de Mensajes

Si envías mensajes adicionales mientras el bot aún procesa, se ponen en cola y se incluyen en la siguiente respuesta. Verás un mensaje como “I’m still working on your previous question. I’ll include this in my next response.”

Comando /help

Escribe /help o help para ver las instrucciones de uso, incluidos los comandos de Space disponibles.

Acceso por Dominio

Solo los usuarios de tu dominio de Google Workspace pueden interactuar con tu bot, lo que garantiza seguridad de nivel empresarial.

Respuestas en Texto

El bot responde solo con mensajes de texto. No se admiten imágenes, archivos, botones interactivos ni adjuntos de cards. Las respuestas se limitan a aproximadamente 30.000 caracteres.

Gestionar tu Integración

Cada tarjeta de integración muestra:

• Bot name - El nombre para mostrar que configuraste
• Status badge - Active, Pending Verification o Error
• Domain name - Tu dominio de Google Workspace (después de la verificación)
• Default agent - Lista desplegable para cambiar el agent predeterminado (usado para DMs + Spaces sin vinculación)
• Space mappings - Sección colapsable que muestra qué Spaces tienen asignaciones de agent personalizadas
• Space commands - Sección colapsable que muestra los comandos del bot disponibles
• Marca temporal de Last activity

Acciones Disponibles

Solución de Problemas

El Bot No Aparece en Google Chat

1. Asegúrate de usar una cuenta de Google Workspace (no una cuenta personal de Gmail)
2. Busca el nombre del bot en “Find apps”
3. Espera unos minutos a que la app se propague

La Sección de Google Chat No Es Visible

1. Google Chat solo aparece para organizaciones que usan Google Workspace
2. Si tu organización usa otro proveedor de email (por ejemplo, Microsoft 365), la sección queda oculta
3. El sistema detecta automáticamente tu proveedor de email mediante registros MX

Problemas de Verificación de Dominio

1. Los cambios de DNS pueden tardar hasta 48 horas en propagarse — espera y vuelve a intentar Verify Now
2. Comprueba que hayas agregado el TXT record con los valores exactos que se muestran en Settings > Domains
3. Verifica que el registro esté en el dominio correcto (por ejemplo, _cuneiform-verify.yourdomain.com)
4. Usa los enlaces rápidos de proveedores de DNS en la tarjeta de verificación para acceder fácilmente

El Código de Verificación No Funciona

1. Asegúrate de enviar el código desde tu email de Google Workspace
2. Comprueba que el código se ingresó exactamente como aparece (incluido el prefijo VERIFY-)
3. Verifica que la integración aún esté en estado “Pending Verification”
4. Intenta crear una nueva integración si el código ha expirado

El Bot Dice “Working on it…” Pero No Llega Respuesta

1. El bot procesa los mensajes de forma asíncrona — espera hasta 25 segundos para la respuesta completa
2. Si no llega respuesta, intenta enviar tu mensaje de nuevo
3. Comprueba que el agent asociado esté configurado correctamente

Los Mensajes No Se Procesan

1. Confirma que tu workspace haya sido verificado (el estado debe ser “Active”)
2. En los Spaces, asegúrate de @mencionar al bot
3. Comprueba que el agent asociado esté configurado correctamente

Mensaje “Organization hasn’t connected”

Esto significa que el bot no reconoce tu dominio de Google Workspace:

1. Tu administrador aún no ha creado la integración
2. El dominio no se ha verificado con un código de verificación
3. Estás escribiendo desde una cuenta personal de Gmail (no compatible)

/set-agent Dice Que el Agent No Se Encontró

1. Comprueba el nombre exacto del agent en el panel de administración (distingue mayúsculas y minúsculas)
2. Asegúrate de que el agent esté en estado “Active”
3. Se admiten nombres de agent con espacios — escribe el nombre completo después de /set-agent

/connect Dice “Only space managers can run /connect”

Debes ser gestor del Space para ejecutar /connect. Pídele a un gestor del Space que ejecute el comando.

Enlace de Autorización de /connect Expirado

El enlace es válido por 10 minutos. Vuelve a ejecutar @Cuneiform Chat /connect para obtener un enlace nuevo.

El Bot Dice “Thread history access has expired”

Un gestor del Space debe ejecutar @Cuneiform Chat /connect de nuevo para reautorizar. Esto sucede cuando el token de OAuth de Google es revocado (por ejemplo, en la configuración de la cuenta de Google).

Seguridad

• Verificación de propiedad del dominio — un TXT record de DNS demuestra que tu organización es dueña del dominio antes de conectar
• Detección de Google Workspace — la verificación de registro MX confirma que tu dominio usa Google Workspace
• Aislamiento por dominio — solo los usuarios de Google Workspace de tu organización pueden interactuar con tu bot
• Verificación de webhook — cada solicitud entrante se valida contra el proyecto de Google Cloud de tu plataforma
• Los códigos de verificación son de un solo uso y están vinculados a tu dominio
• Los mensajes se procesan a través de conexiones seguras y cifradas

Desconectar

Para eliminar la integración con Google Chat:

1. Ve a Integrations desde la barra lateral
2. Encuentra la tarjeta de tu integración con Google Chat
3. Haz clic en el menú de tres puntos
4. Selecciona Disconnect

Notas Importantes

• Se requiere Google Workspace: Las cuentas personales de Gmail no pueden usar esta integración. Si tu organización no usa Google Workspace, la sección de Google Chat no aparecerá.
• Se requiere verificación de dominio: Verifica tu dominio en Settings > Domains antes de conectar Google Chat.
• Una integración por organización: Cada organización puede tener una integración con Google Chat
• Solo texto: El bot no admite imágenes, archivos ni botones interactivos
• Gestionado a nivel de organización: Google Chat se configura en la página Integrations, no por agent
• Enrutamiento de Spaces: Usa /set-agent en los Spaces para asignar agents especializados a distintos equipos
• Agent predeterminado: Cambia el agent predeterminado en cualquier momento usando la lista desplegable — sin necesidad de desconectar