Integrações de API personalizadas

Integrar o seu chatbot com APIs personalizadas

Ao utilizar o nosso editor de ações de IA, pode criar qualquer integração personalizada com qualquer sistema de backend que consiga expor dados através de endpoints de API. Por exemplo, pode fazer com que o chatbot verifique a disponibilidade de um produto no seu armazém, consulte o estado da encomenda no seu sistema ERP ou verifique o saldo atual da conta do cliente.

Também pode executar ações para atualizar sistemas externos - por exemplo, chamar endpoints para agendar reuniões ou acionar webhooks.

Pré-requisitos

ℹ️ Antes de começar - certifique-se de que tem uma subscrição do ChatLab que permita integrações com Custom API. Consulte a página de preços

Adicionar uma Custom API ao seu chatbot

A integração de uma API personalizada permite que o seu chatbot comunique com serviços externos - por exemplo, a sua loja personalizada, obtendo dados ou realizando ações em nome do utilizador.

Este guia irá orientá-lo ao longo dos passos necessários para configurar uma API personalizada utilizando a plataforma ChatLab.

A sua API

Precisa de ter endpoints de API acessíveis publicamente que possam ser chamados pelo chatbot - isto significa que deve expor os dados da sua plataforma de e-commerce ou do seu sistema personalizado através de endpoints de API, para que o nosso chatbot possa chamar estes endpoints de forma a extrair esses dados e fornecê-los aos seus utilizadores.

Invocação da API pelo chatbot

A API será chamada dinamicamente pelo chatbot durante as interações com os utilizadores, com base na necessidade de aceder a dados externos ou executar ações específicas. É importante ter em conta o seguinte:

• Sem garantia de invocação: A API só será invocada quando a lógica do chatbot determinar que tal é necessário. Não existem garantias sobre quando ou com que frequência a API será chamada.

• Requisitos do modelo de IA: Para um desempenho ideal, recomenda-se a utilização de modelos de IA de nível superior que suportem chamadas de funções complexas, como o GPT-4o ou superior. Estes modelos são mais aptos a determinar os momentos adequados para invocar a API com base no contexto da conversa e na intenção do utilizador.

• Chamadas sensíveis ao contexto: O chatbot tentará chamar a API sempre que identificar um contexto na conversa que coincida com o objetivo da API, mas a chamada real dependerá de múltiplos fatores, tais como:

  • Disponibilidade e velocidade de resposta da API externa.
  • O estado atual da conversa e os pedidos do utilizador.
  • Níveis internos de confiança e algoritmos de pontuação do modelo de IA ao decidir a necessidade da chamada.

Passos para configurar uma Custom API

Passo 1: Navegar até às definições de Custom API

1. Inicie sessão no painel do ChatLab.

2. Na barra lateral esquerda, na secção Settings (Definições), clique em Custom API (API personalizada).

Passo 2: Definir uma nova API

1. Clique no botão + Define API (+ Definir API).

2. Introduza um nome para a sua API no campo API Name (Nome da API).

3. Indique o URL base do serviço externo a que se pretende ligar no campo URL.

4. Clique em Save (Guardar) para criar a API.

Passo 3: Adicionar operações à API

1. Na entrada da API recém-criada, clique no botão View (Ver).

2. Clique em + Define API Operation (+ Definir operação de API) para configurar operações individuais (endpoints) para a API.

3. Preencha os detalhes necessários:

• Operation Name: Um nome descritivo para a operação.
• Operation URI: O caminho do endpoint para a operação (ex.: /v1/resource).

Passo 4: Configurar o URI do endpoint e os parâmetros

1. Configuração do URI do endpoint:

• Adicione as variáveis de caminho necessárias para a operação clicando em + Add path variable (+ Adicionar variável de caminho).
• Introduza os detalhes da variável e marque-os como obrigatórios, se necessário.

• Escolha a origem do valor:
  • Fornecido pelo utilizador ao chatbot - caso seja necessário algum valor do utilizador para preencher este campo.
  • Constante - caso se trate de um valor constante que terá de fornecer no momento da definição da operação de API
• Adicione a variável de caminho recém-adicionada à definição do caminho entre dois símbolos “@”: @myvariable@:

1. Parâmetros de consulta (Query Parameters):

• Adicione parâmetros de consulta clicando em + Add query parameter (+ Adicionar parâmetro de consulta).
• Defina o nome do parâmetro, o tipo de dados e a origem (ex.: fornecido pelo utilizador ou pelo chatbot).

Passo 5: Definir o método de pedido e o corpo

1. Escolha o método HTTP para a operação (ex.: GET, POST).

2. Se o método de pedido for POST, configure o corpo do pedido (request body):

• Escolha o tipo de conteúdo (ex.: application/json).
• Adicione os parâmetros do corpo, especificando o nome, o tipo de dados e a origem.

• Adicione as variáveis à definição do corpo - normalmente trata-se de um JSON onde pode colocar as variáveis que definiu

Passo 6: Definir os cabeçalhos da operação

Adicione cabeçalhos - ou seja, Authorization ou outros necessários para a sua API. Consulte a captura de ecrã abaixo para configurar um token permanente no cabeçalho Authorization:

Passo 7: Guardar a operação

1. Reveja a configuração para garantir que todos os detalhes estão corretos.

2. Clique em Save changes (Guardar alterações) para guardar a operação de API.

Passo 8: Testar a integração da API

1. Utilize a funcionalidade Test API (Testar API) para enviar um pedido de teste e verificar se a integração está a funcionar corretamente.

2. Monitorize os registos para detetar eventuais erros ou problemas e ajuste a configuração conforme necessário.

Passo 9: Associar as operações de API ao chatbot

Assim que as operações de API estiverem definidas, é altura de as associar ao chatbot. Selecione o chatbot no painel principal de chatbots, clique em Integrations (Integrações) e selecione AI API Actions (Ações de API de IA) no menu esquerdo

Clique em Attach (Associar) na operação de API selecionada

Passo 10: Adicionar instruções de função para o chatbot

Selecione o seu chatbot no painel principal de chatbots, clique em Settings e, no menu esquerdo, selecione Role (Função)

Clique em Provide custom role instructions (Fornecer instruções de função personalizadas).

Adicione instruções sobre como utilizar a operação de API recém-adicionada. Por exemplo, pode adicionar uma regra como:

“- Sempre que o utilizador perguntar pelo inventário da loja, chama sempre a função getItems e apresenta o resultado da função de acordo com as seguintes regras…..”

Dicas para uma integração bem-sucedida

• Certifique-se de que o URL base e os endpoints estão corretos e acessíveis.

• Verifique se todos os requisitos de autenticação (como chaves de API ou tokens) estão devidamente configurados.

• Teste cada operação exaustivamente para garantir que devolve as respostas esperadas.

Ao seguir estes passos, pode integrar perfeitamente APIs personalizadas no seu chatbot do ChatLab, melhorando a sua funcionalidade e proporcionando uma experiência de utilizador mais rica.

Proteger a sua integração de Custom API

Para garantir que a sua API personalizada está segura e protegida contra acessos não autorizados, considere as seguintes boas práticas:

Utilizar tokens constantes

Tokens de API constantes: Configure um token (ou chave) de API constante que seja obrigatório em todos os pedidos à API. Este token deve ser exclusivo e gerado de forma segura.

• Como implementar: Inclua o token no cabeçalho do pedido ou como parâmetro de consulta em cada chamada de API.

• Onde armazenar: Guarde o token com segurança nas definições do ChatLab como parâmetro constante da operação

Utilizar um endpoint de início de sessão para tokens temporários

Adicione uma operação de API adicional que devolva um token de segurança temporário - ou seja, um endpoint de início de sessão no seu sistema.

Terá de fornecer as suas credenciais de início de sessão correspondentes ao seu sistema como parâmetros constantes da operação ao definir esta operação de API. Para que o chatbot possa utilizar o token obtido desta forma, é necessário adicionar o token de segurança nas definições de outras operações de API e incluir as instruções de prompt adequadas tanto na operação de início de sessão como nas outras operações de API (Por exemplo: “Utiliza sempre o token de segurança obtido na operação de Login como o parâmetro security_token para a operação getOrder”).

Controlar informações sensíveis através do ChatLab

Para evitar que informações sensíveis sejam apresentadas pelo chatbot, os utilizadores do ChatLab podem adotar as seguintes medidas:

Utilizar a engenharia de prompts para orientar o comportamento da IA

• Definir instruções claras nos prompts: Ao configurar o chatbot, forneça instruções explícitas nas definições do prompt para evitar a apresentação de quaisquer dados confidenciais. Por exemplo:

  • Exemplo de prompt: "Não apresentes quaisquer informações pessoais, financeiras ou confidenciais devolvidas por uma chamada de API."
  • Utilização de mensagens de sistema: Inclua uma mensagem de sistema no início do fluxo de conversa para reforçar a importância da privacidade dos dados (ex.: "Certifica-te de que todas as respostas excluem qualquer informação sensível.").

• Atualizar os prompts regularmente: Ajuste os prompts com base no feedback dos utilizadores ou em alterações aos requisitos de sensibilidade dos dados. Isto ajuda a garantir que a IA cumpre consistentemente as diretrizes mais recentes sobre o tratamento de informações confidenciais.

Conceber endpoints de API com lógica de verificação integrada

• Exigir verificação do utilizador para acesso a dados sensíveis: Projete os seus endpoints de API de modo a incluir verificações de validação antes de devolverem informações sensíveis. Por exemplo:

  • Parâmetros de verificação: Exija que os utilizadores forneçam determinadas informações (como um endereço de e-mail, número de encomenda ou uma pergunta de segurança específica) antes de a API devolver dados relacionados com esse utilizador.
  • Verificação multifator: Implemente parâmetros adicionais (ex.: data da encomenda, morada de envio ou um código secreto) para verificar a identidade do utilizador e garantir que tem autorização para aceder aos dados.

• Implementar respostas de segurança (fail-safe): Configure a lógica da sua API para devolver mensagens genéricas ou erros caso a verificação necessária não seja fornecida ou não coincida:

  • Exemplo: "Não foi possível obter os detalhes da encomenda. Por favor, confirme o seu e-mail e o número da encomenda."

Utilizar âmbitos de dados limitados nas respostas da API

• Minimizar a exposição de dados: Configure as respostas da API para incluírem apenas os dados estritamente necessários para a função do chatbot, reduzindo o risco de apresentar inadvertidamente informações confidenciais.
  • Exemplo: Em vez de devolver perfis de utilizador completos, devolva apenas campos específicos, como o estado da encomenda ou a confirmação de pagamento, que sejam necessários para a tarefa do chatbot.