Configurar ferramentas personalizadas para o Capitão

Descubra

Ferramentas personalizadas permitem que o assistente acesse seus próprios sistemas durante uma conversa, por exemplo, para verificar um pedido, uma garantia ou uma reserva, em vez de encaminhar o atendimento.

Plano & acesso: Business ou Enterprise (Pricing & Plans). No Startups, Ferramentas geralmente mostra Atualize para usar ferramentas com o Captain. Cada assistente tem sua própria lista de ferramentas. Administradores criam ferramentas, e apenas administradores podem ver as credenciais salvas. Self-hosted: o Super Admin ativa as Ferramentas Personalizadas para a conta.

Configure e teste

Antes de começar

• Um endpoint HTTPS em um hostname público. O Chatwoot bloqueia HTTP simples, endereços IP, localhost, redes privadas e endereços .local.

• O endpoint deve aceitar a conexão em até 2 segundos e responder em até 20 segundos, com uma resposta de no máximo 1 MB.

• Suas credenciais, caso precise de alguma.

Crie uma ferramenta

1. Vá para Captain > Ferramentas e clique em Criar uma nova ferramenta. Primeiro, use o seletor de assistente no topo para escolher para qual assistente a ferramenta será criada. O formulário abre em um painel lateral.

   

2. Preencha:

   • Nome da Ferramenta: curto, por exemplo "Consulta de Pedido" (até 55 caracteres).

   • Descrição: quando o assistente deve usá-la, escrito como um briefing para um novo agente. Isso define se o assistente escolhe a ferramenta.

   • Método: GET para ler dados; POST, PUT ou PATCH para enviar ou alterar dados; DELETE para remover algo.

   • Endpoint URL: use {{ parameter_name }} para valores que o assistente irá preencher, por exemplo https://api.example.com/orders/``{{ order_id }}.

   • Tipo de Autenticação: Nenhum, Bearer Token, Basic Auth ou API Key (com Header Name e Header Value). Use para inserir credenciais.

   • Cabeçalhos: clique em Adicionar Cabeçalho para cabeçalhos fixos necessários em todas as requisições da sua API, como versão da API ou ID do locatário (até 16). Os valores são enviados exatamente como digitados. O Chatwoot define Authorization, Host, Content-Length, Content-Type e qualquer cabeçalho que comece com X-Chatwoot, então você não pode adicionar esses.

   • Parâmetros: clique em Adicionar Parâmetro para cada valor que o assistente deve obter do cliente. Informe um nome, tipo, descrição e marque Obrigatório se necessário.

   • Modelo do Corpo da Requisição (Opcional): para POST, PUT ou PATCH. Esse e o modelo de resposta ficam em Modelos. O modelo da requisição é um corpo JSON. Suporta Liquid, por exemplo {{ order_id }} para um parâmetro.

   • Modelo de Resposta (Opcional): selecione os campos que o assistente precisa, por exemplo Pedido {{ response.order_id }} status: {{ response.status }}. Leia a resposta da API através de response, por exemplo {{ response.status }}. Deixe o modelo em branco para enviar o JSON bruto ao Captain.

     

   

3. Clique em Testar conexão, depois em Criar.

   

Testar conexão funciona apenas para endpoints sem modelos ou corpo de requisição. Para os demais, teste no Playground. Um resultado verde significa que seu endpoint retornou um status 2xx: está acessível e aceitou as credenciais.

Teste

Faça uma pergunta no Playground que precisa da ferramenta, por exemplo "Onde está o pedido 1234?". Verifique se a resposta utiliza dados reais.

Obtenha valor

• As ferramentas personalizadas funcionam melhor para consultas com entradas claras, como status de pedidos, reservas ou registros por ID.

• Cada assistente pode ter até 50 ferramentas. Mantenha a lista curta: com muitas ferramentas, o assistente tende a escolher a errada.

• Adicionar, editar, desativar ou excluir uma ferramenta afeta apenas o assistente que você está visualizando. Ferramentas existentes antes do modelo por assistente foram copiadas para todos, então revise cada uma.

• Gerenciando vários assistentes? Dê a cada um apenas as ferramentas necessárias.

• Desative uma ferramenta com seu botão ao invés de excluir. Se um cenário a usar, o Chatwoot avisa. Veja Defina os guardrails, diretrizes e cenários do Captain.

• O Chatwoot envia cabeçalhos com cada chamada para seu sistema saber a conta, conversa, e-mail e telefone de contato, assistente e se o contato é verificado. Para dados privados, cheque o cabeçalho X-Chatwoot-Contact-Inbox-Verified antes de responder. Sem validação de identidade, um visitante pode digitar qualquer e-mail no widget. Ferramentas que retornam apenas dados públicos não precisam dessa checagem. Veja Como ativar a validação de identidade no Chatwoot?.

• Se sua API retorna textos escritos por clientes, retorne apenas os campos estruturados necessários. O Captain lê a resposta como está, então textos livres podem conter instruções que podem ser seguidas.

Solucione problemas

Mais causas: Solucione problemas no Captain.