Usando no Google Chat

Guia

Dica

O Prodgy se integra ao Google Chat via HTTP endpoint. Os usuários conversam com o bot em Spaces ou DMs e recebem respostas da Knowledge Base do workspace.

Pré-requisitos

• Google Workspace com permissão para criar apps
• Projeto no Google Cloud Console
• Produto cadastrado no Prodgy com Knowledge Base configurada
• Organização com modelo de IA (LLM) configurado
• API do Prodgy acessível publicamente via HTTPS

---

Configuração

1. Habilitar a Google Chat API

1. Acesse o Google Cloud Console
2. Selecione ou crie um projeto
3. Vá em APIs & Services > Enable APIs
4. Busque e habilite a Google Chat API

2. Configurar o Chat App

1. Na Google Chat API > Configuration, preencha:

   Campo	Valor
   App name	Ex: Prodgy Bot
   Avatar URL	URL do logo do Prodgy
   Description	Assistente IA integrado à Knowledge Base
   Functionality	Marque: Receive 1:1 messages e Join spaces and group conversations
   Connection settings	HTTP endpoint URL
   HTTP endpoint URL	https://<sua-api>/api/communicator/webhook/<integration_base_id>

3. Criar Service Account

Para que o bot possa enviar e atualizar mensagens:

1. Vá em IAM & Admin > Service Accounts
2. Crie uma service account (ex: prodgy-chat-bot@project.iam.gserviceaccount.com)
3. Gere uma chave JSON
4. Guarde o arquivo JSON — será usado como credencial

4. Criar a Integração no Prodgy

1. No Prodgy, acesse Integrações

2. Adicione uma nova integração do tipo Google Chat (classificação: comunicador)

3. Preencha as credenciais:

   Campo	Valor
   Bot Token	OAuth token ou token da service account
   Service Account Key	JSON da service account (opcional)

5. Exportar o Produto

1. Acesse o Playground do workspace desejado
2. Clique em Exportar e selecione a integração Google Chat
3. Opcionalmente, informe um Space ID para criar mapeamento automático
4. O sistema gera a Webhook URL para configurar no Google Cloud

6. Publicar o App

1. Para testes: publique como App available to specific people in your domain
2. Para produção: publique no Google Workspace Marketplace (requer aprovação do Google)

---

Testando

DM com o Bot

1. No Google Chat, busque o bot pelo nome em Encontrar pessoas, salas e bots
2. Envie uma mensagem direta

Em um Space

1. Adicione o bot ao Space desejado
2. Mencione o bot ou envie uma mensagem no Space

Primeiro uso

1. Envie login para vincular sua conta Prodgy
2. Clique no link e autentique pelo navegador
3. Envie list para ver os workspaces disponíveis
4. Envie link <slug> para selecionar um workspace
5. Envie suas perguntas normalmente

Nota

No Google Chat, os comandos podem ser enviados sem o prefixo /prodgy em conversas diretas com o bot.

---

Comportamento

Indicador de Processamento

1. O bot envia “Pensando…” imediatamente
2. O Agentic processa a mensagem
3. A mensagem é atualizada com a resposta final (via PATCH na API do Google Chat)

Formatação

O adapter converte automaticamente o Markdown para o formato do Google Chat:

Markdown	Google Chat
**negrito**	*negrito*
*itálico*	_itálico_
[texto](url)	[texto](url) (mantido)
# Título	*Título*
- item	• item

Payload de Entrada

O Google Chat envia eventos no formato:

{
  "type": "MESSAGE",
  "message": {
    "text": "Olá, bot!",
    "sender": {
      "name": "users/123456",
      "displayName": "João Silva"
    }
  },
  "space": {
    "name": "spaces/AAAA_BBBB"
  }
}

---

Multi-Produto

• Cada usuário seleciona seu workspace ativo via link <slug>
• Spaces podem ser mapeados a produtos específicos pelo administrador
• Se não houver mapeamento nem seleção, o bot usa o primeiro workspace acessível

---

Troubleshooting

Bot não responde

• Verifique se a Google Chat API está habilitada no projeto
• Verifique se o HTTP endpoint URL está correto e acessível
• Verifique se o app está publicado (pelo menos para o domínio)
• Confirme que as credenciais estão corretas no Prodgy

Erro de autenticação ao enviar resposta

• Verifique se a service account tem permissão para enviar mensagens
• Renove o token OAuth se expirado
• Verifique se o token tem os scopes chat.bot ou chat.messages

Bot só funciona em DM

• Verifique se Join spaces and group conversations está marcado na configuração do Chat App
• O bot precisa ser adicionado ao Space manualmente

Mensagem fica como “Pensando…”

• A atualização de mensagem via PATCH requer token válido
• Se o update falhar, o bot envia automaticamente uma nova mensagem como fallback
• Verifique se o token da service account está atualizado

Resposta demora muito

• O timeout padrão é 30 segundos
• Reduza maxIterations nas configurações avançadas do comunicador
• Verifique a latência do serviço Agentic