Configure ferramentas personalizadas para o Captain.

Descobrir

As ferramentas personalizadas permitem que o assistente acesse seus próprios sistemas durante uma conversa — por exemplo, para consultar um pedido, uma garantia ou uma reserva — em vez de transferir o atendimento.

Plano e acesso: Business ou Enterprise (Preços e planos). No plano Startups, Ferramentas geralmente mostra Faça upgrade para usar ferramentas com o Captain. Cada assistente tem sua própria lista de ferramentas. Os administradores criam as ferramentas, e somente eles podem ver as credenciais salvas. Na versão auto-hospedada, o Super Admin ativa Ferramentas personalizadas para a conta.

Configurar e testar

Antes de começar

• Um endpoint HTTPS em um nome de host 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.

• As credenciais, caso sejam necessárias.

Criar uma ferramenta

1. Acesse Captain > Ferramentas e clique em Criar uma nova ferramenta. Primeiro, use o seletor de assistente na parte superior para escolher para qual assistente a ferramenta será criada. O formulário é aberto em um painel lateral.

   

2. Preencha:

   • Nome da ferramenta: um nome curto, por exemplo, "Consulta de pedido" (55 caracteres ou menos).

   • Descrição: quando o assistente deve usar a ferramenta, escrita como instruções para um novo agente. Isso determina se o assistente selecionará 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 preencherá, por exemplo, https://api.example.com/orders/``{{ order_id }}.

   • Tipo de autenticação: Nenhuma, Bearer Token, Autenticação básica ou Chave de API (com Nome do cabeçalho e Valor do cabeçalho). Use essa opção para as credenciais.

   • Cabeçalhos: clique em Adicionar cabeçalho para incluir cabeçalhos fixos exigidos pela sua API em cada chamada, como uma versão da API ou um ID de locatário (até 16). Os valores são enviados exatamente como digitados. O Chatwoot define os cabeçalhos Authorization, Host, Content-Length, Content-Type e qualquer cabeçalho iniciado por X-Chatwoot, portanto você não pode adicioná-los.

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

   • Adicionar e-mail verificado: adiciona um parâmetro. O Chatwoot insere nesse parâmetro o e-mail que o cliente verificou com um código de uso único. Nas conversas com clientes, o Captain não pode vê-lo nem alterá-lo. Use esse parâmetro quando sua API localizar o cliente pelo e-mail, por exemplo, https://api.example.com/orders?email={{ email }}. Uma ferramenta pode ter um único parâmetro de e-mail verificado.

   • Exigir verificação de e-mail: o Captain só pode usar a ferramenta depois que o cliente verificar o e-mail com um código de uso único. Se a ferramenta tiver um parâmetro de e-mail verificado, essa configuração estará sempre ativada.

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

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

     

   

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

   

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

Testar

Faça no Playground uma pergunta que exija a ferramenta, por exemplo, "Onde está o pedido 1234?". Confira se a resposta usa dados reais.

Proteger os dados dos clientes

Um cliente pode digitar qualquer e-mail no widget ou no formulário pré-chat. Algumas ferramentas retornam ou alteram os dados de um cliente, como pedidos, faturas ou reservas. Ative a verificação de e-mail para essas ferramentas.

Quando o Captain chama uma dessas ferramentas, ele solicita o e-mail do cliente. O Chatwoot envia um código de 6 dígitos para esse e-mail, e o cliente o digita na conversa. A ferramenta só é executada depois que o Chatwoot confirma que o código está correto.

• A verificação se aplica a uma única conversa. Ela dura até 1 hora ou até 3 horas em conversas por e-mail. Uma nova conversa começa sem verificação.

• Um código expira após 30 minutos. O cliente pode tentar um código 5 vezes. O Chatwoot envia no máximo 5 códigos a um cliente em uma hora.

• Exigir verificação de e-mail não controla para qual e-mail a ferramenta envia uma solicitação. Se sua API obtiver o e-mail de um parâmetro normal, o Captain poderá enviar qualquer e-mail. Para que a ferramenta envie apenas o e-mail verificado, use Adicionar e-mail verificado.

• O Chatwoot pode identificar indícios de que uma ferramenta usa dados de clientes. Se encontrar esses indícios e a ferramenta não tiver verificação de e-mail, o Chatwoot exibirá Salvar sem verificação de e-mail? antes de salvar. Clique em Voltar ou Salvar mesmo assim.

• No Playground e nas sugestões de resposta, o usuário é um membro da equipe. O Captain preenche o parâmetro de e-mail verificado. O resultado informa se o Chatwoot verificou esse e-mail.

• Em conjuntos de ferramentas instalados, os administradores podem ativar ou desativar Exigir verificação de e-mail.

Aproveitar ao máximo

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

• Cada assistente pode ter até 50 ferramentas. Ainda assim, mantenha a lista curta: com muitas ferramentas, é mais provável que o assistente escolha a ferramenta errada.

• Adicionar, editar, desativar ou excluir uma ferramenta altera apenas a configuração do assistente que você está visualizando. As ferramentas existentes antes de se tornarem específicas de cada assistente foram copiadas para todos eles, então confira cada assistente.

• Se você usa vários assistentes, dê a cada um apenas as ferramentas de que precisa.

• Desative uma ferramenta pelo botão de alternância, em vez de excluí-la. Se um cenário a usar, o Chatwoot avisará você primeiro. Consulte Definir as proteções, diretrizes e cenários do Captain.

• O Chatwoot envia cabeçalhos em cada solicitação. Eles informam ao seu sistema a conta, a conversa, o contato, o assistente e a caixa de entrada.

  • X-Chatwoot-Verified-Email contém o e-mail que o cliente verificou com um código de uso único. Se o cliente não tiver feito a verificação, o Chatwoot não envia esse cabeçalho.

  • X-Chatwoot-Contact-Email contém o e-mail registrado no contato. Qualquer pessoa pode digitar esse e-mail. Não o use para retornar dados privados.

  • X-Chatwoot-Contact-Inbox-Verified é true quando a validação de identidade (HMAC) verificou o contato. Esse cabeçalho não verifica o e-mail.

  Se seu sistema retorna dados privados, verifique X-Chatwoot-Verified-Email ou ative a verificação de e-mail para a ferramenta. Consulte Como ativar a validação de identidade no Chatwoot?.

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

Solução de problemas

Mais causas: Solucionar problemas do Captain.