As integrações Custom API permitem que o seu chatbot solicite informações em tempo real a partir do seu ERP, armazém, CRM ou outro serviço. Também podem aplicar alterações, como a criação de uma marcação. Uma integração guarda o URL base; cada operação define um pedido executável. De seguida, associa as operações selecionadas a um chatbot como AI actions (ações de IA).
Antes de começar
Verifique se a sua conta inclui integrações Custom API. Precisa do URL do endpoint, do método HTTP, dos nomes e tipos de parâmetros, dos requisitos de autenticação e de uma resposta de exemplo. O endpoint tem de estar acessível a partir dos servidores do ChatLab; localhost no seu computador não é um endpoint de produção.
Utilize HTTPS e um serviço de teste ou registos de teste para a configuração. Um pedido de teste chama realmente o endpoint, pelo que um POST, PATCH ou DELETE pode alterar dados externos. Torne as operações seguras para repetição sempre que possível.
1. Criar uma integração
- Abra Custom Integrations (Integrações personalizadas) na navegação principal.
- Clique em + Define API Integration (+ Definir integração de API).
- Introduza API name (Nome da API) e API Base URL (URL base da API), por exemplo
https://api.example.com. - Clique em Create API Integration (Criar integração de API).
- Na entrada correspondente na lista, clique em View (Ver) e, em seguida, em + Define API Operation (+ Definir operação de API).
2. Definir a operação
Atribua à operação uma etiqueta de fácil identificação e um Operation name (Nome da operação) legível por máquina, como getProductDetails. Utilize apenas letras e números no nome da operação, sem espaços nem traços inferiores. Descreva o que a operação faz e quando o chatbot deve utilizá-la.
Introduza o URI relativo, por exemplo /v1/products/@productId@. O URL base e o URI formam o endereço do pedido.
Algumas capturas de ecrã existentes mostram nomes de exemplo mais antigos ou marcadores com chavetas. Siga a sintaxe atual apresentada abaixo: nomes de operação como getProductDetails e marcadores de posição de parâmetros delimitados por @.
Parâmetros de caminho e de consulta
Clique em Add path variable (Adicionar variável de caminho) para definir productId. Defina o respetivo tipo de dados e fonte de valor, e depois inclua @productId@ no URI. As variáveis de caminho são obrigatórias, e cada variável de caminho definida tem de constar no URI antes de poder guardar ou testar.
Utilize Add query parameter (Adicionar parâmetro de consulta) para parâmetros como limit ou language, que se situam a seguir ao ponto de interrogação do URL. Introduza o nome esperado pela sua API, o respetivo tipo, descrição e fonte de valor.
As fontes de valor disponíveis incluem:
- Provided by user or chatbot (Fornecido pelo utilizador ou chatbot): o modelo fornece um valor a partir da conversa. Explique o formato esperado e marque os valores obrigatórios de forma adequada.
- Constant (Constante): um valor configurado na operação, como um identificador de conta fixo ou uma credencial de API restrita.
- Random value (Valor aleatório): um valor gerado automaticamente.
- Client context (Contexto do cliente): um valor transmitido pelo website anfitrião, quando disponível para a sua conta. Consulte Chat API.
Os tipos escalares incluem string, integer, double e boolean. Os parâmetros do corpo também suportam arrays de string e de integer.
3. Configurar o método e o corpo
Selecione GET, POST, PUT, PATCH ou DELETE para corresponder ao seu endpoint. Para métodos diferentes de GET, o editor disponibiliza conteúdo de pedido em formato raw ou form-data.
Para um corpo JSON em raw, defina os parâmetros do corpo e insira os respetivos marcadores @name@ no modelo. Adicione o cabeçalho Content-Type adequado exigido pelo seu endpoint. Por exemplo, com parâmetros do tipo string name e de array de strings tags:
{
"name": "@name@",
"tags": @tags@
}
Isto é um modelo, não sendo JSON literal até que a substituição ocorra. Os marcadores de array não devem ser colocados entre aspas. Todos os parâmetros de corpo definidos têm de ser utilizados no modelo quando o editor de corpo raw for aplicado. Verifique o pedido gerado durante o teste, incluindo textos que contenham aspas ou carateres especiais.
4. Adicionar cabeçalhos de autenticação
Utilize Add header (Adicionar cabeçalho) para definir os cabeçalhos esperados pela API. Para um token bearer, utilize o nome de cabeçalho Authorization, a fonte de valor Constant e o valor Bearer O_SEU_TOKEN_RESTRITO.
Mantenha as informações confidenciais fora dos prompts e dos URLs. Evite operações que devolvam tokens de início de sessão ao modelo dependendo de instruções para os ocultar. Dê preferência a um endpoint de integração do lado do servidor que faça a gestão da sua própria autenticação e disponibilize apenas a operação autorizada.
5. Guardar e testar o pedido
- Clique em Save changes (Guardar alterações) no editor de operações. Ao contrário das Settings (Definições) normais do chatbot, este editor dispõe de um botão de gravação explícito.
- Clique em Test API Operation (Testar operação de API). Este botão fica desativado enquanto existirem alterações por guardar.
- Introduza valores representativos para os parâmetros. Para entradas de teste com arrays, utilize valores separados por vírgulas.
- Execute o teste apenas com dados que tem autorização para consultar ou alterar.
- Inspecione o código de estado, o corpo da resposta, o URL do pedido, os cabeçalhos, o corpo e quaisquer avisos apresentados nos resultados.
- Corrija os erros, guarde e repita conforme necessário.
Não partilhe os dados de saída do teste que contenham credenciais. Devolva dados orientados e paginados sempre que possível: respostas grandes podem ser truncadas antes de chegarem ao modelo.
6. Associar a operação a um chatbot
Abra o seu chatbot e aceda a Settings > Actions (Definições > Ações). Utilize o botão de adição para adicionar uma ação, localize a sua operação em APIs personalizadas e associe-a ou ative-a. A simples criação de uma integração ao nível da conta não torna todas as operações disponíveis para todos os chatbots.
Reveja as instruções da ação e as definições de segurança disponíveis; de seguida, aguarde pela confirmação de estado guardado. Consulte AI actions para informações sobre o editor de ações.
7. Explicar quando deve ser utilizada
Abra Settings > Role & Behavior (Definições > Função e comportamento).
Se utilizar instruções personalizadas de função, selecione Custom Role Definition (Definição de função personalizada) e adicione uma regra precisa, por exemplo: "Quando o visitante perguntar se um produto está em stock, chama getProductDetails com o respetivo ID de produto. Informa a disponibilidade devolvida. Se a pesquisa falhar, explica que não foi possível verificar a disponibilidade."
Mantenha as restantes instruções úteis do chatbot. Aguarde pelo estado de guardado e utilize a pré-visualização em Overview (Visão geral) para testar perguntas realistas, parâmetros em falta, erros e pedidos não autorizados. As conversas de pré-visualização podem acionar operações reais.
O acionamento por IA não é garantido nem é necessariamente efetuado uma única vez. Teste com o modelo selecionado para o seu chatbot; não assuma que apenas o nome de um modelo garante a utilização correta de ferramentas.
Segurança e resolução de problemas
O seu endpoint tem de autenticar os pedidos e autorizar o acesso de cada utilizador antes de devolver informações confidenciais ou executar uma alteração. Um ID de cliente, e-mail, número de encomenda ou campo de contexto fornecido pelo navegador não constitui prova de identidade suficiente. Se transmitir um token por utilizador através do contexto do cliente, o seu servidor tem de validá-lo.
Devolva apenas os campos de que o chatbot necessita, como o estado da encomenda em vez de um perfil de cliente completo. As instruções do prompt podem orientar a forma de redação, mas não podem garantir que os dados confidenciais devolvidos ao modelo fiquem ocultos.
Se o pedido for bem-sucedido no editor de testes, mas não numa conversa, verifique a ação associada, se está ativa, as instruções, os parâmetros obrigatórios e o contexto disponível. Se ambos falharem, inspecione o URL, o método HTTP, a autenticação, o corpo processado e os registos do seu endpoint. Evite tentar novamente uma operação de escrita de forma repetida até ter a certeza se o pedido anterior foi bem-sucedido.