Conhecimento

O Conhecimento é o material que os agentes consultam antes de responder: sua tabela de preços, a política de trocas, as perguntas que os clientes sempre fazem, o catálogo de produtos. Em vez de decorar tudo nas instruções, o agente busca aqui o trecho certo na hora da conversa.

Tudo fica em IA › Conhecimento, com três abas: Fontes, Testar busca e Importar do cliente. Cada item cadastrado é uma fonte.

Antes de começar

• Escolha o cliente no seletor do topo do painel. O conhecimento é separado por cliente: o que você cadastra para um não aparece para outro.
• Excluir uma fonte de vez e cadastrar uma chave de IA nova são só para Administrador. Se você criou a conta, já é. Escolher uma chave já validada qualquer pessoa da equipe faz. Para tirar uma fonte de uso sem apagá-la, use Inativar.
• O BotoZap precisa de uma chave da OpenAI sua para preparar e buscar o material. Sem ela, as fontes ficam cadastradas como Aguardando chave e o agente ainda não encontra nada nelas. Assim que a chave fica pronta, elas são preparadas sozinhas. Veja a seção abaixo.

Configurar a chave de conhecimento

Enquanto não houver uma chave pronta, a aba Fontes mostra o quadro Chave de conhecimento.

1. Se você já cadastrou uma chave da OpenAI validada, escolha-a em Credencial OpenAI validada e clique em Usar para conhecimento.
2. Se ainda não tem, preencha Nome (por exemplo, "OpenAI conhecimento") e Chave da API OpenAI, e clique em Cadastrar e usar.
3. A chave passa por uma validação. Enquanto isso, a tela avisa que a credencial está em validação e se atualiza sozinha.

Quando tudo estiver certo, o quadro some e aparece, no fim da lista, a frase Indexação e busca configuradas com a credencial seguida do nome da sua chave.

Fontes cadastradas antes da chave aparecem como Aguardando chave. Quando a chave fica pronta, elas voltam para a fila sozinhas, sem você precisar abrir uma por uma. As fontes que já estavam prontas não são preparadas de novo.

O que você pode cadastrar

Clique em Adicionar fonte e escolha o tipo:

• Documento (PDF ou texto longo): envie um arquivo ou cole o texto. Bom para manuais, políticas e tabelas.
• Perguntas frequentes: pares de pergunta e resposta. Cada resposta fica sempre junto da sua pergunta, o que ajuda o agente a achar a resposta certa.
• Catálogo (JSON ou CSV): sua lista de produtos, com preço e link.
• Conversa revisada: um atendimento já encerrado que serve de exemplo, depois de revisado e anonimizado.
• Serviços da Agenda: os serviços que você já cadastrou na Agenda.

Limites

• Arquivo de documento: até 20 MB. PDF (inclusive escaneado), TXT, Markdown ou CSV.
• Texto colado: até 500 mil caracteres.
• Perguntas frequentes: até 500 pares. Cada pergunta com até 600 caracteres e cada resposta com até 50 mil.
• Catálogo: até 1.000 produtos e 1,5 MB.
• Conversa revisada: até 1.000 mensagens ou 500 mil caracteres.

Passo a passo: adicionar um documento

1. Em IA › Conhecimento, aba Fontes, clique em Adicionar fonte e escolha Documento.
2. Dê um Nome que a equipe reconheça, como "Política de trocas 2026".
3. Escolha Enviar arquivo e selecione o arquivo, ou Colar texto e cole o conteúdo.
4. Clique em Adicionar e indexar.

A mensagem Fonte adicionada. A indexação começa em instantes. confirma o envio.

PDF escaneado: revisar antes de usar

PDF escaneado é o documento digitalizado ou fotografado: cada página é uma imagem, sem texto que dê para selecionar. O BotoZap aceita esse arquivo e lê as primeiras 10 páginas com IA, a partir da imagem. A leitura por IA pode trocar um número ou uma data, por isso o texto não vai direto para os agentes: a fonte fica como Aguardando revisão até alguém da equipe conferir e aprovar.

A leitura usa a chave de IA do cliente que lê imagens: a da finalidade Descrição de imagens em Configurações › Provedores e chaves ou, sem ela, a chave padrão do cliente. O custo entra no consumo de IA do cliente.

1. Envie o PDF como qualquer documento: Adicionar fonte, Documento, Enviar arquivo.
2. Espere o estado passar de Na fila e Indexando para Aguardando revisão.
3. Clique no nome da fonte. O painel avisa que o PDF não tem texto selecionável e mostra quantas páginas foram lidas e quantos trechos ficaram ilegíveis.
4. Compare o quadro Texto lido com o documento e corrija o que precisar, principalmente valores, datas, nomes e códigos. [ilegível] marca o que a IA não conseguiu ler: preencha ou apague. Se o PDF tem mais de 10 páginas, o painel diz quantas não foram lidas; cole o texto delas no fim, se precisar.
5. Clique em Aprovar e indexar. A mensagem Texto aprovado. A fonte entra na fila de indexação. confirma.

Se a leitura não serviu, clique em Descartar e confirme em Excluir fonte.

Depois da aprovação:

• A fonte segue a indexação normal até ficar Pronta. Na lista e no painel, ela ganha a marca Transcrito por IA, que continua mesmo se você editar o texto depois.
• Os trechos dessa fonte chegam ao agente com o nome da fonte seguido de (transcrito por IA). É assim que eles aparecem em Testar busca e em Fontes da resposta da IA, na conversa.
• Enquanto a fonte aguarda revisão, nenhum agente encontra nada nela. O editor do agente avisa isso logo abaixo das fontes.

Passo a passo: perguntas frequentes

1. Clique em Adicionar fonte e escolha Perguntas frequentes.

2. Dê um Nome e, em Conteúdo, escreva um par por item, assim:

   ## Pergunta: Qual o prazo de entrega?
   ## Resposta: Até 5 dias úteis para capitais.
   
   ## Pergunta: Vocês parcelam?
   ## Resposta: Sim, em até 6 vezes sem juros no cartão.
   

3. Clique em Adicionar e indexar.

Se faltar a pergunta ou a resposta de algum item, o BotoZap recusa e pede pares completos.

Importar o que já está no BotoZap

A aba Importar do cliente reúne três importações. As mesmas opções aparecem no menu Adicionar fonte.

Serviços da Agenda

Em Serviços da Agenda, clique em Importar serviços atuais. O BotoZap usa o nome, a descrição e a duração dos serviços ativos. Os horários livres continuam sendo consultados na Agenda, na hora da conversa.

Mudou algum serviço? Volte aqui e clique em Atualizar serviços. Você precisa ter ao menos um serviço ativo em Configurações › Horários e serviços.

Catálogo de produtos

1. Em Catálogo de produtos, preencha Nome da fonte.
2. Em Arquivo JSON ou CSV, escolha o arquivo. Numa planilha salva como CSV, use as colunas id, nome, descrição, preço, sku e link. id e nome são obrigatórios.
3. Clique em Importar catálogo.

Conversas revisadas

Um bom atendimento vira exemplo para o agente. Por segurança, isso só acontece com conversas encerradas, com a sua autorização e depois de você revisar o texto.

1. Em Conversas revisadas, veja a lista Conversas encerradas (as mais recentes aparecem primeiro). Se precisar, clique em Atualizar.
2. Na conversa escolhida, clique em Autorizar revisão. O selo muda para Uso autorizado.
3. Clique em Revisar texto. Aparece Revisão antes da indexação, com o texto que será usado e quantos identificadores foram removidos.
4. Leia o texto inteiro. O BotoZap troca por marcadores o nome do contato, CPF, CNPJ, e-mail, telefone, CEP, números longos e nomes próprios comuns. Só entram as mensagens de texto.
5. Marque Revisei o texto e confirmei que está adequado, sem dados pessoais ou informações restritas.
6. Clique em Indexar conversa revisada.

Quer tirar a conversa do conhecimento? Clique em Revogar uso. Ela sai da busca na hora.

Acompanhar a indexação

Depois de salvar, o BotoZap prepara o material para a busca. É a indexação. A coluna Estado mostra em que ponto cada fonte está:

• Na fila: aguardando a vez.
• Aguardando chave: falta a chave de conhecimento, ou a OpenAI recusou a chave. A fonte é preparada sozinha quando a chave fica pronta.
• Indexando: em preparação.
• Pronta: o agente já encontra o conteúdo.
• Aguardando revisão: PDF escaneado lido por IA, esperando alguém da equipe conferir o texto. Veja PDF escaneado.
• Falhou: algo deu errado. Abra a fonte para ver o motivo e o que fazer.

Enquanto houver fonte na fila ou indexando, a tela mostra Indexação em andamento. Os estados atualizam automaticamente. e se atualiza sozinha. Para forçar, clique em Atualizar estados, ao lado de Adicionar fonte. Para ver só o que precisa de atenção, clique no filtro Com problema.

Ver, editar e reindexar uma fonte

Clique no nome da fonte para abrir o painel lateral. Ali você vê:

• Conteúdo: o texto que o BotoZap extraiu.
• Usada por: quais agentes usam esta fonte, e se na versão publicada ou num rascunho.
• Um aviso no topo, quando a fonte está em agentes que já atendem: Esta fonte é usada por N agentes em operação, com os nomes, seguido de A mudança vale nas próximas respostas.
• Versões: cada revisão da fonte, com estado e quantidade de trechos.
• Trechos indexados: os pedaços que o agente pode receber na busca.

No rodapé do painel, os botões mudam conforme a origem da fonte:

• Documento e Perguntas frequentes: Editar conteúdo abre o nome e o texto para edição. Clique em Salvar alterações. Salvar um texto novo cria uma nova versão; enquanto ela é preparada, a anterior continua valendo.
• Serviços da Agenda: Atualizar serviços busca de novo os serviços ativos da Agenda.
• Catálogo: Substituir catálogo abre o envio de um novo arquivo JSON ou CSV, que troca os produtos desta fonte. Produtos que não mudaram aproveitam a preparação anterior.
• Conversa revisada: Revisar conversa de novo leva à aba Importar do cliente, onde você revisa o texto anonimizado antes de indexar uma nova versão.
• Reindexar (documentos, perguntas frequentes e catálogo) prepara a fonte de novo, por exemplo depois de uma falha. O estado volta para Na fila.
• No menu ··· ao lado dos botões, Inativar tira a fonte da busca sem apagá-la, e Ativar devolve. Nas fontes importadas, Renomear troca o nome. Excluir apaga a fonte e o histórico, depois de você confirmar em Excluir fonte. A chave Ativa, na própria tabela, faz o mesmo que Inativar e Ativar.

O que vale na hora

A versão publicada do agente guarda quais fontes ele consulta, mas não o conteúdo delas. Por isso, editar o texto, substituir o catálogo, atualizar os serviços, reindexar, inativar ou ativar uma fonte muda as respostas de todos os agentes em operação que a usam, já nas próximas mensagens, sem publicar o agente de novo.

Antes de mexer, confira o aviso no painel da fonte: ele diz quantos agentes em operação usam a fonte e quais são. Depois de salvar, a mensagem de confirmação repete a lista, por exemplo: Fonte salva. Vale nas próximas respostas de 2 agentes em operação (Vendas e Suporte). Se o BotoZap não conseguir conferir a lista naquele momento, o aviso diz isso em vez de mostrar zero.

Testar o que o agente encontra

Na aba Testar busca você faz uma pergunta como um cliente faria e vê exatamente os trechos que o agente receberia.

1. Em Fontes consultadas, deixe marcadas as fontes que quer testar. Só aparecem fontes ativas e prontas.
2. Escreva a pergunta, por exemplo "qual o prazo para troca?".
3. Clique em Buscar trechos.

Cada resultado mostra de qual fonte veio e a similaridade, que indica o quanto o trecho combina com a pergunta. Se nada for relevante o bastante, a tela explica o motivo: por exemplo, que o trecho mais próximo ficou abaixo do mínimo exigido, e sugere reformular a pergunta ou completar o material.

Como o agente usa o conhecimento

Cadastrar a fonte não basta: cada agente só consulta as fontes que você autorizar para ele. Isso evita, por exemplo, que o agente de vendas responda com um documento interno de suporte.

1. Abra o agente em IA › Agentes.
2. No grupo Conhecimento, em Fontes de conhecimento, marque as fontes que ele pode consultar.
3. No grupo O que ele pode fazer, em Ferramentas e acesso ao CRM, confira se Consultar base de conhecimento está ligada. Ela fica no pacote Aprender e evoluir.
4. Publique a nova versão do agente.

Logo abaixo das fontes, o editor avisa quando algo impede a consulta: fontes marcadas com a ferramenta desligada, fonte ainda em indexação, fonte aguardando a chave, PDF escaneado aguardando revisão, fonte com falha (com o motivo e o que fazer) ou fonte inativa.

Depois de publicado, o agente passa a usar o conteúdo mais recente de cada fonte autorizada. Corrigir um texto ou reimportar o catálogo vale para as próximas respostas, sem publicar o agente de novo. Veja O que vale na hora.

O que acontece depois

• A cada conversa, o agente busca nas fontes autorizadas e responde com base nos trechos encontrados.
• Em IA › Evolução, o quadro Buscas no conhecimento mostra quantas buscas trouxeram resultado e lista as Buscas recentes sem resultado. É a melhor pista do que falta cadastrar. Veja Aprendizado e evolução.

Problemas comuns

A fonte fica em "Na fila" por muito tempo. A indexação corre em segundo plano e documentos grandes demoram mais. A tela se atualiza sozinha; se ficar parada, clique em Atualizar estados. Se a chave de conhecimento ainda estiver em validação, espere a validação terminar.

A fonte está como "Falhou". Abra a fonte: o painel mostra o motivo e o que fazer. Em IA › Agentes, o editor de um agente que usa a fonte mostra o mesmo aviso.

O PDF escaneado falhou. Se o aviso pede uma chave que leia imagens, configure a finalidade Descrição de imagens (ou a chave padrão do cliente) em Configurações › Provedores e chaves e clique em Reindexar. Se a leitura por IA não respondeu, clique em Reindexar em alguns minutos. Se nenhum texto legível foi encontrado, envie uma versão do PDF com texto selecionável ou use Colar texto.

A fonte está como "Aguardando revisão". Ela é um PDF escaneado lido por IA. Abra a fonte, confira o texto e clique em Aprovar e indexar. Até lá, o agente não encontra nada nela.

A fonte está como "Aguardando chave". Falta a chave de conhecimento ou a OpenAI recusou a chave. Configure ou troque a chave como mostra Configurar a chave de conhecimento. A fonte volta para a fila sozinha.

O agente responde sem usar o material. Confira no editor do agente se a fonte está marcada em Fontes de conhecimento e se Consultar base de conhecimento está ligada. Depois, teste a pergunta em Testar busca.

Não consigo publicar o agente. Uma das fontes marcadas nele está inativa. Ative a fonte em Conhecimento ou desmarque-a no agente.