Ferramentas Personalizadas permitem que o Capitão chame suas APIs externas durante conversas — assim ele pode verificar status de garantia, confirmar cobertura de serviço ou buscar dados dos seus próprios serviços sem a necessidade de encaminhar para um atendente humano. Quando um cliente faz uma pergunta, o Capitão extrai os valores relevantes da conversa, insere esses valores na sua requisição de API e usa a resposta para formular a própria resposta. Ferramentas Personalizadas estão disponíveis no **plano Business** e superiores. ## Criando uma ferramenta Navegue até **Capitão -> Ferramentas** e clique em **Criar uma nova ferramenta**.\ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRkNNM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--df7aee7258ed39aa41dba2b379f759b0ea35e719/image.png)Preencha os seguintes campos: **Nome da ferramenta** — Um nome curto como "Consulta de Garantia" ou "Verificação de Área de Atendimento" (máx. 55 caracteres). **Descrição** — Explique ao Capitão quando usar esta ferramenta. Este é o campo mais importante. Escreva como se estivesse orientando um agente de suporte: "Verifica o status da garantia de um produto pelo número de série." Descrições vagas como "API de Garantia" farão com que o Capitão perca 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/warranty/{{ serial_number }}` A URL deve usar HTTPS, deve 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: * **Nenhuma** — Sem autenticação * **Token Bearer** — Envia seu token no cabeçalho `Authorization` * **Basic Auth** — Envia um nome de usuário e senha * **API Key** — Envia um nome de cabeçalho personalizado e valor (ex: `X-API-Key`) As credenciais de autenticação são visíveis apenas para administradores da conta. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCSHlQM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--f828a1d2122bd3e56593af9c548c54d0c068a9b5/image.png) \ **Parâmetros** — Defina o que o Capitão deve extrair da mensagem do cliente. Cada parâmetro precisa de um nome, tipo e descrição. Por exemplo: `serial_number` (String) — "O número de série do produto, localizado na parte de trás do aparelho." **Modelo de requisição** (apenas POST) — Um template de corpo JSON usando sintaxe Liquid. **Modelo de resposta** — Controla o que o Capitão verá da resposta da sua API. Se ficar em branco, o Capitão recebe o JSON puro. Use Liquid para extrair campos relevantes, por exemplo: `Série {{ response.serial_number }}: {{ response.warranty_status }}. Expira em: {{ response.expiry_date }}.` Use `response` para acessar o corpo JSON já analisado. Modelos de resposta ajudam o Capitão a focar nos dados relevantes e evitar campos internos como IDs de banco de dados ou informações de depuração. ## Testando sua ferramenta Clique em **Testar conexão** antes de salvar para verificar se o endpoint está acessível. O teste mostra o código de status HTTP.\ ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQXVUM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--a68a265c155a8d2863abd67094b035d5ee3c605f/image.png)Um resultado verde (HTTP 200–299) significa que a conexão e autenticação estão funcionando. Note que o teste envia a URL sem preencher os valores dos parâmetros, então só confirma que seu endpoint está acessível e suas credenciais são aceitas. Se o teste falhar, verifique o seguinte: * 401 Não autorizado — Suas credenciais de autenticação estão incorretas. Verifique seu token bearer, chave de API, ou usuário/senha. * 403 Proibido — Sua API está rejeitando a requisição. Se você exige verificação de identidade, note 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 funcionamento. * Timeout — Sua API demorou muito para responder. Ferramentas personalizadas têm um timeout de 30 segundos; certifique-se de que seu endpoint responde dentro desse tempo. ## Contexto enviado em toda chamada de ferramenta Quando o Capitão chama sua API, ele inclui cabeçalhos de metadados para que seu backend saiba o contexto: * `X-Chatwoot-Account-Id` — ID da sua conta * `X-Chatwoot-Conversation-Id` — ID da conversa * `X-Chatwoot-Contact-Email` — E-mail do cliente (se disponível) * `X-Chatwoot-Contact-Inbox-Verified` — Se a identidade do cliente tem verificação HMAC * `X-Chatwoot-Assistant-Id` — O assistente Capitão que está fazendo a chamada * `X-Chatwoot-Tool-Slug` — O identificador interno da ferramenta * `X-Chatwoot-Contact-Id` — ID de contato do cliente * `X-Chatwoot-Contact-Phone` — Telefone do cliente (se disponível) * `X-Chatwoot-Conversation-Display-Id` — Número de exibição da conversa Você pode usar esses cabeçalhos para localizar o cliente em seu próprio sistema, registrar quais conversas dispararam chamadas de API e verificar a autenticidade das requisições. ## 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 retorna dados específicos do cliente (pedidos, cobrança, detalhes de conta), sua API deve verificar o cabeçalho `X-Chatwoot-Contact-Inbox-Verified`. Sem verificação HMAC habilitada na sua caixa de entrada, um visitante poderia definir qualquer e-mail no widget do chat. Só retorne dados sensíveis quando este cabeçalho for `true`. Para ferramentas que retornam dados públicos esse controle não é necessário. **Prompt injection:** Se sua API retorna conteúdo gerado por usuários (avaliações, posts de fórum), textos maliciosos podem influenciar o comportamento do Capitão. Use modelos de resposta para extrair apenas campos estruturados, e faça a sanitização do conteúdo na sua API. ## Limites * **Máximo de ferramentas por conta** — 15 * **Recomendado** — 10 ou menos. Um aviso aparece acima de 10; mais ferramentas dificultam a escolha correta pelo Capitão. * **Comprimento do nome da ferramenta** — 55 caracteres * **Tamanho da resposta** — 1 MB máx. * **Tempo limite da requisição** — 30 segundos ## Quando usar ferramentas personalizadas Ferramentas personalizadas são mais indicadas para consultas estruturadas com entradas previsíveis — verificações de status do sistema, busca de agendas, ou busca de registros por ID. Se você já tem uma integração dedicada do Chatwoot para seu caso de uso (ex: Shopify para e-commerce), dê preferência a ela — integrações dedicadas lidam com buscas, correspondências aproximadas e sincronização de dados com mais confiabilidade do que uma chamada API única. ## Exemplos ### Consulta de Garantia Quando um cliente pergunta se o produto ainda está em garantia, o Capitão pode verificar usando o número de série. * **Nome da ferramenta:** Consulta de Garantia * **Descrição:** Verifica o status da garantia de um produto pelo número de série. Use quando um cliente perguntar se o produto está coberto, quando expira a garantia ou que tipo de cobertura ele tem. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTjJDM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--a80054243f53a3e776ee0a03230ada57c79f0da8/CleanShot%202026-04-01%20at%2018.40.03@2x.png) ### **Verificação de Área de Atendimento** Para empresas que atuam em regiões específicas — clientes perguntam se o atendimento está disponível no local deles. * **Nome da ferramenta:** Verificação de Área de Atendimento * **Descrição:** Verifica se serviço ou entrega está disponível em determinada área usando o CEP ou nome da cidade do cliente. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCT3lCM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--de09f1cf35338a45a7d40dd662e2cc0c1d77aa94/CleanShot%202026-04-01%20at%2018.38.23@2x.png) Ferramentas Personalizadas 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 ideais para esse recurso.