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

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQ1FZM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cb577b7e950815be109f2925cac60ce4b25305ac/CleanShot%202026-04-01%20at%2015.53.06@2x.png)

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.

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRDQ4M1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--dc19f2d14e08901f6921007175ffd5399064a947/CleanShot%202026-04-01%20at%2016.52.41@2x.png)

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

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCREk5M1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--8a952a29edf820a845a1a3ca27072386c225eeef/image.png)

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 }}` |

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTVViM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--243c121ad98c746cdbfb6aae317471cc2485ccad/CleanShot%202026-04-01%20at%2015.59.39@2x.png)

### 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 %}` |

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCREViM1FRPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2a8aaa32f6747f6cdfca6d3abcac3b62bce5060f/image.png)

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.