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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMW1tRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--c67947dd227177261680e52e2a5cbab3169e7f62/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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMXFtRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--17fd4bd47d3079bf08b76a395a6f601350c2cfe8/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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMXVtRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--64bec170655d5ddb9982e4021b98a8e1a228c3c5/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 RockZap® 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`**](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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMWltRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--732be52caace74d6316d503abfb904763b9b4f15/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=`**](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.rockzap.com.br/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMXltRFE9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--0ea4c7c1b0a144b1856537db8a8b8f86ec72fd3d/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.