Hey 👋, how can we help you?
Pesquise os artigos aqui ou navegue pelas categorias abaixo.
Navegar por tópico
Encontre guias, tutoriais e respostas organizados por categoria.
Chatwoot 101
Comece por aqui para entender o Chatwoot, os principais conceitos e como a plataforma ajuda a gerenciar conversas com clientes.
Navegar
Configuração da conta
Configure sua conta, espaço de trabalho, equipes, usuários e ajustes básicos antes de começar.
Navegar
Chat ao vivo no site
Aprenda a instalar, configurar e personalizar o widget de chat ao vivo do Chatwoot no seu site ou aplicativo.
Navegar
Outros canais
Conecte e gerencie canais como email, WhatsApp, Facebook, Instagram, Telegram e outros.
Navegar
Canais de voz
Aprenda como conectar provedores de voz, gerenciar chamadas recebidas e configurar o atendimento telefônico no Chatwoot.
Navegar
Funcionalidades principais
Entenda os principais recursos do Chatwoot para gerenciar caixas de entrada, conversas, contatos, equipes e fluxos de trabalho.
Navegar
Apps e integrações
Conecte o Chatwoot a ferramentas e serviços externos para ampliar seus fluxos de atendimento.
Navegar
Funcionalidades avançadas
Explore recursos avançados como automações, regras de atribuição, atributos personalizados, macros, SLAs e webhooks.
Navegar
Relatórios
Use relatórios e análises para medir desempenho da equipe, volume de conversas, tempos de resposta e qualidade do atendimento.
Navegar
Central de ajuda
Crie, organize e publique artigos na central de ajuda para que os clientes encontrem respostas por conta própria.
Navegar
Boas práticas
Recomendações práticas para ajudar sua equipe a obter melhores resultados com o Chatwoot.
Navegar
Captain
Aprenda a configurar e usar o Captain, o agente de IA do Chatwoot para atendimento ao cliente.
Navegar
Migrações
Guias para ajudar você a migrar de plataformas como Zendesk, Freshdesk, Intercom e outras para o Chatwoot.
Navegar
Outros tópicos
Guias e referências adicionais que não se encaixam nas principais categorias do produto.
Navegar
Guias práticos
Guias passo a passo para tarefas comuns e casos de uso específicos no Chatwoot.
Navegar
Artigos populares
O que outras pessoas estão lendo agora.
Como usar o Captain Copilot?
Captain Copilot foi desenvolvido para ajudar agentes de suporte a trabalharem de forma mais inteligente, fornecendo sugestões e insights úteis diretamente do seu painel. Aqui está um guia para ajudá-lo a tirar o máximo proveito do Captain Copilot. Onde encontrar o Copilot? Para começar, certifique-se de que o Captain Copilot está habilitado na sua caixa de entrada. Abra seu painel e vá para a tela de conversas. No lado direito, você verá a guia Copilot ao lado das opções de contato. Clique na guia Copilot para acessar e começar a usar seus recursos. Como o Copilot funciona? O Copilot é uma ferramenta que pode melhorar a comunicação de várias maneiras. Ele pode analisar a conversa atual e redigir uma resposta apropriada ou até mesmo traduzir uma mensagem para outro idioma, garantindo que o tom e o contexto permaneçam intactos. Além disso, o Copilot pode analisar o tom da conversa, identificar pontos de melhoria e sugerir ajustes para alinhar melhor com a voz e os valores da sua marca. Para aprimorar ainda mais a experiência, o Copilot também pode encontrar artigos ou recursos relevantes relacionados à conversa atual, oferecendo acesso rápido a informações que apoiam suas respostas. Com sua capacidade de reduzir falhas de comunicação, refinar o tom e fornecer insights práticos. Como usar o copilot? Basta digitar seu pedido em linguagem natural, e o Captain irá analisá-lo para fornecer a melhor resposta. Você pode usá-lo para redigir respostas, traduzir mensagens ou melhorar o tom. Para melhores resultados, faça pedidos claros e específicos. Por exemplo, ao invés de dizer, “Ajude com essa resposta,” tente, “Escreva uma resposta educada explicando o atraso e oferecendo um novo prazo.” O Captain usa o conhecimento dos seus documentos para criar respostas precisas e relevantes. Aqui está um exemplo rápido de como redigir uma resposta. Quando o Captain sugerir uma resposta, clique em “Usar esta” para adicioná-la diretamente à sua janela de mensagens. Dicas Adicionais para Uso Eficaz - Sempre revise as sugestões do Copilot antes de enviá-las para garantir que estejam alinhadas com o tom e as diretrizes da sua equipe. - Utilize as recomendações do Copilot para preencher quaisquer lacunas na comunicação com o cliente, como adicionar instruções mais detalhadas ou esclarecer pontos ambíguos. - Incentive sua equipe a explorar e utilizar o Copilot regularmente para uma colaboração mais fluida e interações melhoradas com os clientes.
🔥 CaptainComo habilitar o Captain em instalações auto-hospedadas?
O Captain é um assistente de IA que ajuda você a responder mais rápido e com maior precisão. Com o Bring Your Own Key (BYOK), você pode usar sua própria chave de API da OpenAI ou de qualquer serviço de IA compatível. Você controla os dados, os custos e qual modelo é utilizado. Em uma instalação auto-hospedada, o Captain só envia dados para o modelo de IA que você escolher. Este guia vai mostrar como habilitar o Captain na sua Enterprise Edition auto-hospedada, adicionar sua chave de API e configurar um modelo personalizado, se desejar. Pré-requisitos Antes de começar, certifique-se de que você possui: - Chatwoot Enterprise Edition com um plano pago. - Acesso de administrador ao Super Admin Console. - Uma chave de API OpenAI válida. - (Opcional) Um endpoint de API compatível com OpenAI auto-hospedado. - (Opcional) Uma chave de API Firecrawl para uma melhor varredura de documentação. Habilitando o Captain no Super Admin Console Para habilitar o Captain no nível da instalação: Faça login no Super Admin Console. Navegue até Configurações → Captain. Preencha os campos de configuração: 1. Chave de API OpenAI (Obrigatório) – A chave para autenticar solicitações para a OpenAI ou serviço compatível. 2. Modelo OpenAI (Obrigatório) – O padrão é gpt-4o-mini. Você pode escolher outro modelo suportado como gpt-5. 3. Endpoint de API OpenAI (Opcional) – Insira seu endpoint de API personalizado caso esteja usando um modelo auto-hospedado. 4. Chave de API Firecrawl (Opcional) – Recomendado para melhor varredura de sites e documentação. Clique em Enviar para salvar sua configuração. Habilitando o Captain para uma Conta Depois de habilitar o Captain globalmente, ative-o para contas individuais: 1. No Super Admin Console, acesse Contas. 2. Selecione a conta para a qual deseja habilitar o Captain e clique em Editar. 3. Na seção Recursos Premium, ative o Captain. 4. Salve as alterações. Solução de problemas Se o Captain não estiver respondendo conforme o esperado: - Verifique se a chave de API OpenAI está correta e ativa. - Confira se o nome do modelo corresponde a um modelo suportado. - Certifique-se de que sua chave de API Firecrawl é válida caso esteja utilizando a varredura. - Confirme que o Captain está ativado tanto no nível da instalação quanto da conta. Se o Captain ainda não estiver respondendo, revise os logs do servidor Chatwoot tanto dos processos web quanto do worker para identificar quaisquer erros e compartilhe esses detalhes de erro com a equipe de suporte para uma assistência adicional.
🔥 CaptainO Capitão decide resolver automaticamente ou repassar as conversas
Quando o Captain lida com uma conversa com o cliente, ela não permanece no estado "pendente" para sempre. Após um período de inatividade, o Captain avalia a conversa e decide por um de dois desfechos: resolver (se as necessidades do cliente foram atendidas) ou transferir para um agente humano (se algo ainda está pendente). Este artigo explica como essa decisão funciona e o que você pode esperar. O fluxo de auto-resolução Veja o que acontece depois que o Captain responde a um cliente: 1. A conversa permanece com status Pendente enquanto o Captain está cuidando dela. 2. Se não houver nova atividade por 1 hora, o Captain avalia a conversa. 3. Com base na avaliação, o Captain irá: - Resolver a conversa — envia uma mensagem de resolução e a encerra. - Transferir para um agente humano — reabre a conversa para que sua equipe possa assumi-la. Em ambos os casos, o Captain adiciona uma nota privada explicando por que tomou a decisão. Como o Captain avalia uma conversa O Captain lê toda a conversa e verifica se as necessidades do cliente foram atendidas. A avaliação é intencionalmente conservadora — em caso de dúvida, o Captain mantém a conversa aberta e transfere para um humano. É melhor que um agente encontre uma conversa que talvez não precisasse de atenção do que um cliente tenha sua conversa encerrada enquanto ainda precisa de ajuda. Quando o Captain resolve O Captain resolve uma conversa quando tem confiança de que a dúvida do cliente foi completamente respondida e não resta nada para acompanhar. O cliente não precisa dizer explicitamente "obrigado" ou confirmar — se o Captain deu uma resposta completa e o cliente não fez outra pergunta, isso já é suficiente. Por exemplo, se um cliente perguntar "Quais são o horário de funcionamento?" e o Captain responder com os horários, e o cliente não responder por uma hora — o Captain irá resolver. A resposta era autoexplicativa e completa. O Captain também resolve quando o cliente envia um texto sem sentido ou só palavras soltas sem nenhuma pergunta clara, e o Captain pediu esclarecimento mas não teve resposta. Quando o Captain transfere O Captain transfere para um humano sempre que houver uma chance de que o cliente ainda precise de ajuda. Alguns exemplos comuns: - O Captain sugeriu que o cliente tente algo (como limpar o cache ou atualizar uma configuração) — o cliente pode ainda estar tentando isso. - O Captain apontou o cliente para um link externo ou recurso — ele pode ainda estar consultando. - O cliente pediu algo que o Captain não pôde fazer — mesmo se o Captain explicou o motivo, a necessidade está pendente. - O cliente levantou vários pontos e nem todos foram respondidos. O princípio orientador: se houver qualquer dúvida sobre o cliente ter terminado, o Captain vai preferir manter a conversa aberta para sua equipe. O que o cliente vê Quando o Captain resolve: O cliente recebe uma mensagem de resolução. Você pode personalizar essa mensagem nas configurações do seu assistente Captain — se não configurar, uma mensagem padrão será utilizada. Quando o Captain transfere: Se você definiu uma mensagem de transferência nas configurações do assistente Captain, o cliente verá essa mensagem. O status da conversa muda para Aberta, e sua equipe pode visualizá-la na fila. Se sua equipe estiver fora do horário comercial, o cliente também recebe automaticamente sua mensagem de ausência. Perguntas frequentes O auto-resolve funciona em todos os idiomas? Sim. O Captain avalia as conversas com base no significado e na intenção, independentemente do idioma utilizado. Onde posso ver por que o Captain resolveu ou transferiu uma conversa? Verifique a conversa para uma nota privada do Captain. Ele adiciona uma nota com sua justificativa antes de cada decisão de resolução ou transferência. Não quero que o Captain auto-resolva conversas na minha conta. Entre em contato com nossa equipe de suporte e podemos desativar o auto-resolve para sua conta.
🌟 Apps e integraçõesComo usar webhooks?
Webhooks são callbacks HTTP configurados para cada conta. Eles são acionados quando ações como a criação de uma mensagem ocorrem no Chatwoot. Vários webhooks podem ser criados para uma única conta. Como adicionar um webhook? Passo 1. Acesse Configurações → Integrações → Webhooks. Clique no botão "Configurar". Passo 2. Clique no botão "Adicionar novo webhook". Um modal será aberto. Aqui, insira a URL para a qual a requisição POST deve ser enviada. Em seguida, você precisa selecionar os eventos aos quais deseja se inscrever. Esta opção permite que você escute apenas pelos eventos relevantes no Chatwoot. O Chatwoot enviará uma requisição POST com o seguinte payload para as URLs configuradas para diversas atualizações em sua conta. Exemplo de payload de webhook { "event": "message_created", // Nome do evento "id": "1", // ID da mensagem "content": "Hi", // Conteúdo da mensagem "created_at": "2020-03-03 13:05:57 UTC", // Hora em que a mensagem foi enviada "message_type": "incoming", // Terá o valor incoming, outgoing ou template. O usuário do widget envia mensagens incoming, o agente envia mensagens outgoing para o usuário. "content_type": "enum", // Isto é um enum, pode ser input_select, cards, form ou text. O message_type será template se o content_type for um destes. O valor padrão é text "content_attributes": {} // Será um objeto, valores diferentes são definidos abaixo "source_id": "", // Será o id externo se a caixa de entrada for uma integração com Twitter ou Facebook. "sender": { // Proverá detalhes do agente que enviou a mensagem "id": "1", "name": "Agent", "email": "[email protected]" }, "contact": { // Proverá detalhes do usuário que enviou a mensagem "id": "1", "name": "contact-name" }, "conversation": { // Proverá detalhes da conversa "display_id": "1", // ID da conversa visível no dashboard. "additional_attributes": { "browser": { "device_name": "Macbook", "browser_name": "Chrome", "platform_name": "Macintosh", "browser_version": "80.0.3987.122", "platform_version": "10.15.2" }, "referer": "<http://www.chatwoot.com>", "initiated_at": "Tue Mar 03 2020 18:37:38 GMT-0700 (Mountain Standard Time)" } }, "account": { // Proverá detalhes da conta "id": "1", "name": "Chatwoot", } } Eventos de webhook suportados no Chatwoot O Chatwoot publica vários eventos para os endpoints de webhook configurados. Se você quiser configurar um webhook, consulte o guia aqui. Cada evento possui sua estrutura de payload com base no tipo de modelo sobre o qual atuam. A seção a seguir descreve os principais objetos que usamos no Chatwoot e seus atributos. Objetos Um payload de evento pode incluir qualquer um dos seguintes objetos. Os vários tipos de objetos suportados pelo Chatwoot estão listados abaixo. Conta { "id": "integer", "name": "string" } Caixa de entrada { "id": "integer", "name": "string" } Contato { "id": "integer", "name": "string", "avatar": "string", "type": "contact", "account": { // <...Objeto Conta> } } Usuário { "id": "integer", "name": "string", "email": "string", "type": "user" } Conversa { "additional_attributes": { "browser": { "device_name": "string", "browser_name": "string", "platform_name": "string", "browser_version": "string", "platform_version": "string" }, "referer": "string", "initiated_at": { "timestamp": "iso-datetime" } }, "can_reply": "boolean", "channel": "string", "id": "integer", "inbox_id": "integer", "contact_inbox": { "id": "integer", "contact_id": "integer", "inbox_id": "integer", "source_id": "string", "created_at": "datetime", "updated_at": "datetime", "hmac_verified": "boolean" }, "messages": ["Array de objetos de mensagem"], "meta": { "sender": { // Objeto Contato }, "assignee": { // Objeto Usuário } }, "status": "string", "unread_count": "integer", "agent_last_seen_at": "unix-timestamp", "contact_last_seen_at": "unix-timestamp", "timestamp": "unix-timestamp", "account_id": "integer" } Mensagem { "id": "integer", "content": "string", "message_type": "integer", "created_at": "unix-timestamp", "private": "boolean", "source_id": "string / null", "content_type": "string", "content_attributes": "object", "sender": { "type": "string - contact/user" // Objeto Usuário ou Contato }, "account": { // Objeto Conta }, "conversation": { // Objeto Conversa }, "inbox": { // Objeto Caixa de entrada } } Exemplo de payload de webhook { "event": "event_name" // Atributos relacionados ao evento } Eventos de Webhook O Chatwoot suporta os seguintes eventos de webhook. Você pode se inscrever neles ao configurar um webhook no painel ou utilizando a API. conversation_created Este evento será acionado quando uma nova conversa for criada na conta. O payload do evento é o seguinte. { "event": "conversation_created" // <...Atributos da Conversa> } conversation_updated Este evento será acionado quando houver uma alteração em algum dos atributos da conversa. { "event": "conversation_updated", "changed_attributes": [ { "<nome_do_atributo>": { "current_value": "", "previous_value": "" } } ] // <...Atributos da Conversa> } conversation_status_changed Este evento será acionado quando o status da conversa for alterado. Nota: Se você estiver utilizando APIs de agent bot em vez de webhooks, este evento ainda não é suportado. { "event": "conversation_status_changed" // <...Atributos da Conversa> } message_created Este evento será acionado quando uma mensagem for criada em uma conversa. O payload do evento é o seguinte. { "event": "message_created" // <...Atributos da Mensagem> } message_updated Este evento será acionado quando uma mensagem for atualizada em uma conversa. O payload do evento é o seguinte. { "event": "message_updated" // <...Atributos da Mensagem> } webwidget_triggered Este evento será acionado quando o usuário final abrir o widget de chat ao vivo. { "event": "webwidget_triggered", "id": "", "contact": { // <...Objeto Contato> }, "inbox": { // <...Objeto Caixa de Entrada> }, "account": { // <...Objeto Conta> }, "current_conversation": { // <...Objeto Conversa> }, "source_id": "string", "event_info": { "initiated_at": { "timestamp": "date-string" }, "referer": "string", "widget_language": "string", "browser_language": "string", "browser": { "browser_name": "string", "browser_version": "string", "device_name": "string", "platform_name": "string", "platform_version": "string" } } } conversation_typing_on Este evento é acionado quando um agente começa a digitar em uma conversa. Pode ser uma nota privada ou uma mensagem para o cliente. Você pode usar o flag is_private para diferenciar entre os dois. { "event": "conversation_typing_on", "conversation": { ...<Objeto Conversa> }, "user": { ... <Usuário / AgentBot / Objeto Capitão> }, "is_private": true } conversation_typing_off Este evento é acionado quando o agente para de digitar ou sai da janela da conversa. { "event": "conversation_typing_off", "conversation": { ...<Objeto Conversa> }, "user": { ... <Usuário / AgentBot / Objeto Capitão> }, "is_private": true } Verificando webhooks O Chatwoot assina todas as requisições de webhook de saída para que seu servidor possa verificar se o payload foi enviado pelo Chatwoot e não foi adulterado. O segredo é exibido uma vez que o webhook é criado, e você pode visualizá-lo novamente no formulário de edição do webhook. Toda requisição de webhook envia os seguintes cabeçalhos, que podem ser usados para calcular a assinatura HMAC do payload - X-Chatwoot-Signature: assinatura HMAC-SHA256 prefixada com sha256= - X-Chatwoot-Timestamp: timestamp Unix (segundos) de quando a requisição foi assinada - X-Chatwoot-Delivery: ID único de entrega para o evento de webhook (quando disponível) A assinatura é calculada assim: sha256=HMAC-SHA256(webhook_secret, "{timestamp}.{raw_body}") Onde: - webhook_secret é o segredo associado ao webhook - timestamp é o valor do cabeçalho X-Chatwoot-Timestamp - raw_body é o corpo da requisição JSON bruta (não parseado/re-serializado) Passos de Verificação 1. Extraia X-Chatwoot-Signature e X-Chatwoot-Timestamp dos cabeçalhos da requisição 2. Leia o corpo bruno da requisição como bytes (não parse e re-serialize) 3. Calcule a assinatura esperada: sha256=HMAC-SHA256(secret, "{timestamp}.{raw_body}") 4. Compare a assinatura calculada com a recebida usando uma comparação em tempo constante 5. Opcionalmente, rejeite requisições cujo timestamp seja muito antigo para prevenir ataques de repetição (replay) Exemplos Ruby def verify_signature(raw_body, timestamp, received_signature, secret) expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}.#{raw_body}")}" ActiveSupport::SecurityUtils.secure_compare(expected, received_signature) end Python import hmac import hashlib def verify_signature(raw_body: bytes, timestamp: str, received_signature: str, secret: str) -> bool: message = f"{timestamp}.".encode() + raw_body expected = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, received_signature) Node.js const crypto = require("crypto"); function verifySignature(rawBody, timestamp, receivedSignature, secret) { const message = `${timestamp}.${rawBody}`; const expected = "sha256=" + crypto.createHmac("sha256", secret).update(message).digest("hex"); return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(receivedSignature) ); } Go import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "fmt" ) func verifySignature(rawBody []byte, timestamp, receivedSignature, secret string) bool { mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(fmt.Sprintf("%s.%s", timestamp, rawBody))) expected := "sha256=" + hex.EncodeToString(mac.Sum(nil)) return hmac.Equal([]byte(expected), []byte(receivedSignature)) } Notas Importantes - Sempre utilize o corpo bruto da requisição para verificação. Fazer o parse do JSON e depois re-serializar pode alterar a ordenação das chaves, espaços ou escape unicode, o que resultará em uma assinatura diferente. - Sempre utilize comparação em tempo constante (ex: hmac.compare_digest, crypto.timingSafeEqual, ActiveSupport::SecurityUtils.secure_compare) para prevenir ataques de timing. - Considere rejeitar requisições com timestamp mais antigos que 5 minutos para mitigar ataques de repetição.
🔥 CaptainCriando um assistente com o Captain
O Assistente no Captain foi desenvolvido para ajudar a responder perguntas de clientes, fornecer soluções e auxiliar com questões relacionadas ao produto. Ele aprende com os artigos da sua central de ajuda e conversas passadas para fornecer respostas precisas. Quando vinculado a uma caixa de entrada, pode gerenciar conversas diretamente com seus clientes. Como criar um assistente no Captain? Se você possui um plano pago no Chatwoot Cloud, encontrará o menu Captain na barra lateral esquerda. Neste menu, você verá as opções Assistentes, Documentos e FAQs. Clique em Assistentes. Você verá uma página como a mostrada abaixo. Clique no botão Criar um novo Assistente. Aqui estão os campos disponíveis atualmente no formulário para criar um assistente: | Nome do Campo | Descrição | Padrão | Obrigatório | | -- | -- | -- | --| | Nome do Assistente | Este é o nome interno do assistente | -- | Sim | | Descrição | Forneça uma descrição sobre o que o assistente faz. Nota: Isto não é uma instrução para o assistente | -- | Sim| | Nome do Produto | Isto é importante. O assistente é criado em torno do produto, ter o nome do produto ajudará a identificar lacunas de conteúdo e perguntas dos usuários | -- | Sim | | Funcionalidade: Ativar FAQs a partir de conversas resolvidas | Se você ativar esta opção, o Assistente Captain tentará identificar lacunas nos artigos da central de ajuda e sugerirá novas FAQs, consulte o documento de FAQ para mais detalhes | false | Não | | Funcionalidade: Capturar detalhes importantes como memórias das interações com clientes | Se ativado, tentará identificar detalhes importantes das conversas e salvará nas notas | false | Não | Depois de inserir os detalhes, clique em Criar e seu assistente será adicionado à sua conta! Você pode criar múltiplos assistentes para lidar com diferentes casos de uso, se necessário. Como conectar um assistente às caixas de entrada? Adicionar um assistente à sua conta não o conecta automaticamente a todas as caixas de entrada. Você precisará vincular manualmente cada assistente às caixas de entrada relevantes onde ele é necessário. Isso oferece flexibilidade para atribuir assistentes com base em produtos específicos ou segmentos de cliente. Para conectar um assistente, clique no menu de três pontos ao lado dos detalhes do assistente. No menu suspenso, selecione Ver Caixas de Entrada Conectadas. Isso levará você a uma página exibindo todas as caixas de entrada vinculadas ao assistente. A partir daí, você pode gerenciar as conexões. Nota: Cada caixa de entrada pode ser conectada a apenas um assistente por vez. Clique em Conectar uma Nova Caixa de Entrada para ver uma lista de caixas de entrada disponíveis. Selecione uma caixa de entrada da lista e conecte. Pronto! O assistente já está ativo na caixa de entrada. Experimente—envie uma mensagem no chat e veja se ele responde com a saudação inicial. Você pode implantar o assistente em qualquer caixa de entrada disponível, seja chat ao vivo, WhatsApp, Instagram, e-mail ou outros. Pronto! O assistente foi configurado com sucesso. No entanto, neste estágio, ele ainda não possui nenhum conhecimento sobre o seu negócio ou produto. Após a saudação inicial, o assistente tentará transferir a conversa para um agente. Para fornecer contexto sobre seu produto ao assistente, você pode adicionar documentos. Saiba mais sobre documentos neste artigo.
🔥 CaptainComo Configurar Ferramentas Personalizadas para o Captain
Custom Tools permitem que o Captain chame suas APIs externas durante conversas — assim ele pode verificar o status do sistema, consultar horários ou buscar dados dos seus próprios serviços sem encaminhar para um agente humano. Quando um cliente faz uma pergunta, o Captain extrai os valores relevantes da conversa, insere-os na requisição à sua API e usa a resposta para formar a sua resposta. Custom Tools está disponível no plano Business e superiores. Criando uma ferramenta Navegue até Captain -> Ferramentas e clique em Criar uma nova ferramenta. Preencha os seguintes campos: Nome da Ferramenta — Um nome curto como "Status do Sistema" ou "Consulta de Horários" (máx. 55 caracteres). Descrição — Indique ao Captain quando usar esta ferramenta. Este é o campo mais importante. Escreva como se estivesse instruindo um agente de suporte: "Verifica o status atual do sistema, incluindo quaisquer incidentes em andamento ou manutenção." Descrições vagas como "API de Status" farão o Captain perder oportunidades de usar a ferramenta. Método — Escolha GET (para buscar dados) ou POST (para enviar dados). URL do Endpoint — A URL da sua API. Use {{ parameter_name }} para inserir valores extraídos da conversa: https://api.yourcompany.com/v1/showtimes?q={{ query }} A URL deve usar HTTPS, ser um hostname (não um endereço IP), e não pode apontar para localhost ou redes privadas. Autenticação — Escolha como sua API autentica as requisições: | Tipo | O que você fornece | |------|-------------------| | Nenhum | Sem autenticação | | Bearer Token | Uma string de token | | Basic Auth | Nome de usuário e senha | | API Key | Um nome de cabeçalho personalizado e valor | As credenciais de autenticação são visíveis apenas para administradores da conta. Parâmetros — Defina o que o Captain deve extrair da mensagem do cliente. Cada parâmetro precisa de um nome, tipo e descrição. Por exemplo: query (String) — "O título do filme ou data que o cliente está perguntando." Template de Requisição (apenas POST) — Um template de corpo JSON usando sintaxe Liquid: { "query": "{{ query }}", "source": "captain" } Template de Resposta — Controla o que o Captain vê da resposta da sua API. Se ficar em branco, o Captain recebe o JSON bruto. Use Liquid para extrair campos relevantes: Status do sistema: {{ response.status }}. {{ response.message }} Use response para acessar o corpo JSON analisado. Templates de resposta ajudam o Captain a focar apenas nos dados relevantes e evitar campos internos como IDs de banco de dados ou informações de debug. Testando sua ferramenta Clique em Testar conexão antes de salvar para verificar se seu endpoint está acessível. O teste mostra o código de status HTTP. Um resultado verde (HTTP 200–299) significa que a conexão e a autenticação estão funcionando. Note que o teste envia a URL sem preencher os valores de parâmetro, então ele apenas verifica se seu endpoint está acessível e se suas credenciais foram aceitas. Se o teste falhar, verifique o seguinte: - 401 Não autorizado — Suas credenciais de autenticação estão incorretas. Verifique o bearer token, chave API ou nome de usuário/senha. - 403 Proibido — Sua API está rejeitando a requisição. Se você exigir verificação de identidade, observe que requisições de teste não incluem cabeçalhos de contato. - 404 Não encontrado — A URL do endpoint está errada. Verifique o caminho e confirme se sua API está em execução. - Timeout — Sua API demorou muito para responder. As ferramentas customizadas têm um timeout de 30 segundos; certifique-se de que seu endpoint responda dentro desse prazo. Contexto enviado em cada chamada de ferramenta Quando o Captain chama sua API, ele inclui cabeçalhos de metadados para que seu backend saiba o contexto: | Cabeçalho | Descrição | |-----------|------------| | X-Chatwoot-Account-Id | O ID da sua conta | | X-Chatwoot-Conversation-Id | O ID da conversa | | X-Chatwoot-Contact-Email | O e-mail do cliente (se disponível) | | X-Chatwoot-Contact-Inbox-Verified | Se a identidade do cliente está verificada por HMAC | Cabeçalhos adicionais incluem X-Chatwoot-Assistant-Id, X-Chatwoot-Tool-Slug, X-Chatwoot-Contact-Id, X-Chatwoot-Contact-Phone e X-Chatwoot-Conversation-Display-Id. Você pode usar esses cabeçalhos para buscar o cliente em seu próprio sistema, registrar quais conversas acionaram chamadas à API e verificar a autenticidade da requisição. Segurança Proteções nativas: - Todos os endpoints devem usar HTTPS - Requisições para faixas de IP privadas, localhost e domínios .local são bloqueadas - Redirecionamentos HTTP não são seguidos - Respostas são limitadas a 1 MB - Credenciais de autenticação são visíveis apenas para administradores Verificação de identidade: Se sua ferramenta retornar dados específicos do cliente (pedidos, faturamento, detalhes de conta), sua API deve verificar o cabeçalho X-Chatwoot-Contact-Inbox-Verified. Sem verificação HMAC ativada no seu inbox, um visitante pode definir qualquer endereço de e-mail no widget de chat. Só retorne dados sensíveis quando este cabeçalho for true. Para ferramentas que retornam dados públicos (horários, status do sistema), essa checagem não é necessária. Prompt injection: Se sua API retornar conteúdo gerado por usuários (avaliações, postagens de fórum), textos maliciosos podem influenciar o comportamento do Captain. Use templates de resposta para extrair apenas campos estruturados, e sanitize conteúdos em sua API. Limites | Limite | Valor | |--------|-------| | Máximo de ferramentas por conta | 15 | | Recomendado | 10 ou menos (um aviso aparece acima de 10) | | Tamanho do nome da ferramenta | 55 caracteres | | Tamanho da resposta | 1 MB máx. | | Timeout da requisição | 30 segundos | Quando usar ferramentas customizadas Ferramentas customizadas são mais indicadas para consultas estruturadas com entradas previsíveis — verificar status do sistema, buscar horários ou consultar registros por ID. Se você já possui uma integração dedicada do Chatwoot para seu caso de uso (ex.: Shopify para e-commerce), use-a em vez disso — integrações dedicadas lidam com buscas, correspondência difusa e sincronização de dados de forma mais confiável do que uma única chamada de API. Exemplos Verificação de Status do Sistema Uma ferramenta simples sem parâmetros — o Captain a aciona quando um cliente pergunta se algo está fora do ar. | Campo | Valor | |-------|-------| | Nome da Ferramenta | Status do Sistema | | Descrição | Verifica o status operacional atual do sistema, incluindo qualquer incidente em andamento ou manutenção programada. Use quando um cliente relatar problemas ou perguntar se o sistema está fora do ar. | | Método | GET | | URL do Endpoint | https://status.yourcompany.com/api/v1/status | | Autenticação | Nenhuma | | Parâmetros | (nenhum) | | Template de Resposta | Status do sistema: {{ response.status }}. {{ response.message }} | Consulta de Sessões / Horários Para empresas que têm horários, tabelas ou listas de eventos — os clientes perguntam o que está disponível e o Captain busca a agenda atual. | Campo | Valor | |-------|-------| | Nome da Ferramenta | Consulta de Horários | | Descrição | Consulta horários de filmes e exibições em cartaz. Use quando um cliente perguntar quais filmes estão passando ou quando um filme específico será exibido. | | Método | GET | | URL do Endpoint | https://api.yourcinema.com/v1/showtimes?q={{ query }} | | Autenticação | Bearer Token | | Parâmetros | query (String, obrigatório) — "O título do filme ou data da sessão que o cliente está perguntando" | | Template de Resposta | {% for show in response.showtimes %}{{ show.title }} — {{ show.date }} às {{ show.time }}{% endfor %} | Ferramentas customizadas funcionam melhor quando as entradas são diretas e a resposta da API é previsível — verificações de status, consultas e outras buscas estruturadas são opções ideais.