Coleta do Google Meet

Esta página descreve, detalhe por detalhe, como a Onvox AI coleta reuniões do Google Meet: desde o app OAuth até a análise atribuída ao vendedor certo. Para a matriz de quem-pode-o-quê, veja Permissionamento.

Visão geral do modelo

O fluxo tem dois níveis, propositalmente separados:

1. App OAuth (o global, pelo super_admin; ou o próprio do tenant, pelo admin_company). Define o client_id/client_secret do Google e o Redirect URI. É o "aplicativo" que o Google reconhece.
2. Conexão por usuário (self-service). Cada pessoa conecta a própria conta Google contra esse app, liberando a leitura das transcrições das reuniões dela e faz a coleta atribuir as reuniões a ela.

O app OAuth de plataforma

• Global e compartilhado. Existe um app OAuth global para toda a plataforma (o padrão). Ele mora num tenant de sistema fixo com o nome do produto ("Onvox AI"), uma empresa reservada usada só como espaço de configuração. O super_admin autentica o app global selecionando esse tenant na mesma tela de Integrações → Google Meet.
• Quem cadastra: o app global, só o super_admin, pelo menu/UI (compliance), em "Credenciais (app global)". O app próprio do tenant, o admin_company da própria empresa (ou o super_admin, com a empresa selecionada), em "Credenciais (OAuth próprio)"; desse formulário só o client_id/ client_secret são gravados. A variável de ambiente GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET fica como fallback opcional.
• Precedência de resolução do app: app próprio do tenant → app global (tenant de produto) → env. Ou seja, se um tenant tiver um app próprio cadastrado, ele usa o dele; senão, herda o global.
• Remover app próprio: o admin_company (ou o super_admin) remove o app do tenant e a empresa volta ao app global. Os tokens emitidos pelo app próprio param de renovar: essas contas caem em "Precisa de ação" e os usuários precisam reconectar a própria conta.
• Redirect URI: o Google exige registrar a URL de callback exata do Onvox AI no Google Cloud Console. Ela aparece no próprio diálogo de credenciais (botão Copiar) e muda por ambiente. Sem isso, a conexão falha com redirect_uri_mismatch.

Pré-requisitos do app no Google Cloud (consentimento, publicação, verificação)

• Tela de consentimento = "Externo" (External). O tipo "Interno" só funciona para contas do mesmo Google Workspace da empresa dona do app. Como os usuários reais (clientes/parceiros, ex.: @omniassessoria.com.br) são de fora desse Workspace, o app precisa ser Externo, senão essas contas nem aparecem para autorizar.
• App em "Testing" (teste): só os e-mails adicionados como Usuários de teste (máx. 100) conseguem autorizar; qualquer outro recebe 403: access_denied. Além disso, em Testing com escopo sensível o refresh token expira a cada 7 dias → a coleta em background para toda semana e o usuário precisa reconectar na mão (não há como renovar um refresh vencido, nenhum ajuste no Onvox AI resolve isso).
• Para uso real, publique o app "Em produção" e envie-o para verificação. O escopo do Meet (meetings.space.readonly) é sensível, então a verificação exige marca/logo, política de privacidade, homepage e o domínio verificado. Em produção o refresh é perene e some o limite de 100 contas. (É possível publicar antes de a verificação concluir; funciona com o aviso "app não verificado", até 100 usuários.)

Conexão por usuário (self-service)

Cada usuário conecta a própria conta em Configurações → "Conectar meu Google Meet":

• Quem conecta: admin_company e vendedor SIM; supervisor NÃO. (O super_admin não tem reuniões próprias, portanto não se aplica.)
• O que acontece: ao autorizar, o token OAuth é gravado cifrado por usuário (user_integration_config). A partir daí as reuniões daquela conta passam a ser coletadas e atribuídas àquele usuário.
• Auto-correção (sem depender do suporte): no mesmo card, quem já está conectado pode Desconectar e Conectar de novo a qualquer momento, por exemplo, para corrigir uma conta errada. Ambas as ações são escopadas à sessão do próprio usuário.
• Apagar a conexão de outro usuário (ação de suporte) é exclusiva do super_admin.

Data de corte da coleta (collectSince)

• Guardado em integration_config.credentials.collectSince (ISO, cifrado).
• Inicializado na conexão (collectSince = agora, se ainda não houver valor).
• Editável depois: campo "Coletar a partir de" no card conectado.

Polling automático (a cada ~5 min)

• A coleta é automática por polling: o sistema busca automaticamente, a cada ~5 minutos, reuniões/transcrições novas desde collectSince (não incremental desde a última varredura, relista tudo desde o corte a cada ciclo e confia no dedup por externalCallId pra não duplicar análise).
• Para cada transcrição encontrada: baixa o texto, monta os participantes, cria a análise e a atribui (ver abaixo).
• Como relista desde o corte a cada ciclo, uma parada não perde reunião no modo Total diário: quando a conta volta a coletar, as reuniões do período parado entram no ciclo seguinte. Nos modos Quantidade e Amostragem, só o dia corrente conta. Instabilidade do Google e falha de rede entram em retentativa automática, sem bloquear a conta. O que acontece em cada caso, e como desbloquear, está em Sincronização e recuperação da coleta.

Espaços monitorados (opcional)

• Além do polling automático das conexões, é possível registrar espaços monitorados (salas específicas do Meet), recurso opcional/manual.
• A lista mostra o link meet.google.com (resolvido via spaces.get) em vez do id spaces/..., com paginação, e um botão para carregar o endereço e as transcrições.
• Só pra espaços monitorados (diferente do polling principal acima): o limite inferior usado é o maior entre a última varredura daquele espaço e collectSince; aqui sim é incremental.

Transcrição com locutor por frase

• Coleta: o transcript é salvo no formato displayName: frase (nome de exibição do participante via participants.list; id curto quando não há nome).
• Exibição correlacionada: na leitura da análise, se houver correlação identificador↔usuário, o rótulo do locutor é trocado pelo nome oficial do usuário do Onvox AI. A troca é só na visão do leitor, pois o texto original permanece intacto.
• O nome do Google é sempre trazido e persistido, mesmo sem correspondência com um usuário cadastrado. A correlação apenas substitui o nome na exibição quando existe.

Contatos reutilizáveis

Para mapear uma vez e valer para todas as reuniões, os participantes vistos nas coletas viram contatos persistentes:

• Tabela integration_contact por (company_id, provider, external_id): o external_id é o People-id do Meet. Guarda display_name, o user_id mapeado, seen_count e first/last_seen_at.
• A cada coleta, os contatos têm a recorrência incrementada e o nome atualizado, sem sobrescrever o mapeamento já feito.
• Na tela de Integrações há a seção "Contatos do Google Meet": lista com "visto Nx"
  • um seletor de usuário por contato (mapear/desmapear).

Atribuição (de quem é a reunião)

Ao registrar a análise, a Onvox AI resolve o dono nesta ordem:

1. Mapeamento de vendedor (salesperson_mapping / contato mapeado).
2. Identidade externa do usuário: o e-mail do Google cadastrado no usuário (googleMeetEmail).
3. Supervisor padrão do tenant (mais antigo): quando nada casa, a análise é auto-correlacionada ao supervisor já no registro (status auto_supervisor). Sem supervisor no tenant → pending.

Limites da API do Meet

• A correlação robusta por e-mail depende do mapeamento manual (campo "E-mail/login do Meet" no cadastro do usuário) ou do salesperson_mapping/contato mapeado.