Como Configurar Ferramentas Personalizadas para o Captain

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:

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

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.