Visão geral
O Maestro é o motor de IA da plataforma: alimenta o Cérebro da conta, o copiloto, os robôs e o onboarding generativo. A integração é gerenciada pelo operador no console administrativo — sem necessidade de reimplantar o serviço para alterar a configuração.
Pré-requisitos
- Acesso ao console do operador (Super Admin).
- URL interna do serviço Maestro e a chave administrativa fornecidas na implantação.
Passo a passo
- Acesse o console do operador → configurações do Maestro.
- Preencha a URL da API (endereço interno) e, se houver, a URL pública (usada nos webhooks dos robôs).
- Informe a chave administrativa — ela fica mascarada e nunca é exibida novamente.
- Escolha o modo de onboarding para novas contas: desligado, guiado (wizard) ou automático.
- Defina o modelo vertical padrão aplicado quando o cadastro não informa segmento.
- Salve e use "Testar conexão" para validar.
Configurações & opções
- Maestro habilitado: chave geral. Desligado, todas as superfícies de IA respondem com um estado claro de "desativado pelo operador" em vez de erros de conexão.
- Permitir chaves por conta (BYOK): controla se contas podem usar as próprias chaves de IA (veja o artigo "Tokens de IA por conta").
- A configuração do painel tem precedência sobre variáveis de ambiente; ambientes provisionados por variável continuam funcionando.
Pausa por atendimento humano
Quando uma conversa é assumida ou atribuída a uma pessoa, o estado de pausa é gravado de forma durável e continua válido após reiniciar a API, os workers ou o cache. A retomada só libera o robô depois de uma confirmação válida; estado desconhecido é tratado como pausado.
Cada robô também define o que reter das mensagens recebidas durante a pausa: descartar (padrão), guardar apenas a mais recente ou guardar um conjunto limitado por quantidade e idade. Retomar a conversa nunca reproduz essas mensagens sozinho. Uma eventual reprodução é uma ação separada, explícita e confirmada pelo operador.
Para processar uma fila retida com segurança:
- Remova o atendente humano da conversa, quando ele ainda estiver atribuído.
- No painel Maestro da conversa, selecione Retomar e aguarde a confirmação. Essa ação libera somente mensagens novas.
- O cartão Mensagens recebidas durante a pausa aparece apenas depois da retomada confirmada.
- Selecione Processar mensagens retidas, leia o impacto e escolha Confirmar processamento.
Cada tentativa usa um identificador único e seguro para repetição: se a resposta da rede se perder, tentar novamente não processa a mesma fila duas vezes. Sem confirmação, com estado desconhecido ou enquanto houver um atendente atribuído, a plataforma mantém a fila bloqueada.
Casos de uso
- Trocar a chave administrativa após rotação de credenciais, sem reiniciar serviços.
- Ativar o onboarding automático apenas depois de validar o guiado em contas-piloto.
Dicas, limites e boas práticas
- Rotacione a chave administrativa periodicamente e após qualquer suspeita de exposição.
- Mantenha a URL interna acessível apenas na rede privada; exponha somente a URL pública.
Solução de problemas
O diagnóstico mostra um dos cinco estados:
- OK: serviço acessível e autenticado.
- Falha de autenticação: a chave administrativa não confere com a do serviço — atualize um dos lados.
- Inacessível: a URL não responde (DNS, rede, serviço parado). O detalhe indica a causa.
- Desativado: a chave geral "Maestro habilitado" está desligada.
- Não configurado: falta a chave administrativa.
Durante Inacessível ou uma resposta inválida, respostas automáticas, ferramentas com efeito e Follow-ups configurados para respeitar o atendimento humano ficam bloqueados até o estado voltar a ser conhecido.
Se o onboarding generativo estiver ativo e o Maestro indisponível, as contas continuam sendo provisionadas com os modelos verticais — nada fica bloqueado.
Veja também
- Tokens de IA por conta (BYOK)
- Uso e limites de consumo
- Onboarding com IA