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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMSttRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--4bc0544c2a217533221a826575f28a9aacb9ea22/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/`**](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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMkdtRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cd8b7ee60b9b8c6a52f8844ee25bca1b9d920398/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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMk9tRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--be3e2945dbefab8815d5511c3230491d2af39fed/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 RockZap® 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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMkNtRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--969cfcc3b23a0a395ad1bf2696b1feb0416172d2/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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMkttRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--defef88f5fe53cbc2809c29494075cf996a74a6b/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.