> ## Documentation Index > Fetch the complete documentation index at: https://docs.octasend.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Chatbot com IA > Bots de atendimento com IA no WhatsApp, com base de conhecimento da empresa, tom de voz e consulta aos seus sistemas O **chatbot** responde automaticamente às mensagens que chegam nos seus números de WhatsApp, usando um modelo de IA. Além de conversar, ele consulta a **base de conhecimento** da sua empresa e pode chamar a API do seu sistema para responder com dados reais: o status de um pedido, o valor de uma fatura, a situação de um cadastro. Você pode ter **vários bots**, um para cada número de WhatsApp, cada um com instruções, tom de voz, identificação e integrações próprias. A base de conhecimento é uma só para a empresa inteira. ## Onde fica No menu lateral, abra **Chatbot**: | Item do menu | O que você encontra | | - | - | | **Chatbot WhatsApp** | A lista dos seus bots (**Meus Bots**), a chave que liga e desliga o módulo e o botão **Criar bot**. Ao abrir um bot, aparecem as abas **Conector de API**, **Identidade**, **Configuração do Bot** e **Conversas**. | | **Base de Conhecimento** | Os documentos, textos e páginas que os bots consultam (aba **Fontes**) e os tons de voz da IA (aba **Tom de voz**). | | **Chatbot Site** | O assistente de IA do seu site. Só aparece quando esse módulo está ativo na sua conta. Veja [Chatbot do site](https://docs.octasend.com.br/plataforma/chatbot-do-site.md). | As telas do chatbot não têm permissão separada por papel: quem acessa o painel da sua conta pode configurá-las. ## Ligar e desligar o módulo No topo de **Chatbot → Chatbot WhatsApp** fica a chave **Módulo de chatbot**. Ela vale para a conta inteira, não para um bot só. Com o módulo **desativado**: * nenhum bot responde no WhatsApp, mesmo os marcados como ativos; * a lista de bots e as abas de cada bot (conector de API, identidade, configuração e conversas) ficam ocultas. Se alguém abrir um link direto, volta para a tela do **Chatbot WhatsApp**; * a **Base de Conhecimento** continua disponível se o [Chatbot do site](https://docs.octasend.com.br/plataforma/chatbot-do-site.md) estiver ativo, porque ele usa a mesma base; * as configurações, a base de conhecimento e o histórico continuam salvos. As mensagens recebidas continuam sendo registradas, só não recebem resposta automática. Para voltar a usar, é só ligar a chave de novo. ## Criar um bot **1. Abra a lista de bots** Vá em **Chatbot → Chatbot WhatsApp** e clique em **Criar bot**. **2. Dê um nome e escolha a conexão** Preencha **Nome** (ex.: "Atendimento vendas") e escolha a **Conexão de WhatsApp** (o número) em que o bot vai atender. Clique em **Criar**. **3. Configure e ative** Abra o bot na lista. Na aba **Configuração do Bot**, escreva as instruções, marque **Bot ativo no WhatsApp** e clique em **Salvar**. Regras: * Cada bot atende **exatamente um número** de WhatsApp, e cada número só pode ter **um bot**. A lista de conexões mostra só as que ainda não estão em uso. Se nenhuma aparecer, a tela avisa **Nenhuma conexão de WhatsApp livre**: conecte um número novo em [WhatsApp](https://docs.octasend.com.br/guias/whatsapp.md). * A conexão do bot não pode ser trocada depois da criação. Para atender em outro número, crie um novo bot. * O painel não tem opção para renomear um bot. Para liberar um número já vinculado, exclua o bot (veja [Excluir um bot](#excluir-um-bot)). * O bot nasce **inativo**: ele só responde depois que você marcar **Bot ativo no WhatsApp** e salvar. * Um número conectado que não tem bot não recebe resposta automática. ## Configuração do bot Na aba **Configuração do Bot** você define como o assistente se comporta: | Campo | O que faz | | - | - | | **Bot ativo no WhatsApp** | Liga ou desliga as respostas deste bot. Desligado, as mensagens continuam registradas, sem resposta automática. | | **Conexão de WhatsApp** | Mostra a conexão em que o bot atende: o nome dela e o tipo (**Meta Cloud API** ou **Evolution API**), com **(padrão)** ou **(desativada)** quando for o caso. Somente leitura: para usar outra conexão, crie um novo bot. Se a conexão foi removida, aparece **não encontrada**. | | **Persona / instruções do sistema** | As instruções permanentes do bot: quem ele é, o que pode e o que não pode fazer, como deve conduzir a conversa. | | **Mensagem de fallback (quando não souber responder)** | O que o bot envia quando o modelo de IA não produz uma resposta — o que pode acontecer, por exemplo, quando ele atinge o limite de consultas do turno sem concluir. Se você salvar com o campo em branco, fica gravada a mensagem padrão **Desculpe, não consegui te ajudar com isso no momento.** | | **Mensagem quando o atendimento automático estiver indisponível** | O que o bot envia ao cliente quando o limite de uso de IA é atingido. Em branco, vale a mensagem padrão **Desculpe, nosso atendimento automático está temporariamente indisponível. Tente novamente em instantes.** Veja [Meu LLM (opcional)](#meu-llm-opcional). | | **Tom de voz** | O jeito de escrever do bot. Em **Padrão da conta**, ele segue o tom padrão definido na Base de Conhecimento. Veja [Tom de voz](#tom-de-voz). | | **Usar a base de conhecimento** | Liga ou desliga a consulta à base de conhecimento neste bot. Vem ligada e **salva na hora**, sem precisar clicar em **Salvar**. | | **Limite de chamadas de tool por turno** | Quantas consultas à sua API o bot pode encadear antes de responder uma mensagem. Use um valor de 1 a 20; o padrão é 5. Protege contra respostas lentas e consultas em cascata. | Clique em **Salvar** para gravar os campos (exceto a chave da base de conhecimento, que já salva sozinha). ### Instruções da empresa Além das instruções de cada bot, existe um texto de **instruções da empresa** que vale para todas as conversas da IA com os seus clientes: os bots do WhatsApp, as etapas de IA das [automações](https://docs.octasend.com.br/plataforma/automacoes.md) e o chat do site. Ele fica em **Chatbot → Chatbot Site**, aba **System Prompt**, e aceita até 10.000 caracteres. Na conversa, as instruções da empresa vêm primeiro e as do bot são somadas a elas. O tom de voz é aplicado por último. > [!NOTE] > > A aba **System Prompt** fica dentro do **Chatbot Site**, que é um módulo opcional. Se o item não aparece no seu menu, fale com a OctaSend para ativar. ### Meu LLM (opcional) Por padrão, o bot usa a conta de IA da plataforma, com o modelo padrão definido pela OctaSend. Em **Meu LLM (opcional)**, na mesma aba, você pode usar a sua própria conta: 1. Escolha o **Provedor**: Anthropic (Claude), OpenAI, Grok (xAI) ou DeepSeek. 2. Escolha o **Modelo** desse provedor. 3. Cole a **Chave de API** e clique em **Salvar token**. A chave fica salva por provedor, para a conta inteira, e o campo passa a mostrar só os quatro últimos caracteres. Quando você escolhe um modelo antes de salvar, este bot passa a responder com esse provedor e esse modelo. Se você salvar a chave sem escolher um modelo, o bot continua com o provedor padrão da plataforma, e a sua chave só é usada se for do mesmo provedor. Para garantir que o bot use a sua conta, escolha provedor e modelo antes de clicar em **Salvar token**. > [!TIP] > > O botão **Salvar token** só fica habilitado com uma chave digitada. Para trocar apenas o modelo do bot, informe a chave de novo e salve. **Meu limite de tokens** aparece depois que você salva uma chave própria. Ele vale só para as chamadas feitas com a sua chave: deixe em branco para não ter teto, ou informe um número para limitar o consumo. O consumo atual aparece ao lado e soma as chamadas de IA feitas com a sua chave. Quando o limite de consumo é atingido (o seu, com chave própria, ou o definido pela OctaSend para a sua conta, com a IA da plataforma), o bot envia ao cliente a **Mensagem quando o atendimento automático estiver indisponível**, da aba **Configuração do Bot**. A mensagem padrão diz só que o atendimento automático está temporariamente indisponível, sem mencionar limite nem cobrança. Um texto seu nesse campo substitui o padrão. ## Excluir um bot No fim da aba **Configuração do Bot** fica o bloco **Excluir bot**. **1. Clique em Excluir bot** A confirmação lista o que será apagado. **2. Digite o nome do bot** O botão de excluir só fica disponível quando o nome digitado confere com o do bot. A cada vez que a confirmação abre, o campo volta vazio. **3. Confirme** Clique em **Excluir bot**. A tela volta para a lista de bots. * São apagados a configuração, a identidade, os conectores de API, as conversas e o histórico de mensagens daquele bot. A exclusão não pode ser desfeita. * A **base de conhecimento** continua: ela é da empresa, não do bot. * O número de WhatsApp fica livre para você criar outro bot nele. * O assistente do [Chatbot do site](https://docs.octasend.com.br/plataforma/chatbot-do-site.md) não é excluído por aqui. ## Base de conhecimento Em **Chatbot → Base de Conhecimento** você cadastra o conteúdo que a IA deve conhecer. A base é **uma só para a empresa**: vale para todos os bots do WhatsApp que estão com **Usar a base de conhecimento** ligado e para o [Chatbot do site](https://docs.octasend.com.br/plataforma/chatbot-do-site.md). > [!NOTE] > > A base deixou de ser separada por bot. Links antigos para a base dentro de um bot levam para a página única da Base de Conhecimento. ### Adicionar uma fonte **1. Abra a tela de nova fonte** Na aba **Fontes**, clique em **Adicionar fonte**. **2. Escolha o tipo e o escopo** Em **Tipo**, escolha **Texto**, **Arquivo** ou **URL**. Em **Escopo**, escolha **Compartilhado** ou **Privado a um sub-cliente** (veja [Escopo](#escopo)). **3. Preencha o conteúdo** Para **Texto** e **Arquivo**, dê um **Título** e cole o texto ou envie o arquivo. Para **URL**, escolha em **O que ler** entre **Páginas** e **Site inteiro** e informe os endereços. Clique em **Adicionar**. | Tipo | Como funciona | | - | - | | **Texto** | Você cola o conteúdo direto na tela. Fica pronto quase na hora. | | **Arquivo** | Aceita PDF, Word (`.docx`), PowerPoint (`.pptx`), Excel (`.xlsx`), imagem (`.png`, `.jpg`, `.jpeg`) e texto (`.txt`, `.md`). Arquivos `.txt` e `.md` ficam prontos quase na hora; os demais passam por uma leitura que pode levar alguns minutos. | | **URL → Páginas** | Informe até 20 URLs por vez, uma por linha. Cada URL vira uma fonte, com o título da própria página. Só aquela página é lida: os links dela não são seguidos. | | **URL → Site inteiro** | Informe o endereço do site. A plataforma lê o mapa do site (sitemap) e segue os links internos, até 500 páginas, só do endereço informado para dentro e respeitando o `robots.txt` do site. O site vira uma fonte só, com uma tela própria que lista as páginas lidas. | #### Site inteiro Ao abrir um site na lista, você vê o andamento (**Descobrindo páginas…**, **Lendo N de M páginas** e, no fim, o resumo de páginas prontas e com falha) e a tabela das páginas lidas, com filtro. * **Mapear de novo** lê o site outra vez: procura páginas novas e lê de novo as que já estavam na base. * Numa página, **Reprocessar** lê só aquela página de novo, e **Remover** (com confirmação) tira os trechos dela da base. Uma página removida não volta quando o site é mapeado de novo; para trazê-la de volta, use **Incluir de novo** na tabela. * **Excluir** apaga o site e todas as páginas lidas dele. * O escopo vale para todas as páginas do site. Para trocar, exclua o site e mapeie de novo. * Um mesmo site só pode ser cadastrado uma vez. Para atualizá-lo, use **Mapear de novo**. * A tela avisa quando o mapeamento para no limite de 500 páginas e quando o site parece montado por JavaScript, caso em que o conteúdo não pode ser lido. Regras de leitura: * **Tamanho máximo:** 50 MB por arquivo. O mesmo limite vale para a página baixada de uma URL. * **PDF:** até 500 páginas. * **Imagens e documentos digitalizados:** o texto é reconhecido automaticamente (OCR), em português e em inglês. * **URL:** precisa ser um endereço público. Endereços internos ou inválidos são recusados. A página tem 30 segundos para responder e pode redirecionar até 5 vezes. * **Tempo de leitura:** a leitura de PDF, Word, PowerPoint, Excel, imagem e URL roda em segundo plano. Se não terminar em 15 minutos, a plataforma tenta um método de leitura alternativo (disponível para PDF, Word e URL). Sem alternativa, a fonte fica com erro e você pode reprocessar. O conteúdo lido é dividido em **trechos**. A cada mensagem, o bot recebe os **5 trechos mais relevantes** para a pergunta. ### Status da fonte A lista se atualiza sozinha enquanto houver fontes em processamento. | Status | O que significa | | - | - | | **Pendente** | A fonte foi cadastrada e aguarda o início da leitura. | | **Processando** | O conteúdo está sendo lido e dividido em trechos. | | **Pronta** | Os trechos estão disponíveis para os bots. | | **Falhou** | A leitura não deu certo. O motivo aparece junto da fonte. | Quem consulta a base: * fontes com **erro** não são consultadas; * uma fonte que está sendo **reprocessada** continua respondendo com o conteúdo anterior até a nova leitura terminar. ### Mensagens de erro | Mensagem | O que fazer | | - | - | | O arquivo passa de 50 MB, o limite da base de conhecimento. | Divida o arquivo ou reduza o tamanho. | | O PDF tem mais de 500 páginas, o limite da base de conhecimento. | Divida o PDF em partes menores. | | Tipo de arquivo não suportado: .(extensão) | Converta para um dos formatos aceitos. | | Nenhum texto foi encontrado nesta fonte. | Confira se o arquivo ou a página tem texto legível (uma página que só carrega o conteúdo por script pode vir vazia). | | Não foi possível ler o arquivo agora. Tente reprocessar em alguns minutos. | Clique em **Reprocessar** mais tarde. | | URL não permitida: aponta para um endereço interno ou inválido. | Use um endereço público completo, começando com `https://` ou `http://`. | | A página respondeu (código). / A página redirecionou vezes demais. | Confira se o endereço abre normalmente no navegador. | ### Escopo Cada fonte tem um escopo: * **Compartilhado** — vale para todas as conversas. * **Privado a um sub-cliente** — vale só para as conversas de um cliente específico do seu sistema. Útil quando cada cliente tem regras, contratos ou condições próprias. Informe o **ID do sub-cliente**, exatamente o mesmo identificador que o seu sistema devolve na identificação do usuário (veja abaixo). O conteúdo privado só é usado depois que a conversa foi identificada como daquele sub-cliente. Antes disso, o bot consulta apenas o conteúdo compartilhado. ### Editar, reprocessar e excluir Clique em qualquer fonte da lista para abrir a página dela. Lá você vê os **Dados** (tipo, escopo, criação e última atualização), pode editar a fonte e confere os **Trechos gerados**, que são exatamente o que os bots consultam. Em **Editar** você altera o título, o escopo e o conteúdo (o texto, a URL ou, em **Enviar outro arquivo**, um arquivo novo). Clique em **Salvar alterações**: | O que mudou | O que acontece | | - | - | | Só o título | Salva sem ler o conteúdo de novo. | | O conteúdo (texto, URL ou arquivo) | A fonte é lida de novo. Os trechos antigos continuam valendo até a nova leitura terminar. | | O escopo | Os trechos antigos são apagados na hora e a fonte é lida de novo, para que um conteúdo que virou privado nunca fique visível a outro sub-cliente. | * O **tipo** de uma fonte não muda. Para trocar, exclua e cadastre de novo. * Em fontes do tipo arquivo, **Baixar arquivo** gera um link temporário para o arquivo original. * **Reprocessar** (na lista ou na página da fonte) lê o conteúdo de novo sem alterar nada. * **Excluir** pede confirmação e remove a fonte e os trechos dela. * Se a tela avisar que as alterações foram salvas mas o reprocessamento não começou, use **Reprocessar**. ### Tom de voz A aba **Tom de voz** da Base de Conhecimento define o jeito de escrever da IA com os seus clientes. * A plataforma traz 20 tons prontos, em cinco grupos: *Corporativos e profissionais*, *Proximidade e relacionamento*, *Autoridade e impacto*, *Educacionais e criativos* e *Suporte e vendas*. * Use **Definir como padrão** para escolher o tom da conta. Sem escolha, a IA usa o tom **Formal**. * Em **Criar tom personalizado** você escreve um tom da sua marca: **Nome** (até 60 caracteres, sem repetir o nome de outro tom seu), **Descrição** (até 300) e **Instruções para a IA** (até 2.000). Nome e instruções são obrigatórios. Tons personalizados podem ser editados e excluídos; os prontos, não. * Cada bot pode usar um tom diferente do padrão, no campo **Tom de voz** da aba **Configuração do Bot**. As etapas de IA das [automações](https://docs.octasend.com.br/plataforma/automacoes.md) também podem escolher o tom. * Ao excluir um tom, os bots e as automações que o usavam passam a seguir o padrão da conta. Se o tom excluído era o padrão, a IA volta ao **Formal**. ## Identificação do usuário Quando o bot precisa responder com dados de um cliente específico, ele primeiro descobre **quem** está do outro lado. A identificação é configurada por bot, na aba **Identidade**: | Campo | Para que serve | | - | - | | **Habilitar resolução de identidade por sub-cliente** | Liga a identificação neste bot. | | **Endpoint de resolução (telefone → sub-cliente)** | Endereço do seu sistema que recebe o telefone de quem escreveu e devolve qual cliente é o dono daquele número. | | **Mensagem de desafio (pedido de autenticação)** | O texto que o bot envia quando precisa pedir uma credencial (CPF, e-mail, código de cliente — o texto é seu). | | **Endpoint de validação da credencial** | Endereço do seu sistema que recebe a credencial digitada e confirma, ou não, de quem se trata. | ### Credencial dos endpoints Se os seus endpoints de resolução e de validação exigem autenticação, cole o token no bloco **Credencial dos endpoints**, na mesma aba **Identidade**, e clique em **Salvar credencial**. O bot envia esse token no cabeçalho `Authorization: Bearer ` nas chamadas aos dois endpoints. * A credencial fica cifrada e nunca volta para a tela: o bloco mostra só **Configurada** ou **Não configurada**, com o campo mascarado. Para trocar, use **Substituir** e salve a nova. * **Remover credencial** pede confirmação. Sem credencial, os endpoints passam a ser chamados sem autenticação; se a sua API exigir o token, o bot deixa de identificar os clientes até você salvar uma nova. * Salvar os demais campos da aba **Identidade** não mexe na credencial salva. ### Como a identificação acontece 1. Na primeira mensagem que o bot processa numa conversa, a OctaSend envia o telefone ao **endpoint de resolução**. Se o seu sistema reconhecer o número, a conversa já fica identificada. Se não reconhecer (ou se a identificação foi ligada depois que a conversa começou), a consulta pelo telefone é repetida nas mensagens seguintes, no máximo uma vez por hora, enquanto a conversa não estiver identificada nem aguardando a credencial. 2. Sem identificação, o cliente conversa normalmente: o bot usa só o conteúdo **compartilhado** da base e só as consultas à API que **não** exigem identificação (veja *Parâmetro de escopo*, mais abaixo). Isso permite, por exemplo, navegar por um catálogo público. 3. Quando o pedido exige saber quem é o cliente (comprar, ver pedidos, dados da conta), o bot pede a credencial usando a **mensagem de desafio**. Sem mensagem configurada, ele pede o CPF ou o e-mail cadastrado. 4. A mensagem seguinte do cliente é enviada ao **endpoint de validação**. Se o seu sistema confirmar, a conversa fica identificada; se não, o bot envia a mensagem de desafio de novo (sem mensagem configurada, pede para tentar novamente). > [!WARNING] > > Enquanto aguarda a credencial, **toda** mensagem do cliente é tratada como a credencial e enviada ao endpoint de validação, até que uma seja aceita. Escreva a mensagem de desafio deixando claro o que a pessoa deve responder. Uma vez identificada, a conversa mantém o mesmo sub-cliente nas mensagens seguintes. ### O que o seu sistema recebe e devolve Os dois endpoints recebem um `POST` com corpo JSON. O telefone chega como o WhatsApp informa, só com dígitos (normalmente com código do país e DDD). ```json Resolução — requisição theme={null} { "phone": "5511999999999" } ``` ```json Validação — requisição theme={null} { "phone": "5511999999999", "credential": "123.456.789-00" } ``` ```json Resposta dos dois endpoints theme={null} { "sub_client_id": "cliente-4821" } ``` * Responda com status 2xx e `sub_client_id` preenchido como **texto** (entre aspas, mesmo que o seu ID seja numérico, ex.: `"4821"`) quando reconhecer o cliente. Um valor numérico conta como não identificado. * Qualquer outra resposta (status de erro, `sub_client_id` vazio ou ausente, falha de conexão) conta como **não identificado**. Uma recusa por falta de autenticação também: se os seus endpoints exigem token, configure a [credencial dos endpoints](#credencial-dos-endpoints). > [!WARNING] > > O bot **nunca decide sozinho** de qual cliente são os dados. O identificador vem só do seu sistema, pela identificação, e é o único usado nas consultas seguintes — mesmo que o modelo de IA tente informar outro valor, ele não chega à sua API. ## Consultar seus sistemas Na aba **Conector de API** você conecta a API do seu sistema ao bot enviando uma especificação **OpenAPI 3.0**. A plataforma lê a especificação e transforma cada operação numa ferramenta (*tool*) que o bot pode usar durante a conversa. Os conectores são de cada bot. ### Importar um conector **1. Abra o formulário** Na aba **Conector de API** do bot, clique em **Importar conector**. **2. Preencha os dados da API** Informe o **Nome** do conector, a **URL base** (ex.: `https://api.suaempresa.com`), o tipo de autenticação e, se houver, a **Credencial**, que é guardada cifrada. **3. Cole a especificação** Cole o **JSON** da especificação OpenAPI 3.0 e clique em **Importar**. Se o texto não for um JSON válido, a tela avisa "JSON inválido na spec OpenAPI". **4. Revise as ferramentas** Clique no conector na lista para ver as ferramentas geradas. Em cada uma, marque ou desmarque **Ativa** e, nas que devolvem dados de um cliente, preencha o **parâmetro de escopo (sub-cliente)**. | Autenticação | Como a credencial é enviada nas chamadas | | - | - | | **Sem autenticação** | Nenhuma credencial é enviada. | | **API Key** | No cabeçalho `X-API-Key`. | | **Bearer Token** | No cabeçalho `Authorization: Bearer `. | Essas são as três opções aceitas. OAuth não é oferecido: para APIs protegidas, use **API Key** ou **Bearer Token**. ### Como a especificação vira ferramentas * Cada operação `GET`, `POST`, `PUT`, `PATCH` ou `DELETE` vira uma ferramenta. * O nome da ferramenta é o `operationId`. Sem ele, a plataforma gera um nome a partir do método e do caminho. * O `summary` é a descrição que o bot lê para decidir quando usar a ferramenta. `operationId` e `summary` descritivos melhoram bastante a qualidade das respostas. * Os parâmetros de caminho e de query e as propriedades do corpo JSON (`application/json`) viram os campos que o bot preenche. Na chamada à sua API: * parâmetros de caminho (`/pedidos/{id}`) são substituídos na URL; * em `GET` e `DELETE`, os demais campos vão na query string; * em `POST`, `PUT` e `PATCH`, os demais campos vão no corpo, em JSON; * a resposta da sua API é repassada ao bot do jeito que chega, para ele montar a resposta ao cliente. ### Parâmetro de escopo O **parâmetro de escopo (sub-cliente)** é o nome do campo da operação que identifica o cliente (ex.: `customer_id`). Ele é salvo quando você sai do campo. Com ele preenchido: * a ferramenta só fica disponível **depois** que a conversa foi identificada; * o valor desse campo é **sempre** o sub-cliente da identificação, substituindo qualquer valor que o modelo de IA tenha tentado informar. Para que isso proteja os dados, basta que a sua API sempre filtre a resposta por esse parâmetro. Você não precisa escrever código específico para a OctaSend. ### Reimportar e excluir * Importar de novo um conector **com o mesmo nome** no mesmo bot atualiza a especificação e **substitui a lista de ferramentas**: elas voltam todas ativas e sem parâmetro de escopo, então revise-as depois. Se você deixar a credencial em branco, a anterior é mantida. * Excluir um conector pede confirmação e remove também todas as ferramentas dele. ### Pagamento por PIX Se uma ferramenta devolver um objeto `pix` no JSON de resposta, o bot trata o PIX de forma especial: ```json theme={null} { "pix": { "copia_e_cola": "00020126...", "qr_code_base64": "iVBORw0KGgo..." } } ``` * `copia_e_cola` — o código é enviado numa **mensagem separada**, para o cliente copiar com facilidade, e é retirado do texto da resposta para não aparecer duplicado. * `qr_code_base64` — uma imagem PNG em base64, enviada como **imagem** depois do texto. > [!NOTE] > > Para o passo a passo completo do que a sua API precisa expor, incluindo exemplos de requisição e resposta, fale com o time da OctaSend: existe uma especificação detalhada para repassar a quem for desenvolver a API. ## Como o atendimento acontece 1. O cliente manda uma mensagem para o número de um bot. Mensagens em **grupos** de WhatsApp nunca acionam o bot. 2. O bot só responde se o **módulo** estiver ligado, o bot estiver marcado como **ativo** e a conversa **não estiver pausada** por um atendente (veja [Quando uma pessoa assume a conversa](#quando-uma-pessoa-assume-a-conversa)). Em qualquer outro caso, a mensagem fica registrada sem resposta. 3. Se a mensagem for de voz, ela é transcrita conforme a configuração de [mensagens de voz](#mensagens-de-voz). Imagem, vídeo ou documento **com legenda** recebem resposta à legenda (o bot não enxerga o arquivo). Arquivos e figurinhas **sem texto** não recebem resposta. 4. O bot tenta identificar o cliente, se a identificação estiver configurada. 5. Se a base de conhecimento estiver ligada no bot, ele busca os trechos mais relevantes para a mensagem. 6. Se precisar de dado ao vivo, chama a sua API pelas ferramentas do conector, até o limite de chamadas por turno. 7. Responde ao cliente, seguindo as instruções da empresa, as instruções do bot e o tom de voz. Se o modelo de IA não produzir texto, envia a mensagem de fallback. Se ocorrer uma falha técnica ao processar a mensagem, o cliente recebe uma mensagem pedindo desculpas pelo problema e sugerindo tentar de novo. ## Mensagens de voz O bot responde a áudios pela transcrição. O comportamento depende de **Configurações → Geral**, seção **Conversas**, campo **Transcrição de áudios**: | Opção | Com o bot ativo na conversa | | - | - | | **Desligada** | Os áudios não são transcritos e o bot **não responde** mensagens de voz. É a opção padrão. | | **Automática** | Todo áudio recebido é transcrito, e o bot responde pela transcrição. | | **Ao clicar** | Você escolhe quais áudios transcrever na tela de conversas, mas, em conversas com o bot ativo, o áudio é transcrito sempre, para o bot poder responder. | Áudios com mais de **5 minutos** não são transcritos e, por isso, não recebem resposta do bot. ## Quando uma pessoa assume a conversa Um atendente pode responder o cliente pelo painel, em **WhatsApp → Conversas** (veja [Conversas e grupos de WhatsApp](https://docs.octasend.com.br/plataforma/whatsapp-conversas-e-grupos.md)): * Ao enviar uma mensagem manual, o bot fica **pausado por 30 minutos** naquela conversa. Cada novo envio manual reinicia os 30 minutos. Passado esse tempo, o bot volta a responder sozinho. * Enquanto a pausa durar, a conversa aparece com o aviso **Bot pausado** na lista, e as mensagens do cliente continuam sendo registradas, sem resposta automática. Dentro da conversa, a faixa **Bot pausado até HH:MM** tem o botão **Reativar bot**, que devolve a conversa ao bot na hora, sem esperar os 30 minutos. * A mensagem manual aparece no histórico com **Enviado por** e o nome de quem enviou. * Responder pelo aplicativo do WhatsApp no celular **não** pausa o bot: só o envio pelo painel pausa. * O envio manual pelo painel funciona em conversas de números conectados via QR code (Evolution API). A mensagem sai pelo **mesmo número em que o cliente escreveu**. Se esse número estiver desativado, o envio é recusado com um aviso para reativá-lo, em vez de sair por outro número. ## Acompanhar as conversas Na aba **Conversas** de cada bot você vê os atendimentos daquele número, do mais recente para o mais antigo, com o telefone, a origem da conexão (`evolution` para número conectado via QR code, `meta` para a API oficial), o estado da conversa e o sub-cliente identificado (ou "sem sub-cliente"). As mensagens recebidas em um número conectado que não tem bot também ficam registradas, só como histórico, nas conversas do bot mais antigo da conta: nenhum bot responde a elas. Por isso a aba **Conversas** do seu primeiro bot pode mostrar atendimentos de outros números. | Estado | O que significa | | - | - | | **Não identificado** | O bot ainda não atendeu nenhuma mensagem desta conversa (por exemplo, porque estava inativo quando o cliente escreveu). | | **Aguardando autenticação** | O bot pediu a credencial e está esperando a resposta do cliente. | | **Ativo** | O bot já atendeu a conversa. Se o cliente foi identificado, o sub-cliente aparece ao lado. | Abrindo uma conversa, você lê a troca de mensagens entre o cliente e o bot, incluindo as mensagens manuais. As consultas internas à sua API não aparecem. É útil para entender uma resposta ruim e ajustar as instruções ou a base de conhecimento. Esta tela é só de leitura: para responder, use **WhatsApp → Conversas**. ## Perguntas frequentes > [accordion] O bot não responde. O que conferir? > > * A chave **Módulo de chatbot** em **Chatbot → Chatbot WhatsApp** está ligada? > * O bot está com **Bot ativo no WhatsApp** marcado e salvo? > * A mensagem chegou no número desse bot? Números sem bot não têm resposta automática. > * Um atendente enviou mensagem manual pelo painel nos últimos 30 minutos? A conversa fica pausada. Use **Reativar bot** na conversa, em **WhatsApp → Conversas**, para devolvê-la ao bot antes disso. > * É uma mensagem de voz com a **Transcrição de áudios** desligada, ou um arquivo sem legenda? > * É uma mensagem de grupo? Grupos não acionam o bot. > [accordion] Uma fonte está parada em Pendente > > Clique em **Reprocessar** na lista ou na página da fonte para iniciar a leitura de novo. > [accordion] O bot não usa o conteúdo que acabei de cadastrar > > Confira se a fonte está **Pronta**, se o bot está com **Usar a base de conhecimento** ligado e, se a fonte for **Privado a um sub-cliente**, se a conversa já foi identificada com o mesmo ID de sub-cliente. > [accordion] O bot responde com a mensagem de fallback com frequência > > Revise as instruções do bot e o conteúdo da base. Se o bot usa muitas consultas à sua API por mensagem, aumente o **Limite de chamadas de tool por turno**: ao atingir o limite sem concluir, ele pode acabar enviando a mensagem de fallback. ## Pré-requisito O chatbot atende no **WhatsApp**, então o canal precisa estar configurado antes. Veja o guia de [WhatsApp](https://docs.octasend.com.br/guias/whatsapp.md). > [card] [Chatbot do site](https://docs.octasend.com.br/plataforma/chatbot-do-site.md) > > O assistente de IA no seu site, com a mesma base de conhecimento. > [card] [Conversas e grupos de WhatsApp](https://docs.octasend.com.br/plataforma/whatsapp-conversas-e-grupos.md) > > Acompanhe e responda as conversas manualmente. > [card] [Automações](https://docs.octasend.com.br/plataforma/automacoes.md) > > Etapas de IA com tom de voz e instruções da empresa. > [card] [WhatsApp](https://docs.octasend.com.br/guias/whatsapp.md) > > Conecte o número em que o bot vai atender. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.