Intervenção Humana

O que é

Ferramenta nativa que permite ao agente encerrar o próprio atendimento e transferir a conversa para um humano. Quando acionada, dois efeitos acontecem em sequência:

1. O SquadOS dispara um webhook HTTP para a URL que você configurou, com os dados da conversa.
2. A conversa fica com a IA desligada (ai_enabled = false) — o agente para de responder até que alguém reative manualmente.

Quando usar

• Atendimento de suporte onde o agente lida com perguntas comuns mas precisa passar casos complexos para um humano.
• Vendas com qualificação automática seguida de transferência para um SDR humano.
• Conversas com sinais de frustração, urgência ou reclamação séria.
• Casos fora do escopo do agente que exigem julgamento humano.

Configuração

1. Na aba Ferramentas do agente, clique em + Adicionar Ferramenta.
2. Em FERRAMENTAS NATIVAS, escolha Intervenção Humana.
3. Preencha a URL do webhook — precisa começar com https:// (HTTP simples não é aceito) e ser uma URL completa.
4. Clique em Salvar.

A URL receberá um POST com o payload da conversa toda vez que o agente decidir transferir. Tipicamente você aponta para:

• um endpoint no seu CRM/helpdesk (Zendesk, Freshdesk, etc.);
• um webhook do Zapier / Make / n8n que dispara notificação em Slack, e-mail ou WhatsApp;
• seu próprio backend que cria um ticket interno.

Payload do webhook

O POST inclui contexto da conversa, dados do agente, motivo informado pelo modelo e as últimas 10 mensagens. Use esse payload para criar um ticket ou notificar o atendente certo.

Como o agente invoca

O agente decide chamar essa ferramenta quando:

• o usuário pede explicitamente para falar com um humano;
• a conversa demonstra que a IA não está resolvendo;
• o prompt do agente orienta a transferir em situações específicas (por exemplo, “se o usuário quiser cancelar a assinatura, sempre transfira para um humano”).

Após a transferência, a IA fica totalmente silenciosa nessa conversa — qualquer nova mensagem do usuário não receberá resposta automática.

Reativar a IA

Para a IA voltar a responder na conversa transferida:

• No painel de conversas em Conversas, abra a conversa e religue a IA.
• Ou via API, atualize conversations.ai_enabled = true.

Limitações e notas

• URL precisa ser HTTPS. HTTP simples não é aceito (o formulário valida e bloqueia o salvamento).
• Webhook não tem retry automático. Se sua URL falhar, o evento é perdido — implemente idempotência e log do seu lado.
• Sem resposta visível para o usuário por padrão. Configure o prompt para o agente avisar o usuário antes de transferir (“vou te passar para um atendente humano agora”).
• Funciona em qualquer canal. Hub interno, WhatsApp, Telegram, widget web, URL pública, API — todos respeitam o ai_enabled = false.