Chatwoot
pt_BR
Idioma
en English pt_BR Portuguese (Brazil)

Como configurar ferramentas personalizadas para o Captain?

Abrir em
Ver como Markdown Abrir no ChatGPT Abrir no Claude
Pranav

Pranav

Última atualização em Jun 3, 2026

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.
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.


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.
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.

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.

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.