Quase todo problema com agente de IA cai em poucas causas: o agente não está ligado, o contato não está liberado, a conversa está com a equipe, a chave ou o orçamento pararam a IA, ou as instruções e os materiais não cobrem o assunto. Procure abaixo o sintoma mais parecido com o seu.
Dois lugares ajudam em quase todos os casos:
- O Diagnóstico, no topo da página do agente em IA › Agentes, lista o que está certo e o que bloqueia.
- A própria conversa na Inbox mostra avisos da IA no fim do histórico, como IA não elegível: Fora da lista de teste ou IA pausada nesta conversa · a equipe responde.
- Em IA › Casos, o alerta O agente deixou de responder N contatos por causa do acesso avisa quando contatos reais escreveram e foram barrados pelo acesso, um alerta por número ou conta do Instagram e por dia.
O agente não responde ninguém
Causa mais comum: o acesso está fechado. Todo número começa em Somente números de teste (no Instagram, Somente testadores), e se a lista de teste estiver vazia a IA não responde a ninguém.
O que fazer: em Configurações › Acesso da IA, cadastre um número de teste ou abra o acesso. Veja Liberar o acesso da IA. Esse caso nem chega a acontecer com um agente novo: a publicação é recusada enquanto o número estiver sem nenhum número de teste, e a janela Publicar versão deixa cadastrar o número ali mesmo.
O agente não está em operação. Na lista de IA › Agentes, o status precisa ser Em operação. Rascunho e Publicado, aguardando ativação ainda não atendem, e Pausado parou.
O que fazer: publique e ative o agente. Veja Criar seu primeiro agente.
Outro agente ou um roteador é o responsável pelo número. Cada número tem um só responsável. No cartão do número em Acesso da IA, a linha abaixo do modo diz quem atende agora.
O que fazer: pause o outro agente, ou inclua este agente no roteador. Veja Roteadores.
O agente só responde a certas palavras. Em Quando responde, na configuração do agente, o campo Palavras ou expressões de acionamento limita as mensagens que ele atende. Vazio, ele responde a qualquer mensagem liberada.
Está fora do horário. Com Limitar a uma janela de atendimento ligado e Fora do horário em Aguardar o próximo horário, o agente espera o horário voltar. A conversa mostra O agente aguarda o horário permitido para continuar este atendimento.
A chave ou o orçamento pararam a IA. Veja as seções sobre chave e orçamento mais abaixo.
Responde só o meu número
Causa: o número está no modo Somente números de teste. É o comportamento esperado: você testa sem risco de o agente falar com clientes antes da hora.
O que fazer: quando estiver satisfeito com os testes, em Configurações › Acesso da IA, mude para Contatos autorizados por origem ou Aberto para todos. Veja Liberar o acesso da IA.
Parou de responder um contato
Alguém da equipe respondeu na conversa. Quando uma pessoa manda mensagem manualmente, o agente sai daquela conversa para as duas respostas não se atropelarem. O mesmo acontece quando alguém clica em Pausar IA nesta conversa ou quando o próprio agente transfere para a equipe. A conversa mostra IA pausada nesta conversa · a equipe responde.
O que fazer: quando a equipe terminar, clique em Devolver à IA na conversa. Isso também libera o contato para a IA por um tempo, mesmo no modo Contatos autorizados por origem.
A conversa foi atribuída a alguém. Por padrão, a IA não responde a conversas com responsável na equipe. Ao assumir a conversa, a autorização daquele contato também é revogada.
O que fazer: tire o responsável da conversa. Se ela também estiver pausada, use Devolver à IA. Outra opção é mudar a regra em Conversas atribuídas a uma pessoa, na tela Acesso da IA.
A autorização do contato venceu ou foi revogada. No modo Contatos autorizados por origem, cada liberação tem validade. A conversa mostra IA não elegível: Autorização expirada ou IA não elegível: Contato sem autorização de origem.
O que fazer: se quiser que a IA atenda essa pessoa, clique em Autorizar este contato no aviso da conversa. Confira também a lista Contatos autorizados em Acesso da IA. O contato ganha uma nova autorização quando responde a uma transmissão, jornada ou follow-up, ou quando um atendente usa Devolver à IA numa conversa pausada. Para não depender disso, abra o número para todos.
O contato é o destinatário dos avisos de casos. O número escolhido em Configurações › Avisos de casos no WhatsApp vira interno, e os agentes não respondem a ele, mesmo com os avisos desligados. A conversa mostra a etiqueta Número interno da equipe (recebe avisos da IA).
O que fazer: em Avisos de casos no WhatsApp, clique em Remover destinatário ou escolha outro destinatário. Veja Avisos de casos no WhatsApp.
A IA não conseguiu terminar a resposta. Às vezes o agente começa a responder e para antes do fim: atingiu o Limite de tokens por execução ou o Máximo de etapas por execução, o provedor não respondeu a tempo ou recusou a chamada. Nesses casos nenhuma mensagem inventada é enviada ao contato. Se o agente pode passar para a equipe, a conversa vai para Atendimento humano e a IA fica pausada nela, como numa transferência. Se não pode, aparece em IA › Casos o alerta Um contato ficou sem resposta da IA, com o botão Abrir atendimento.
O que fazer: responda o contato pela conversa e, quando quiser, clique em Devolver à IA. Se o alerta O agente está parando pelo limite de tokens aparecer, aumente o Limite de tokens por execução no grupo Avançado do agente e publique. Cada consulta a uma ferramenta, como a base de conhecimento, reenvia a conversa ao modelo e soma nesse limite. O padrão para agentes novos é 150.000. O Limite estimado por execução e o orçamento mensal em Uso e orçamento continuam valendo.
A IA parou de responder todo mundo. Confira os alertas em IA › Casos:
- A IA parou: credencial de IA indisponível: a credencial foi desativada, removida ou não passou na validação. Revalide ou troque a chave em Configurações › Provedores e chaves.
- O provedor de IA recusou a chave: a chave foi revogada, expirou ou não tem permissão para o modelo. Gere outra no provedor e troque em Configurações › Provedores e chaves.
- IA interrompida pelo orçamento: veja Uso e orçamento.
Esses alertas valem para o roteador e para os agentes. Há um por credencial; se você marcar como resolvido e o problema continuar, ele volta a abrir. Depois da correção, a IA responde as próximas mensagens. As que chegaram enquanto ela estava parada não são respondidas sozinhas: responda pelo atendimento.
A resposta demora ou fica aguardando aprovação
O agente está no modo assistido. No modo Assistida, toda resposta espera alguém aprovar. A conversa mostra Resposta da IA aguardando aprovação.
O que fazer: clique em Aprovar e enviar ou Rejeitar na conversa, ou decida em IA › Execuções. Se quiser que ele responda sozinho, troque o modo para Automática no botão de status do agente. Veja Execuções e aprovação.
A IA não respondeu uma mensagem antiga. Se a resposta automática fosse sair mais de 30 minutos depois da mensagem do contato (por exemplo, depois de uma instabilidade), a IA não responde: a resposta chegaria fora de hora e sem contexto. Como em toda resposta que não sai, se o agente pode passar para a equipe, a conversa vai para Atendimento humano e a IA fica pausada nela; se não pode, aparece em IA › Casos o alerta Um contato ficou sem resposta da IA, com o motivo "a mensagem esperou mais de 30 minutos na fila da IA". Quem esperava o horário de atendimento configurado no agente não entra nessa conta: a IA responde na abertura.
Mesmo no automático, uma resposta ficou retida. As proteções da IA seguram a resposta para revisão quando a verificação de segurança da mensagem não conclui (por exemplo, o provedor não respondeu a tempo) ou quando a avaliação antes do envio encontra um problema, como uma promessa que o agente não podia fazer. Um alerta explica o motivo em IA › Casos.
O que fazer: revise e decida a resposta em IA › Execuções, ou responda você mesmo na conversa.
O agente está esperando o horário de atendimento. Veja "Está fora do horário", acima.
A resposta leva alguns segundos para começar. É de propósito: o agente espera uns 8 segundos depois da última mensagem do contato para responder tudo junto, em vez de mandar uma resposta para cada mensagem ou foto. Se o contato continuar mandando, a espera recomeça a cada mensagem.
No Instagram
O agente responde no WhatsApp, mas não no Instagram. Cada canal tem o próprio responsável e o próprio acesso. Confira se há um agente Em operação (ou um roteador ativo) com a conta do Instagram marcada em Canais de atendimento, e se o cartão da conta em Acesso da IA libera o contato. No modo Somente testadores, o testador é o @usuário do perfil, como aparece na conversa. Veja Liberar o acesso da IA.
A resposta da IA não saiu numa conversa do Instagram. O Instagram só aceita resposta durante 24 horas desde a última mensagem do contato. No modo Assistida, uma resposta aprovada depois desse prazo não sai. Passadas as 24 horas, a conversa mostra Conversa encerrada, e ninguém consegue responder até o contato escrever de novo. Aprove as respostas do Instagram dentro do prazo.
O motivo aparece no alerta Um contato ficou sem resposta da IA e na transferência para a equipe: "a janela de 24 horas do Instagram fechou antes do envio da resposta (no Instagram não existe modelo de mensagem para retomar a conversa; quando o contato escrever de novo, a conversa reabre)".
A resposta chegou em várias mensagens. Cada mensagem do Instagram vai até 1.000 bytes, e acentos e emoji ocupam mais de um byte. Uma resposta maior é dividida automaticamente. Para respostas mais curtas, peça objetividade em Instruções do agente ou ajuste o Detalhamento em Comportamento.
Para as regras do canal, veja Conectar e atender pelo Instagram.
Não consigo publicar o agente
Causa: o diagnóstico do rascunho tem uma verificação bloqueando. A publicação confere o diagnóstico na hora, pelo painel e pela integração, e recusa enquanto houver pendência.
O que fazer: clique em Publicar versão. A janela lista cada pendência com um botão que leva a onde ela se resolve, como Abrir Provedores e chaves, Escolher credencial e modelo ou Abrir Acesso da IA. Quando o número não tem nenhum número de teste, cadastre ali mesmo em Cadastrar número de teste (no Instagram, Cadastrar testador, com o @usuário). Os itens em Avisos (não impedem a publicação) e a prova de geração não bloqueiam.
Erro de chave ou credencial
A chave foi recusada ou desligada. No Diagnóstico do agente, o item Chave validada aparece com Bloqueia. Em Configurações › Provedores e chaves, a chave aparece como Inválida ou Inativa.
O que fazer: substitua a chave em Editar › Validar e substituir chave, ou reative em Ativar. Veja Provedores e chaves.
A chave é aceita, mas o provedor recusa as respostas. "Validada" só quer dizer que o provedor reconheceu a chave. Falta de saldo ou limite de uso na conta do provedor só aparecem na hora de gerar. Na prova de geração do diagnóstico, isso aparece como "O provedor recusou por limite de uso ou saldo insuficiente."
O que fazer: confira o saldo e os limites na sua conta do provedor e refaça a prova em Fazer prova de geração.
A chave aparece como Desativada e a IA parou. A chave é de Google, OpenRouter, DeepSeek ou xAI. O BotoZap usa só OpenAI e Anthropic: essas chaves foram desativadas em 17/10/2026 e o segredo delas foi apagado.
O que fazer: em Configurações › Provedores e chaves, cadastre uma chave da OpenAI ou da Anthropic, escolha a chave nova nos agentes, roteadores e finalidades e publique o agente de novo. A chave antiga não precisa ser excluída. Veja Provedores e chaves.
O orçamento bloqueou a IA
Causa: o orçamento está em Interromper novas chamadas e o gasto estimado do mês chegou ao limite, ou houve chamadas com custo desconhecido, feitas com um modelo sem preço cadastrado. Aparece o alerta IA interrompida pelo orçamento em IA › Casos.
O que fazer: em Configurações › Uso e orçamento, na aba Orçamento e preços, aumente o Limite mensal (US$) se o gasto chegou ao limite. Se faltam preços, cadastre o preço do modelo e clique em Estimar histórico sem preço na linha dele: as chamadas antigas passam a ter valor e a IA volta a responder. Enquanto isso, a equipe atende pela Inbox. Veja Uso e orçamento.
Avisos de Atenção no diagnóstico
Estes itens do Diagnóstico não impedem a publicação, mas avisam que o agente não vai atender do jeito que você espera. Com o agente Em operação, os mesmos avisos aparecem no topo da página dele, na faixa Atenção no atendimento. Clique em Ver no diagnóstico para abrir o item com o botão que resolve.
Consulta à base de conhecimento. Há fontes marcadas em Conhecimento, mas a ferramenta Consultar base de conhecimento está desligada. Sem ela, o agente não lê esse material e responde só com as instruções.
O que fazer: clique em Ligar a consulta à base, marque Consultar base de conhecimento em O que ele pode fazer, salve o rascunho e publique.
Fontes de conhecimento. Uma fonte marcada no agente ainda não serve para consulta. O aviso diz qual e por quê, com a mesma frase da tela IA › Conhecimento:
- Aguardando a chave de conhecimento ou A OpenAI recusou a chave de conhecimento: falta a chave da OpenAI que prepara as fontes para busca. Clique em Abrir Provedores e chaves e configure a linha Base de conhecimento. A fonte é preparada sozinha depois disso.
- Falhou na indexação ou PDF escaneado aguardando revisão: clique em Abrir Conhecimento e siga o que a fonte pede, como Reindexar ou revisar o texto lido do PDF.
- Inativa ou não existe mais: clique em Revisar as fontes e desmarque a fonte no agente.
Fontes que ainda estão sendo preparadas não geram aviso: isso termina sozinho.
Áudios recebidos. Nenhuma chave está escolhida para Transcrição de áudio, ou a chave escolhida está desativada ou sem validação. Essa finalidade não usa a chave padrão do cliente. Sem ela, quando um contato manda áudio, o agente responde "Não consegui ouvir o áudio. Pode escrever o que precisa?". Se o agente lê vídeos, a fala dos vídeos também fica de fora.
O que fazer: clique em Abrir Provedores e chaves e escolha uma chave da OpenAI com um modelo de transcrição na linha Transcrição de áudio. Veja Provedores e chaves.
Imagens e documentos. O catálogo do provedor informa que o modelo usado para ler imagens não aceita imagens. Esse modelo é o da finalidade Descrição de imagens ou, sem ela, o próprio modelo do agente. Fotos, PDF sem texto (lido como imagem) e vídeos recebidos não são lidos: o agente sabe que o arquivo chegou, mas não vê o conteúdo e não tenta adivinhar o que há nele. O aviso só aparece quando o catálogo diz isso com certeza.
O que fazer: clique em Abrir Provedores e chaves e escolha em Descrição de imagens um modelo que aceite imagens.
Número de teste é o próprio número (no Instagram, Testador é a própria conta). A lista de teste em Acesso da IA tem o próprio número do WhatsApp do canal, ou o @usuário da própria conta do Instagram. Um número não conversa consigo mesmo como cliente, então esse teste nunca chega ao agente. Se ele é o único da lista, ninguém consegue testar.
O que fazer: clique em Abrir Acesso da IA, tire esse item da lista e cadastre outro celular, como o seu pessoal, ou outro perfil do Instagram.
Canal vinculado: outro agente ou um roteador atende este canal. O agente tem vários canais marcados e um deles já tem outro responsável. Ao ativar, esse canal fica de fora e os outros passam a ser atendidos.
O que fazer: pause o outro agente, ou desative o roteador (ou inclua este agente nele). Depois use Pausar agente e Retomar agente neste agente para ele passar a atender o canal.
Canal vinculado: o agente está em operação, mas ainda não atende neste canal. O canal está livre, mas ainda não foi ligado a este agente. Acontece quando o canal ficou de fora numa ativação anterior e depois foi liberado.
O que fazer: use Pausar agente e depois Retomar agente no botão de situação ao lado do nome do agente.
Canal fora da versão. O agente continua atendendo num canal que você tirou da versão publicada. Acontece quando a publicação não achou nenhum dos canais marcados livre: para não deixar o agente sem atendimento, ele segue no canal antigo.
O que fazer: libere um dos canais marcados (pause o agente que está nele) e use Pausar agente e Retomar agente neste. Se quiser manter o canal antigo, marque-o de novo em Canais de atendimento e publique.
Modo assistido. O agente está Em operação no modo Assistida: cada resposta fica esperando alguém da equipe aprovar na conversa, em Resposta da IA aguardando aprovação. Sem aprovação, o contato fica sem resposta. Se é isso que você quer para começar, está certo; o aviso só lembra que alguém precisa aprovar.
O que fazer: aprove as respostas na conversa ou em IA › Execuções. Para o agente responder sozinho, clique em Mudar para automático. Veja Execuções e aprovação.
Operação não ativada. A versão está publicada, mas a operação nunca foi ativada: o agente não atende ninguém.
O que fazer: no Diagnóstico, em Publicação, escolha o modo e clique em Ativar operação, ou use Ativar agente no botão de situação ao lado do nome do agente.
Versão em uso. O agente ainda não foi publicado, e o rascunho não atende ninguém. Ou o rascunho tem mudanças que ainda não valem: o atendimento segue com a versão publicada até você clicar em Publicar versão.
O que fazer: resolva o que estiver em Bloqueia e clique em Publicar versão no topo do agente.
O agente responde o que não devia
Ele não tem a informação. Se o assunto não está nos materiais, o agente não sabe. No agente, em Conhecimento, confira se as fontes certas estão marcadas e se a ferramenta Consultar base de conhecimento está ligada em O que ele pode fazer. Um aviso na própria tela aponta fontes ainda em preparação ou com falha. Veja Conhecimento.
As instruções deixam brecha. Em Comportamento, deixe claro em Instruções do agente o que ele deve e não deve fazer. Use Afirmações proibidas para frases que ele nunca pode dizer, como "garantimos entrega em 24 horas". Regras que valem para todos os agentes ficam nas regras da empresa, em Memória.
O tom não combina com o negócio. Ajuste Tom, Detalhamento, Usar emojis e Orientações de estilo em Comportamento, e as correções automáticas em Estilo das respostas.
Ele comenta fotos ou documentos que você só queria receber. Em O que ele pode fazer › Ler arquivos recebidos, desligue o tipo de arquivo. O agente continua sabendo que o arquivo chegou, mas não vê o conteúdo, e segue as suas instruções, como agradecer e dizer que a equipe vai conferir. Veja Fotos, PDFs e vídeos que o contato manda.
Ele fez algo que você não queria. Desligue a ferramenta em O que ele pode fazer. Ações sensíveis como remarcar ou cancelar compromissos vêm desligadas e precisam ser ligadas uma a uma.
Depois de cada ajuste: clique em Salvar rascunho, teste em Testar com a pergunta que deu problema e publique de novo. A versão anterior continua atendendo até você publicar. Para aprender com os atendimentos reais, veja Aprendizado e evolução.
Dica: enquanto ajusta, deixe o agente no modo Assistida. Assim nada sai sem alguém da equipe ver antes.
