Configure sua integração com API

Uma etapa do Chatlayer API etapa está disponível na Ação blocos para permitir que você crie mensagens do bot com base em informações específicas do usuário e outros dados externos, e redirecione seus usuários para fluxos diferentes com base na sua própria lógica de negócios.

Você pode usar esta solução em qualquer plataforma que suporte receber e responder a solicitações HTTP.

A etapa de API envia uma solicitação para o seu servidor backend.

Enviar uma solicitação de API

Para configurar sua etapa de API:

1. Adicione um Ação bloco para o seu canvas.

Adicione uma etapa de Ação de API.

1. Clique em API.

2. Configure seus parâmetros. Veja abaixo para mais detalhes.

Métodos HTTPS

A etapa de API suporta 5 métodos HTTPS:

• POST

• GET

• DELETE

• PUT

• PATCH

Você só pode definir um corpo da solicitação quando o método da solicitação for POST ou DELETE.

Consulta

A guia Query dentro da sua etapa de API.

Na Consulta guia, adicione parâmetros de consulta e/ou um payload de corpo definindo combinações de chave-valor. Cada chave pode ter 3 tipos de valor possíveis:

• text: texto estático.

• variável: uma sessão do usuário variável. O valor da variável será armazenado como valor da chave. A notação de ponto e de array são suportadas, por exemplo: users[0].firstname

• dialogstate: selecione um estado de diálogo no menu suspenso. O ID do estado de diálogo será armazenado como valor da chave. Esse ID pode ser usado para redirecionar o usuário para um determinado estado de diálogo com base na sua lógica de negócios ao retornar a resposta da API.

Autorização

A guia Autorização dentro da sua etapa de API.

A Autorização guia tem os seguintes componentes:

• Autenticação básica: exibirá os campos para preencher nome de usuário e senha.

Autorização de autenticação básica.

• Token Bearer: exibirá o campo Token para ser preenchido.

Autorização com token Bearer.

Cabeçalhos

A guia Cabeçalhos dentro da sua etapa de API.

A guia Cabeçalhos é onde você configura seus cabeçalhos.

Corpo

A guia Corpo dentro da etapa de API.

Corpo é onde você pode definir um corpo da solicitação em todos os métodos HTTPS.

Na Corpo guia, adicione parâmetros de consulta e/ou um payload de corpo definindo combinações de chave-valor. Cada chave pode ter 3 tipos de valor possíveis:

• text: texto estático.

• variável: uma sessão do usuário variável. O valor da variável será armazenado como valor da chave. A notação de ponto e de array são suportadas, por exemplo: users[0].firstname

• dialogstate: selecione um estado de diálogo no menu suspenso. O ID do estado de diálogo será armazenado como valor da chave. Esse ID pode ser usado para redirecionar o usuário para um determinado estado de diálogo com base na sua lógica de negócios ao retornar a resposta da API.

Neste exemplo, representando uma transferência de dinheiro, enviamos cinco chaves no payload do corpo de uma solicitação HTTPS POST para nosso endpoint de API https://chatlayer-integration-demo.glitch.me/transaction.

Exemplo de payload do corpo.

• A amount a chave terá o valor da variável de sessão do usuário transfer_amount (ex.: 500).

• A destination a chave terá o valor da variável de sessão do usuário transfer_destination (ex.: Elon Musk).

• A accountType a chave terá o valor da variável de sessão do usuário card_type (ex.: savings_account).

• A transactionSuccess a chave terá o identificador do estado de diálogo para o estado de diálogo de ‘transação bem-sucedida’. Esse identificador pode ser usado na resposta desta solicitação de API para redirecionar o usuário para um novo estado de diálogo.

• A transactionNoMoney a chave terá o identificador do estado de diálogo para o estado de diálogo de ‘transação malsucedida’. Esse identificador pode ser usado na resposta desta solicitação de API para redirecionar o usuário para um novo estado de diálogo.

• A teste a chave terá o valor de ‘5’.

Isso resultará no seguinte payload do corpo:

{
    "amount": 500,
    "destination": "Elon Musk",
    "accountType": "savings_account",
    "transactionSuccess": "transação bem-sucedida",
    "transactionNoMoney": "transação malsucedida",
    "test": 5
}

Configuração

A guia Configuração dentro de uma etapa de API.

Configuração é onde, se você tiver uma configuração de API em Configurações>API, você a verá aqui.

Se se seu bot for multilíngual, se a resposta da API enviar mensagens do agente de volta ao usuário e o agente suportar vários idiomas, não se esqueça de enviar o idioma do usuário na solicitação. O idioma do usuário está disponível em sessão do usuário variável locale. Seu serviço backend pode usar essa configuração de idioma para enviar de volta a resposta no idioma do usuário preferredLanguage.

Escutar uma resposta da API

Você não precisa configurar o plugin de API para escutar uma resposta. Isso é feito automaticamente e a API etapa escutará o que sua API retornar.

Variáveis de retorno da API

A API etapa suporta 3 tipos de variáveis de retorno:

• session: Um objeto de sessão para salvar dados na sessão do usuário. A sessão tem 2 campos obrigatórios:

  • namespace: um namespace de chave. O objeto de dados será armazenado nessa chave de namespace na sessão do usuário. Você pode acessar esse objeto no Chatlayer.ai usando interpolação: {namespace.dataKey}.

  • data: um objeto que será salvo nos dados da sessão do usuário na chave de namespace.

• messages: uma matriz de mensagens para enviar de volta para o canal da interface do usuário. A estrutura dos diferentes tipos de mensagem (como texto, botões, respostas rápidas, carrosséis, listas, mídia etc.) está disponível na estrutura da mensagem de chat.

• ação: um objeto definindo uma ação, como redirecionar o usuário para um próximo estado de diálogo na conversa.

  • nextDialogstate: um identificador de estado de diálogo para redirecionar o usuário para um próximo estado de diálogo no fluxo da conversa.

As 3 opções acima são executadas na ordem mostrada acima: as variáveis de sessão são definidas primeiro, depois as mensagens são enviadas e então você irá para o próximo estado de diálogo.

Exemplo

Você pode encontrar um exemplo JSON para esses 3 casos no trecho de código abaixo:

const result = {
  session: {
    namespace: 'myNamespace',
    data: { variable: 'test123' },
  },
  messages: [{ type: 'text', config: { textMessages: [{ text: 'mensagem aleatória 1' }] } }],
  action: {
    nextDialogstate: 'dialogstate-123-abc',
  },
};

Certifique-se de incluir o tipo de conteúdo correto no cabeçalho: content-type: application/json;

Exemplo

Este exemplo demonstra um endpoint de API para transferir uma quantia de dinheiro de um tipo de conta (regular ou poupança) para alguém. Redirecionaremos o usuário para um determinado estado de diálogo com base no resultado da transação.

app.post('/transaction', function (req, res) {
  let nextDialogstate; 
  const { amount, destination, accountType, transactionSuccess, transactionNoMoney = req.body; 

  // obter o tipo de conta (conta corrente - conta poupança) 
  const account = account_synonyms[accountType];
 
  if( accounts[account].amount + accounts[accounthlimit — amount < ) {
    nextDialogstate = transactionNoMoney 
  } else { 
    // transferir o valor 
    accounts[account].amount —= amount;
    nextDialogstate = transactionSuccess; 
  } 

  res.json({
    action: { 
      nextDialogstate,
    }, 
    session: {
      namespace: 'account', 
      data: {
        limit: accounts[account].limit, 
        amount: accounts[account].amount 
      }
    },
  })
});

Recebemos o objeto de payload do corpo conforme definido no Chatlayer API step. Se o usuário não tiver uma quantia suficiente de dinheiro em sua conta, definimos o próximo estado de diálogo como ‘transactionNoMoney’. Caso contrário, subtraímos o valor desejado e definimos o próximo estado de diálogo como ‘transactionSuccess'.

Como resposta à solicitação, enviamos o próximo estado de diálogo para redirecionar o usuário para esse estado e salvamos a quantia de dinheiro e o limite da conta nos dados de sessão dele sob o namespace account. Esses dados podem ser usados naquele próximo estado de diálogo.

Como solução alternativa, você também pode enviar essa mensagem de chat como resposta às solicitações do plugin de API usando a chave messages.