Referência Técnica

Avancado

Nota

Esta página contém detalhes técnicos destinados a administradores e integradores. Para o guia de uso, consulte Como Usar.

Configurações

Configuração	Descrição	Padrão
Email:Enabled	Ativa/desativa monitoramento de email	-
Email:Provider	Provedor de email (graph ou imap)	-
Email:Mailbox	Endereço de email do bot	-
Email:PollIntervalMinutes	Frequência de verificação da caixa de email	~5 min
Email:RecurrenceHorizonDays	Horizonte de expansão de reuniões recorrentes	7 dias
JoinLeadTime	Antecedência de entrada na reunião	15 seg
DedupTolerance	Tolerância para deduplicação de reuniões	5 min
FallbackMeetingDuration	Duração assumida se desconhecida	4 horas
MaxWaitMinutes	Tempo máximo de espera em reunião vazia	Configurável

---

Detecção de Convites

O sistema processa até 25 mensagens não lidas por ciclo de polling. Para cada mensagem, a detecção do convite segue esta ordem de prioridade:

1. Anexos ICS no email
2. ICS embutido no conteúdo MIME
3. EventMessage da Graph API (quando ICS não e encontrado)

Dados Extraidos

• URL da reunião: padrões /l/meetup-join/ (legado) e /meet/ (atual)
• Horarios das ocorrências
• Duração da reunião
• Informações de recorrência (RRULE)
• Meeting ID e Passcode (extraidos do corpo do email como fallback)

Se nenhum horário for encontrado, a reunião é agendada imediatamente (com delay de 10 segundos).

---

Resolução de Webhook

Dois caminhos possíveis para resolver o destino da transcrição:

Webhook Explicito

O padrão {{webhook:https://...}} no corpo do email é detectado é utilizado diretamente. Não exige cadastro do remetente no Prodgy.

Lookup Automático (via Prodgy API)

1. Identifica o remetente

   • Em emails encaminhados: tenta FromAddress primeiro, fallback para SenderAddress

2. Verifica cadastro no Prodgy

   • Usuário não encontrado → rejeita

3. Resolve o workspace

   • Um workspace → usa automaticamente
   • Múltiplos workspaces → busca notação [NomeProduto] no título da reunião
   • Notação não encontrada com múltiplos workspaces → rejeita

4. Valida o agente

   • Agente não instalado → rejeita
   • Sem versão ativa → rejeita
   • Sem trigger de webhook configurado → rejeita

5. Retorna dados

   • webhookUrl, userId, orgId, productId, agentBaseId

---

Deduplicação e Agendamento

Antes de agendar, o sistema aplica estas validações em sequência:

1. Reunião já encerrada? — Verifica se horário + duração < agora (duração fallback: 4 horas)
2. Ocorrência cancelada? — Verifica na lista de cancelamentos (URL + horário, tolerância de 5 minutos)
3. Ja agendada? — Mesma URL + horário com tolerância de 5 minutos → faz merge do novo target
4. Bot já em chamada ativa? — Adiciona target na chamada ativa sem novo agendamento
5. Todas validações passam — Cria ScheduledMeeting, persiste no Redis, posta meeting_scheduled

Aceitação Automática de Convite

Após agendar, o bot tenta aceitar o convite no calendário via provedor de email. Execução assíncrona — falhas não bloqueiam o agendamento.

---

Reuniões Recorrentes

• Detecta recorrência via RRULE (ICS) ou PatternedRecurrence (Graph API)
• Expande ocorrências futuras dentro do horizonte configurado (RecurrenceHorizonDays)
• Re-expansão automática: a cada 12 horas, recalcula próximas ocorrências
• Multi-usuário: merge de targets quando múltiplos usuários encaminham o mesmo convite recorrente

---

Politica de Retry — Entrada na Reunião

Tentativa	Espera
1a falha	10 segundos
2a falha	30 segundos
3a falha	60 segundos

Após 3 falhas consecutivas, o sistema posta evento meeting_error.

Antes de cada tentativa, o bot re-válida todos os targets. Usuários desativados desde o agendamento são removidos. Se nenhum target válido restar, o join e cancelado.

---

Politica de Retry — Entrega de Webhook

Tentativa	Espera
1a falha	5 segundos
2a falha	15 segundos
3a falha	45 segundos

• Cada target e entregue independentemente — falha em um não bloqueia os demais
• Se 0 segmentos e 0 participantes: webhook não é enviado
• Backup local salvo em logs/transcripts/ antes da entrega
• Arquivo de backup removido após entrega bem-sucedida

---

Idioma da Transcrição

O idioma da transcrição é resolvido por uma cascata de prioridade:

Prioridade	Fonte	Comportamento
1	{{lang:xx}} no email	Força o idioma especificado (ex: en, pt, es)
2	Auto-detect	Modelo identifica o idioma automaticamente a partir do áudio

Quando {{lang:xx}} é especificado, o código BCP-47 é enviado ao modelo de transcrição e o prompt de contexto (nomes de participantes, continuação) é adaptado para o idioma correspondente.

Quando nenhum idioma é especificado (padrão), o campo language não é enviado ao modelo, permitindo que ele detecte automaticamente o idioma a partir do áudio. Isso funciona bem para idiomas comuns (português, inglês, espanhol, francês, alemão) e suporta reuniões multilíngues.

---

Persistência e Recuperação (Redis)

O sistema persiste todos os estados no Redis:

Dado	Descrição
Reuniões pendentes	Reuniões agendadas aguardando entrada
Padrões de recorrência	Regras de expansão de reuniões recorrentes
Ocorrências canceladas	Lista de cancelamentos detectados
Mapeamento chamada ↔ reunião	Vinculo entre call_id e sessão

Comportamento na Reinicialização

1. Carrega ocorrências canceladas
2. Carrega padrões de recorrência
3. Reseta reuniões orfas (status joined → pending)
4. Restaura reuniões pendentes e recria timers
5. Limpa reuniões passadas obsoletas

---

Histórico de Eventos — API

Consulta

GET /api/meeting-events

Parâmetro	Tipo	Descrição
organization_id	obrigatório	Filtra por organização
event_type	opcional	Tipo de evento (ex: meeting_joined)
status	opcional	Status (completed, failed)
start_date	opcional	Data inicial (ISO 8601)
end_date	opcional	Data final (ISO 8601)
limit	opcional	Limite de resultados (padrão: 200)
offset	opcional	Offset para paginação

Resultados ordenados por data de criação (mais recente primeiro).

Streaming em Tempo Real (SSE)

GET /api/meetings/history/stream

• Cada novo evento dispara notificação via Server-Sent Events
• Sem necessidade de polling

Resiliência do Registro

O registro de eventos usa semântica fire-and-forget: falhas no registro nunca bloqueiam o fluxo da reunião.