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 transferir o atendimento.

Plano & acesso: Business ou Enterprise (Pricing & Plans). No Startups, Ferramentas normalmente exibe Faça upgrade para usar ferramentas com o Captain. Cada assistente tem sua própria lista de ferramentas. Administradores criam ferramentas, e somente administradores podem ver as credenciais salvas. Na versão self-hosted: o Super Admin ativa Ferramentas Personalizadas para a conta.

Configure & 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 1 MB ou menos.

• Suas credenciais, se for necessário.

Crie uma ferramenta

1. Vá em Captain > Ferramentas e clique em Criar nova ferramenta. Primeiro use o seletor de assistente no topo para escolher para qual assistente a ferramenta é. O formulário será aberto 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, escrita como um briefing para um novo agente. Isso decide se o assistente escolhe ou não a ferramenta.

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

   • URL do Endpoint: 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 isso para credenciais.

   • Cabeçalhos: clique em Adicionar Header para cabeçalhos fixos que sua API exige em todas as chamadas, como uma versão da API ou ID do tenant (até 16). Os valores são enviados exatamente como digitados. O Chatwoot define Authorization, Host, Content-Length, Content-Type e qualquer cabeçalho começando com X-Chatwoot automaticamente, então você não pode adicionar estes.

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

   • Template do Corpo da Solicitação (Opcional): para POST, PUT ou PATCH. Este e o template de resposta ficam em Templates. O template de solicitação é um corpo JSON. Suporta Liquid, por exemplo {{ order_id }} para um parâmetro.

   • Template da Resposta (Opcional): destaque os campos que o assistente precisa, por exemplo Pedido {{ response.order_id }} status: {{ response.status }}. Leia a resposta da API via response, por exemplo {{ response.status }}. Deixe o template em branco para enviar ao Captain o JSON bruto.

     

   

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

   

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

Teste

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

Ganhe valor

• Ferramentas personalizadas funcionam melhor para consultas com entradas claras, como status de pedido, uma reserva ou um registro por ID.

• Cada assistente pode ter até 50 ferramentas. Mesmo assim, mantenha a lista curta: com muitas ferramentas, o assistente tem mais chance de escolher a errada.

• Adicionar, editar, desativar ou excluir uma ferramenta altera apenas para o assistente que você está visualizando. Ferramentas que já existiam antes de serem individualizadas foram copiadas para todos os assistentes, então confira cada um.

• Rodando vários assistentes? Dê a cada só as ferramentas que precisa.

• Desative uma ferramenta pela chave seletora em vez de excluir. Se um cenário a usar, o Chatwoot avisa primeiro. Veja Defina as regras de proteção, diretrizes e cenários do Captain.

• O Chatwoot envia cabeçalhos em cada chamada para seu sistema saber a conta, conversa, e-mail do contato e telefone, assistente, e se o contato está verificado. Para dados privados, confira 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 só dados públicos não precisam dessa verificação. Veja Como habilitar validação de identidade no Chatwoot?.

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

Solução de problemas

Mais causas: Solucione problemas do Captain.