Integração com Google Chat

Conecte seu agent ao Google Chat para uma comunicação fluida dentro do Google Workspace.

Visão Geral

A integração com Google Chat oferece:

• Mensagens diretas com seu bot
• Suporte a Spaces do Google Workspace com gatilhos por @menção
• Roteamento de agent no nível do Space — atribua agents diferentes a Spaces diferentes
• Respostas em texto com memória de conversa e ciência opcional do contexto do Space
• Processamento assíncrono com confirmação imediata
• Segurança pronta para uso corporativo com isolamento por domínio

Pré-requisitos

• Um AI agent ativo (criado na seção Agents)
• Uma conta do Google Workspace (contas pessoais do Gmail não são suportadas)
• Um domínio verificado — verifique a propriedade do seu domínio em Settings > Domains antes de conectar

Passos de Configuração

1. Verificar Seu Domínio (Configuração Única)

Antes de conectar o Google Chat, verifique a propriedade do seu domínio:

1. Vá para Settings na barra lateral
2. Clique na aba Domains
3. Seu domínio é detectado automaticamente a partir do e-mail da sua conta
4. Adicione um TXT record no seu provedor de DNS com os valores exibidos:
   • Type: TXT
   • Name: _cuneiform-verify (ou o valor completo exibido)
   • Content: A string de verificação exibida (por exemplo, cuneiform-verify=abc123...)
5. Clique em Verify Now — alterações de DNS podem levar até 48 horas para se propagar
6. Quando o status mudar para Verified, prossiga para criar a integração

Links rápidos para os principais provedores de DNS (Cloudflare, GoDaddy, Namecheap, Route 53, DigitalOcean, Hostinger) são exibidos no card de verificação.

2. Criar a Integração com Google Chat

1. Vá para Integrations na barra lateral
2. Em “Google Chat Bots”, clique em Connect Bot
3. Selecione o Agent que será o padrão para DMs e Spaces sem vínculo
4. Insira um Bot Name (para sua referência no painel admin)
5. Clique em Connect Bot
6. Copie o Verification Code exibido (formato: VERIFY-XXXXXX)

3. Concluir a Verificação do Bot

Depois de criar a integração, você receberá um código de verificação:

1. Abra o Google Chat
2. Clique em Start a chat → Find apps
3. Procure pelo bot da plataforma
4. Inicie uma mensagem direta com o bot
5. Envie o código de verificação (por exemplo, VERIFY-ABC123)
6. O bot vai confirmar: “Setup complete! Your workspace (yourdomain.com) is now connected. Send a message to start chatting!”

O status da sua integração vai mudar de “Pending Verification” para “Active”.

Usando o Bot

Mensagens Diretas

Os usuários podem iniciar uma conversa:

1. Abra o Google Chat
2. Clique em Start a chat → Find apps
3. Procure pelo nome do seu bot
4. Comece a conversar naturalmente — o bot responde a todas as mensagens em DMs

DMs são sempre tratadas pelo agent padrão.

Em Spaces

Adicione o bot a um Space:

1. Abra o Space
2. Clique no nome do Space → Manage apps
3. Adicione seu bot
4. Mencione o bot com @Cuneiform Chat para interagir — o bot só responde a @menções em Spaces

Roteamento de Agent no Nível do Space

Cada Space pode opcionalmente usar um agent diferente do padrão. Use estes comandos do bot dentro de um Space (requer @menção):

Como o roteamento funciona:

• DMs → sempre usam o agent padrão
• Space com agent personalizado → usa o agent atribuído
• Space sem agent personalizado → cai no agent padrão

Ciência do Histórico de Threads

Por padrão, o bot só vê a mensagem que o @mencionou diretamente. Se os membros da equipe enviarem mensagens de contexto antes (em outros threads ou mais cedo no Space) e depois @mencionarem o bot, ele não vai ter esse contexto — a menos que um gerente do Space execute /connect.

Como Funciona

1. Um gerente do Space envia @Cuneiform Chat /connect no Space
2. O bot envia um link de autorização único (expira em 10 minutos)
3. O gerente clica no link e faz login com a conta do Google Workspace
4. O bot agora pode ler as mensagens enviadas no Space dentro dos últimos 15 minutos antes de cada @menção

Uma vez conectado, em cada @menção o bot lê automaticamente as mensagens recentes do Space como contexto — entendendo o que a equipe estava discutindo antes de ser @mencionado.

Exemplo: Membros da equipe postam “quais são os planos de preços?” e “o que está incluso no starter?” e depois @mencionam o bot com “você pode ajudar?” — o bot vê as três mensagens e responde com o contexto completo.

Requisitos e Privacidade

• Apenas gerentes do Space (não membros comuns) podem executar /connect
• A autorização é por Space — cada Space precisa do seu próprio /connect
• O token OAuth do Google do gerente do Space é criptografado e armazenado com segurança
• Apenas mensagens visíveis para a conta desse gerente podem ser lidas
• Remover o bot de um Space apaga automaticamente o token armazenado

Reautorização

Se o bot perder o acesso (por exemplo, o token foi revogado na sua conta do Google), ele vai notificar o Space:

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

Execute /connect novamente para restaurar o acesso.

Recursos

Respostas Assíncronas

Quando você envia uma mensagem, o bot responde imediatamente com uma confirmação curta (por exemplo, “Working on it…”) e depois entrega a resposta completa quando o processamento terminar. Isso costuma levar de 3 a 8 segundos, dependendo da complexidade da sua pergunta.

Memória de Conversa

O bot lembra do contexto dentro de uma sessão, então você pode fazer perguntas de acompanhamento sem precisar se repetir.

Ciência do contexto do Space (opt-in): Depois que um gerente do Space executa /connect, o bot lê as mensagens enviadas no Space dentro dos últimos 15 minutos antes de cada @menção — assim ele entende o que a equipe já estava discutindo sem que você precise repetir o contexto. Veja Ciência do Histórico de Threads abaixo para os passos de configuração.

Fila de Mensagens

Se você enviar mensagens adicionais enquanto o bot ainda estiver processando, elas entram em fila e são incluídas na próxima resposta. Você verá uma mensagem como “I’m still working on your previous question. I’ll include this in my next response.”

Comando /help

Digite /help ou help para ver as instruções de uso, incluindo os comandos de Space disponíveis.

Acesso por Domínio

Apenas usuários do seu domínio do Google Workspace podem interagir com seu bot, garantindo segurança em nível corporativo.

Respostas em Texto

O bot responde apenas com mensagens de texto. Imagens, arquivos, botões interativos e anexos de cards não são suportados. As respostas são limitadas a aproximadamente 30.000 caracteres.

Gerenciando Sua Integração

Cada card de integração exibe:

• Bot name - O nome de exibição que você configurou
• Status badge - Active, Pending Verification ou Error
• Domain name - Seu domínio do Google Workspace (após a verificação)
• Default agent - Lista suspensa para alterar o agent padrão (usado para DMs + Spaces sem vínculo)
• Space mappings - Seção recolhível mostrando quais Spaces têm atribuições de agent personalizadas
• Space commands - Seção recolhível mostrando os comandos do bot disponíveis
• Carimbo de Last activity

Ações Disponíveis

Solução de Problemas

O Bot Não Aparece no Google Chat

1. Garanta que você está usando uma conta do Google Workspace (não Gmail pessoal)
2. Procure pelo nome do bot em “Find apps”
3. Aguarde alguns minutos para o app se propagar

A Seção do Google Chat Não Está Visível

1. O Google Chat só aparece para organizações que usam Google Workspace
2. Se sua organização usa outro provedor de e-mail (por exemplo, Microsoft 365), a seção fica oculta
3. O sistema detecta automaticamente seu provedor de e-mail via registros MX

Problemas de Verificação de Domínio

1. Alterações de DNS podem levar até 48 horas para se propagar — aguarde e tente Verify Now novamente
2. Verifique se você adicionou o TXT record com os valores exatos exibidos em Settings > Domains
3. Confira se o registro está no domínio correto (por exemplo, _cuneiform-verify.yourdomain.com)
4. Use os links rápidos de provedores de DNS no card de verificação para acesso fácil

Código de Verificação Não Funciona

1. Garanta que você está enviando o código a partir do seu e-mail do Google Workspace
2. Verifique se o código foi inserido exatamente como exibido (incluindo o prefixo VERIFY-)
3. Confirme que a integração ainda está com status “Pending Verification”
4. Tente criar uma nova integração se o código tiver expirado

O Bot Diz “Working on it…” Mas Nenhuma Resposta Vem em Seguida

1. O bot processa as mensagens de forma assíncrona — aguarde até 25 segundos pela resposta completa
2. Se nenhuma resposta chegar, tente enviar a mensagem de novo
3. Verifique se o agent associado está configurado corretamente

Mensagens Não Estão Sendo Processadas

1. Confirme que seu workspace foi verificado (o status deve ser “Active”)
2. Em Spaces, garanta que você está @mencionando o bot
3. Verifique se o agent associado está configurado corretamente

Mensagem “Organization hasn’t connected”

Isso significa que o bot não reconhece o seu domínio do Google Workspace:

1. Seu admin ainda não criou a integração
2. O domínio não foi verificado com um código de verificação
3. Você está enviando mensagem de uma conta pessoal do Gmail (não suportada)

/set-agent Diz Que o Agent Não Foi Encontrado

1. Verifique o nome exato do agent no painel admin (diferencia maiúsculas e minúsculas)
2. Garanta que o agent está com status “Active”
3. Nomes de agent com espaços são suportados — digite o nome completo após /set-agent

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

Você precisa ser gerente do Space para executar /connect. Peça a um gerente do Space para executar o comando.

Link de Autorização do /connect Expirou

O link é válido por 10 minutos. Execute @Cuneiform Chat /connect novamente para obter um link novo.

O Bot Diz “Thread history access has expired”

Um gerente do Space precisa executar @Cuneiform Chat /connect de novo para reautorizar. Isso acontece quando o token OAuth do Google é revogado (por exemplo, nas configurações da conta do Google).

Segurança

• Verificação de propriedade do domínio — um TXT record de DNS prova que sua organização é dona do domínio antes da conexão
• Detecção do Google Workspace — a verificação de registro MX confirma que seu domínio usa Google Workspace
• Isolamento por domínio — apenas usuários do Google Workspace da sua organização podem interagir com seu bot
• Verificação de webhook — toda requisição recebida é validada contra o projeto do Google Cloud da sua plataforma
• Os códigos de verificação são de uso único e vinculados ao seu domínio
• As mensagens são processadas por conexões seguras e criptografadas

Desconectando

Para remover a integração com Google Chat:

1. Vá para Integrations na barra lateral
2. Encontre o card da sua integração com Google Chat
3. Clique no menu de três pontos
4. Selecione Disconnect

Notas Importantes

• Google Workspace obrigatório: Contas pessoais do Gmail não podem usar esta integração. Se sua organização não usa Google Workspace, a seção do Google Chat não vai aparecer.
• Verificação de domínio obrigatória: Verifique seu domínio em Settings > Domains antes de conectar o Google Chat.
• Uma integração por organização: Cada organização pode ter uma integração com Google Chat
• Apenas texto: O bot não suporta imagens, arquivos nem botões interativos
• Gerenciado no nível da organização: O Google Chat é configurado na página Integrations, não por agent
• Roteamento de Spaces: Use /set-agent em Spaces para atribuir agents especializados a equipes diferentes
• Agent padrão: Mude o agent padrão a qualquer momento usando a lista suspensa — sem precisar desconectar