Como a EvoluAI coleta ligações do PABX Yeastar detalhe por detalhe — opt-in por ramal, janela recente com cache, amostragem, atribuição por ramal e retroativo, limite de tokens e a nova Coleta por Tags.

Coleta — Yeastar

Esta página descreve, detalhe por detalhe, como a EvoluAI coleta ligações do PABX Yeastar (P-Series). Para quem-pode-o-quê, veja Permissionamento.

Conexão e credenciais

A integração usa a credencial de API do PBX (client_id/client_secret), guardada cifrada em integration_config.
Modo de conexão na UI: HTTPS, HTTPS autoassinado ou HTTP.

A tela de configuração em 4 níveis

A configuração do Yeastar é organizada em quatro abas, do mais simples ao mais avançado — você só desce de nível se precisar. O Yeastar aparece por empresa (ao selecionar uma empresa na tela de Integrações); ele não faz parte da configuração global do Google Meet.

Básico — cadastra os dados do PABX (URL, modo de conexão, client_id/ client_secret) e salva. Também: Coletar agora, Ativar/Desativar e Apagar autenticação.
Intermediário — Coletar desde (data de corte), amostragem/duração/escopo (o modo de coleta), Buscar no Yeastar + lista de gravações, Importar ramais, Correlação de vendedores e Atribuição pendente.
Avançado — Tipos de chamada, Controle de custo (opt-in/negar coleta, faixas, blacklist, criar-contas automaticamente), Webhook, Auto-enriquecer nomes, Buscar chamada (CDR manual) e Coletas agendadas.
Tags — a Configuração 2 (coleta por tags da empresa).

Os três primeiros níveis editam a mesma configuração no banco. Cada aba mostra só uma parte dos campos, mas salvar em uma aba não zera os campos das outras — o painel lê e regrava a config inteira. Depois de salvar, todas as abas reexibem o valor atual.

Básico: "salvar → já coleta"

Ao cadastrar o PABX pela primeira vez, o botão Salvar já ativa a integração e liga a coleta no modo amostragem padrão (3 chamadas por agente/dia, mín. 120s, escopo automático). Ou seja, o caminho simples é só cadastrar e salvar — a coleta começa sozinha, sem passar pelos outros níveis.

Isso concilia o comportamento com o controle de custo (a coleta nasce em opt-in por padrão, ver abaixo): o Básico deliberadamente opta pela amostragem — um padrão de baixo custo — enquanto o Avançado continua permitindo negar a coleta, restringir a ramais/faixas e configurar a blacklist. Editar as credenciais depois (integração já configurada) não mexe na configuração de coleta existente.

Data de corte da coleta (`collectSince`)

Nada anterior à conexão é coletado. Ao conectar, grava-se a data/hora como marco de corte; ligações anteriores não entram. É editável depois no campo "Coletar desde".

Controle de custo — coleta é OPT-IN (default-deny)

Coletar consome transcrição (STT) + análise (LLM) + créditos. Por isso a coleta do Yeastar é deliberada: por padrão nenhum ramal é coletado até alguém apontar quais.

No card do Yeastar, bloco "Controle de custo — coleta de ramais":

Negar coleta de ramais — nasce LIGADA (ON) para toda empresa. Enquanto ligada, nada é coletado. O supervisor/admin desmarca para poder coletar e, ao desmarcar, é obrigado a escolher quais ramais entram.
Ramais a coletar — seleção individual (lista viva do PBX) e/ou por faixa/range (ex.: 1000-1019, 3000-3005).
Blacklist (avançado) — ramais/faixas que nunca entram na auto-criação de contas nem são coletados enquanto não tiverem conta (suporte, URA, salas, testes).

Semântica da blacklist

A blacklist mira o fluxo do admin (buscar ramais → criar contas → coletar por usuário); não é um kill-switch geral:

Sempre bloqueia a AUTO-criação/correlação de conta no "Importar ramais".
NÃO bloqueia contas já criadas. Ramal da blacklist que já tem usuário continua coletando (a coleta é por usuário).
Bloqueia a coleta apenas de ramais SEM conta.

Criar contas de vendedor automaticamente

Interruptor geral da auto-criação (config autoCreateAccounts, default true):

Ligado: ao coletar (ou no "Importar ramais"), as contas dos ramais novos são criadas (senha temporária, trocada no 1º login).
Desligado: nenhuma conta é criada — o "Importar ramais" continua listando e permite vincular a usuários existentes.

Configuração de coleta — demais campos do painel

Além do controle de custo acima, o painel ⚙️ Configuração de coleta tem:

Tipos de chamada — Chamadas de usuário (com sub-opções Internas e Externas) e Conferência (sala de áudio / MeetMe). Conferência nasce desligada por padrão.
Escopo de usuários — Auto-discovery (todos os ramais elegíveis) ou Específicos (você lista os ramais). No modo opt-in, o padrão é Específicos (você escolhe).
Duração — mínima (padrão 120s, ver acima) e máxima (checkbox "Máx. ilimitado" ligado por padrão; desligue para limitar).
Modo e, no modo amostragem, Amostras por pessoa + Horário do pós-processamento.

Fora do painel, no card do Yeastar há ainda:

Auto-enriquecer nomes (sala e ramal) — ligado por padrão. A coleta consulta conference/list e extension/list e troca números por nomes no texto (ex.: "6500" → "admin (6500)", "1001" → "Fulano (1001)"). Não afeta a atribuição do vendedor (essa é pelo ramal cadastrado). Desligável se o PBX não tiver permissão nesses endpoints.

Janela recente + cache compartilhado

O PABX Yeastar não filtra por data nem por ramal do lado do servidor. Sem cuidado, o código baixaria o histórico inteiro a cada consulta (um cliente real tinha 54.680 gravações). A regra abaixo evita isso.

Vale para listar (Nova Análise) e coletar (coleta automática):

Ordenar do mais NOVO para o mais antigo (sort_by=time&order_by=desc).
Parar ao cruzar o piso de data (stopBeforeSec) — baixa só a janela [piso, agora]. O piso é: filtro de data do usuário → senão o collectSince → senão últimos 30 dias (nunca varre tudo).
Cache em memória compartilhado — um Map com single-flight (duas consultas concorrentes = uma varredura), TTL ~3 min e teto LRU. A mesma varredura serve o interativo (Nova Análise) e a coleta automática/amostragem.
Salvaguardas: maxPages+partial (janela enorme devolve as mais recentes sem erro) e requestTimeoutMs (PBX pendurado → TIMEOUT acionável).

Modos de coleta e piso de duração

Modos disponíveis (Configuração 1 — coleta padrão):

Total do dia — coleta tudo que for elegível no dia.
Quantidade — N por pessoa/dia.
Amostragem — sorteio (padrão: 3 aleatórias por pessoa/dia, no horário configurado).

Piso de duração: 120s. No sorteio da amostragem, chamadas curtas (saudação, engano, caixa postal) poluíam a amostra. Com 120s de duração mínima, só entram ligações com conteúdo real. Afeta o default de novas configs; configs já salvas mantêm o valor delas até serem regravadas.

Atribuição por ramal + retroativo

Ao registrar a análise, o dono é resolvido nesta ordem:

Mapeamento de vendedor (salesperson_mapping).
Identidade externa do usuário — o ramal cadastrado (yeastar_extension).
Supervisor padrão — sem match, vai ao supervisor (auto_supervisor).

Correlação retroativa: ao vincular um ramal a um usuário depois da coleta, as análises já coletadas daquele ramal que estavam em auto_supervisor/pending são realinhadas ao usuário. Não toca em manual nem em auto já resolvido.

Filtro "parece ramal" na atribuição pendente

A direção da chamada às vezes é classificada errada, fazendo o número externo (telefone completo) virar "dono" e aparecer como ramal a atribuir — um falso match.

Por isso, um candidato Yeastar só aparece em Atribuição pendente se o identificador parece um ramal (curto/numérico) ou bate com um ramal já cadastrado. Candidato sem dono detectado continua como atribuição manual legítima.

Importar ramais / criar contas

O botão "Importar ramais" lê os ramais direto do PBX (número, nome, e-mail) e concilia com os usuários da empresa pelo e-mail. Por ramal você decide: Vincular, Criar ou Ignorar. No cadastro do usuário, o campo "Ramal / login do Yeastar" é um menu com os ramais do PBX — ao escolher, nome e e-mail são preenchidos sozinhos.

Polling × webhook

Polling (padrão): a coleta automática varre a janela recente. Não depende de webhook.
Webhook (opcional, tempo real): grupo expansível "Webhook (opcional)" com toggle (que pausa o polling) + URL/segredo.

Transcrição (sem diarização)

No Yeastar não há diarização: o STT (Whisper, via OpenRouter) devolve texto corrido, sem separar locutores. A atribuição é da chamada toda à pessoa do ramal — diferente do Meet, que traz "quem falou" por frase.

Limite de tokens (8 / 30 min) e token-store

O Yeastar P-Series impõe, por credencial de API: 8 tokens simultâneos (o 9º get_token retorna errcode 60002), 30 min de expiração do access token e 24 h do refresh. São limites de sistema, não configuráveis, e há uma única credencial por PBX.

A EvoluAI minimiza a pegada a ~1 token por PBX/processo com um token-store compartilhado (Map singleton + single-flight + refresh proativo). Um único token atende requisições ilimitadas em paralelo — por isso um pool de tokens não aumenta vazão (só desperdiça slots).

Coleta por Tags (Configuração 2)

O Yeastar tem DUAS configurações (comportamentos) independentes — mesmo sistema, dois fluxos distintos. Você pode ligar só a 1, só a 2, ambas (rodam em paralelo, com dedup por externalCallId) ou nenhuma. Uma não depende da outra.

Configuração 1 — coleta padrão: tudo acima (modos total/quantidade/amostragem + opt-in/blacklist/duração). Sem mudança de comportamento.
Configuração 2 — coleta por tags (novo): se a chamada tiver uma das tags configuradas, ela é coletada — curto-circuitando negação/escopo/duração (coleta deliberada). Tem seu próprio liga/desliga; enabled=false ou lista vazia = fluxo parado. Coleta como total do dia (tudo que casar, sem sorteio/limite por pessoa).

O que são as "tags"

As tags são os disposition codes das chamadas no Yeastar. Elas vêm do CDR (cdr/list, em call_note.disposition_code_list[].name) — não do recording/list. Não há endpoint para listar as tags disponíveis do PABX, então a lista de tags no painel é texto livre e o match é feito varrendo o CDR da janela recente.

Match: EXATO

O match é exato e sensível a maiúsculas/minúsculas e a espaços internos — só as pontas são aparadas. Escreva a tag exatamente como aparece no Yeastar.

Uma chamada entra na Fila 2 se qualquer uma de suas tags for igual (texto exato) a uma das tags configuradas.

Tags da empresa × tag pessoal

Tags da empresa (globais): valem para o tenant inteiro. Só admin_company (própria empresa) e super_admin (qualquer tenant) podem criar/editar. Na UI, um bloco/card próprio ("Ativar coleta por tags") com uma textarea "Tags a coletar (uma por linha)".
Tag pessoal (self-service): o próprio usuário informa a dele em Configurações, campo "Minha tag de coleta" (com tooltip do match exato). Ela coleta apenas as chamadas do ramal dele (yeastar_extension) que tenham essa tag — "usada para ele explicitamente, além das globais".

Modelo de dados (resumo)

Config da empresa ganha tagCollection: { enabled: boolean; tags: string[] } (default { enabled: false, tags: [] }) no mesmo blob cifrado da config de coleta. Normalização: apara pontas, remove vazias, dedupe exato — sem lower-case.
Tag pessoal: coluna yeastar_collection_tag (nullable) no usuário, editável só pelo próprio (self-service).

Regra de negócio: uma chamada é coletada se for elegível pela Fila 1 OU pela Fila 2. A Fila 2 bypassa negação/escopo/duração de propósito — é uma coleta que você pediu explicitamente por tag.

Coleta — Yeastar

On this page