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