Intervenção Humana

A intervenção humana permite que um admin entre numa conversa em andamento, pause o agente e responda diretamente ao usuário final. É útil quando o agente trava, quando o caso precisa de julgamento humano, ou quando o cliente pede explicitamente para falar com alguém.

Quando intervir

• O agente não está entendendo o pedido depois de várias tentativas.
• O caso envolve uma decisão sensível (reembolso fora do padrão, problema delicado, escalonamento).
• O usuário pediu para falar com uma pessoa.
• O agente acionou a ferramenta Intervenção Humana automaticamente.

Conversas internas (do próprio Hub) não recebem intervenção — o painel admin entra em modo somente leitura. Intervenção só faz sentido em canais externos: chat público, widget, WhatsApp, Telegram e API.

Assumir uma conversa

1. Abra a página Conversas no painel admin e selecione a conversa que você quer assumir.
2. No header do chat, clique em Intervir.

3. Confirme no modal:

“Intervir na conversa? O agente de IA será pausado e você poderá responder diretamente ao usuário. O usuário verá suas mensagens como se fossem do agente.”

4. O agente é pausado imediatamente nessa conversa específica.

A partir desse momento aparece um compositor no rodapé e a notificação “Intervenção ativada”. O botão Intervir vira Devolver no header.

Tudo que você digitar é enviado para o usuário final pelo mesmo canal que ele está usando — se ele está no WhatsApp, sua resposta chega no WhatsApp; se está no chat público do site, chega no chat público.

Como o usuário vê sua mensagem

Sua resposta aparece para o usuário como se fosse do agente — mesmo nome, mesmo avatar. Isso é proposital: o usuário não precisa saber que tem um humano respondendo. Internamente a mensagem fica marcada com sent_by_admin: true, então no histórico admin dá para distinguir.

Quando o próprio agente pede ajuda — ferramenta Intervenção Humana

O agente também pode pausar a si mesmo quando perceber que precisa de ajuda. Isso é feito pela ferramenta nativa Intervenção Humana:

• O agente chama a ferramenta quando decide que é hora de escalar.
• O SquadOS dispara um POST para a URL de webhook configurada na ferramenta, com contexto da conversa, dados do agente, motivo do handoff e as últimas mensagens.
• O agente para de responder nessa conversa (ai_enabled vira false) até alguém reativar manualmente.

Configure a ferramenta em Agentes -> [agente] -> editar -> Ferramentas -> Intervenção Humana com a URL HTTPS do seu CRM, n8n, Zapier ou sistema interno. Ative essa ferramenta quando quiser que o próprio agente saiba pedir ajuda.

Devolver controle ao agente

Quando terminar o atendimento:

1. No header da conversa, clique em Devolver.
2. O agente volta a responder automaticamente às próximas mensagens.

Não há confirmação nesse caminho — é uma ação segura e reversível. Se quiser intervir de novo depois, é só clicar em Intervir outra vez.

Caso especial: canal API

Conversas do canal API não têm o botão Intervir no header, porque o fluxo da API é iniciado por outro sistema. Quando uma conversa API está pausada (normalmente via ferramenta Intervenção Humana), aparece um banner amarelo no topo com o botão Reativar agente — use ele quando o handoff externo terminar.

Boas práticas

• Avise que você vai assumir quando demorar a entrar — o usuário pode estar esperando o agente responder.
• Conclua a conversa depois de resolver, em vez de só devolver para o agente. Veja Estados de Conversa.
• Use anotações para registrar contexto que outros admins ou o próprio agente precisem saber depois. Veja Notas Internas.
• Não deixe o agente pausado esquecido — uma conversa em intervenção não recebe respostas automáticas, então se o admin sumir o usuário fica sem resposta.