Agente de IA para Atendimento no WhatsApp

Este guia monta uma jornada completa de atendimento: preparar o agente, escolher uma integração do WhatsApp, definir quem recebe cada conversa e validar o canal real. A disponibilidade contínua depende da conexão com o provedor e das regras de roteamento configuradas; não é uma garantia de resposta sem falhas.

Resultado esperado

Ao terminar, você terá:

um agente ativo, com comportamento e limites definidos no prompt;
uma caixa conectada a uma das cinco integrações atuais do WhatsApp;
um destino padrão e, se necessário, horários alternando IA e atendimento humano;
um caminho explícito para transferência humana;
uma conversa real de entrada e saída validada no WhatsApp.

Antes de começar

Você precisa de permissão para editar agentes e caixas. Se Novo Agente, Conectar caixa de entrada ou os controles de edição não aparecerem, peça ao administrador da organização o acesso correspondente.

Prepare também a conta e as credenciais da integração escolhida. A API Oficial usa o fluxo da Meta e um número do WhatsApp Business; Z-API, UAZAPI e Evolution usam a conta ou instância que você mantém nesses provedores.

Escolha a integração

Em Caixas de entrada, Escolha o canal mostra cinco opções. Estes são os nomes atuais da interface:

Opção	Quando usar	O que preparar
WhatsApp	Validação por QR Code. A interface identifica esta opção como somente para testes.	Celular disponível para ler o QR Code.
WhatsApp Oficial	API oficial da Meta com número verificado.	Conta Meta e número do WhatsApp Business; o fluxo pode pedir o PIN de verificação em duas etapas.
WhatsApp (Z-API)	Conta própria na Z-API.	ID da instância, token da instância e token de segurança do cliente.
WhatsApp (UAZAPI)	Conta própria na UAZAPI.	URL base e token da instância.
WhatsApp (Evolution)	Instância própria da Evolution.	URL base, nome da instância e chave de API.

Configure o atendimento

Crie e salve o agente

Abra Agentes, selecione Novo Agente, informe o nome e confirme em Criar Agente. No desktop, o novo agente abre o editor com o AgentMaker; você também pode fechar o copiloto e editar diretamente.

Em Prompt, descreva papel, tom, limites, informações que nunca devem ser inventadas e situações que exigem uma pessoa. Escolha um modelo disponível, mantenha o agente ativo e use Salvar alterações. Consulte Criando Agentes e Prompts de Sistema.
Adicione conhecimento quando necessário

Em Conhecimento, selecione as bases pertinentes e escreva uma instrução compartilhada. O runtime decide quando chamar search_knowledge_base; ele não consulta todos os documentos em toda mensagem. Confirme que os itens estão processados e teste perguntas cuja resposta exista no conteúdo. Veja Conectando Bases a Agentes.
Defina a transferência humana

Adicione a ferramenta nativa Transferir Conversa quando o agente precisar encaminhar casos específicos. Configure condições e destinos válidos, explique no prompt quando transferir e teste um caso que transfere e outro que permanece com a IA. Veja Transferir Conversa.
Conecte a caixa do WhatsApp

Abra Caixas de entrada, selecione Conectar caixa de entrada e escolha uma das cinco opções em Escolha o canal.
- No QR Code, leia o código antes do prazo exibido e aguarde a conexão.
- Na API Oficial, conclua o fluxo da Meta e, se solicitado, o PIN de verificação em duas etapas.
- Em Z-API, UAZAPI ou Evolution, informe as credenciais, siga a configuração do provedor e conclua a verificação no SquadOS.
Consulte o guia específico: QR Code, API Oficial, Z-API, UAZAPI ou Evolution.
Escolha o destino e o nome da caixa

A conexão acontece antes da criação da caixa. Quando ela for confirmada, Quem atende esta caixa? pede o Destino e o Nome da caixa. Selecione o agente do passo 1 como destino padrão, revise o nome e use Concluir.
Configure os horários de atendimento

O SquadOS abre Horários de atendimento, etapa 2 de 2. Você pode escolher Configurar depois. Sem agenda ativa, toda nova conversa segue o destino padrão em qualquer horário. Com a agenda, defina janelas semanais, destino fora do horário e exceções; a tela também oferece SLA e retomada pela IA. Caixas de entrada explica a separação entre conexão e roteamento.
Teste a versão salva e o canal real

Abra Testar Agente. O painel usa o runtime real, pode criar conversa persistente, consumir créditos e executar ferramentas com efeitos externos. Teste conhecimento, recusa, transferência e resposta normal. Salve qualquer alteração antes de testar novamente. Veja Testando seu Agente.

Depois, envie uma mensagem de outro telefone ao número conectado. Em Conversas, confirme caixa, destino, agenda e entrega da resposta no WhatsApp. Faça também uma resposta humana e um handoff para validar a contingência.
Monitore e ajuste com evidência

Em Conversas, acompanhe responsável, estado, SLA e vez da resposta. Assumir uma conversa interrompe a automação naquele atendimento; isso não desativa o agente para as demais conversas. Leia Intervenção Humana.

Em Analytics, observe volume, créditos, desempenho por agente e SLA. Ajuste prompt, conhecimento e roteamento a partir das conversas reais, não apenas do teste isolado.

Regra de 24 horas da API Oficial

A janela da Meta se aplica somente ao WhatsApp Oficial. Nas 24 horas após a última mensagem do cliente, a equipe pode responder com texto livre. Fora da janela, uma nova mensagem exige um modelo aprovado. Quando disponível para sua organização, o catálogo fica em Configurações → Modelos do WhatsApp; a conversa também oferece o envio de modelo quando ele é obrigatório.

QR Code, Z-API, UAZAPI e Evolution não usam a janela nem os modelos da Cloud API dentro do SquadOS. Ainda assim, cumpra as políticas e o contrato do provedor.

Checklist antes de liberar o número

O agente está ativo e as alterações foram salvas.
Perguntas com e sem resposta na base foram testadas.
A transferência humana tem destino válido e foi exercitada.
Destino padrão, agenda e destino fora do horário foram revisados.
Uma mensagem real entrou pela caixa correta e recebeu resposta no WhatsApp.
A equipe sabe assumir, transferir, concluir e reabrir uma conversa.
Na API Oficial, há modelos aprovados para uso fora da janela de 24 horas.

Diagnóstico rápido

Sintoma	Verifique
Novo Agente ou Conectar caixa de entrada não aparece	Permissões de escrita para Agentes e Caixas de entrada.
O agente não responde	Estado ativo, versão salva, créditos, destino e agenda atual.
O conhecimento não aparece	Vínculo da base, item processado, instrução e teste de recuperação.
A conversa caiu com destino inesperado	Destino padrão, janela semanal, exceção e destino fora do horário.
A API Oficial não permite texto livre	Hora da última mensagem do cliente e modelo aprovado.
O canal conecta, mas não entrega	Status, credenciais, webhook ou sessão no provedor e logs da conversa.