Configure sua integração de API

Um passo do Chatlayer API etapa está disponível nos 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 para redirecionar seus usuários para fluxos diferentes com base na sua própria lógica de negócio.

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

O passo de API envia uma requisição para o seu servidor backend.

Enviar uma requisição de API

Para configurar seu passo de API:

Solte um Ação bloco para o seu canvas.

Clique em API.
Configure seus parâmetros. Veja abaixo para mais detalhes.

Métodos HTTPS

O passo de API suporta 5 métodos HTTPS:

POST
GET
DELETE
PUT
PATCH

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

Sob a Query aba, adicione parâmetros de query e/ou um payload de corpo definindo combinações chave-valor. Cada chave pode ter 3 tipos possíveis de valor:

text: texto estático.
variável: uma sessão do usuário variável. O valor da variável será armazenado como valor para a chave. Notação de ponto e de array são suportadas, por exemplo: users[0].firstname
dialogstate: selecione um estado de diálogo no menu. O ID do estado de diálogo será armazenado como valor para a chave. Este ID pode ser usado para redirecionar o usuário para um determinado estado de diálogo com base na sua lógica de negócio ao retornar a resposta da API.

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

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

text: texto estático.
variável: uma sessão do usuário variável. O valor da variável será armazenado como valor para a chave. Notação de ponto e de array são suportadas, por exemplo: users[0].firstname
dialogstate: selecione um estado de diálogo no menu. O ID do estado de diálogo será armazenado como valor para a chave. Este ID pode ser usado para redirecionar o usuário para um determinado estado de diálogo com base na sua lógica de negócio ao retornar a resposta da API.

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

O amount a chave terá o valor da variável de sessão do usuário transfer_amount (ex: 500).
O destination a chave terá o valor da variável de sessão do usuário transfer_destination (ex: Elon Musk).
O accountType a chave terá o valor da variável de sessão do usuário card_type (ex: savings_account).
O transactionSuccess a chave terá o identificador do estado de diálogo para o estado de diálogo 'transação bem-sucedida'. Este identificador pode ser usado na resposta desta requisição de API para redirecionar o usuário para um novo estado de diálogo.
O transactionNoMoney a chave terá o identificador do estado de diálogo para o estado de diálogo 'transação malsucedida'. Este identificador pode ser usado na resposta desta requisição de API para redirecionar o usuário para um novo estado de diálogo.
O test a chave terá o valor '5'.

Isso resultará no seguinte payload do corpo:

{
    "amount": 500,
    "destination": "Elon Musk",
    "accountType": "savings_account",
    "transactionSuccess": "successful transaction",
    "transactionNoMoney": "unsuccessful transaction",
    "test": 5
}

Se seu bot é multilíngue l, se a resposta da API enviar mensagens de agente de volta ao usuário e o agente suportar múltiplos idiomas, não esqueça de enviar o idioma do usuário na requisição. O idioma do usuário está disponível no sessão do usuário variável locale. Seu serviço backend pode usar essa configuração de idioma para enviar a resposta no idiomaPreferido.

Escutar por uma resposta da API

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

Variáveis de retorno da API

O API o passo suporta 3 tipos de variáveis de retorno:

sessão: 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 nesta chave de namespace na sessão do usuário. Você pode acessar este objeto no Chatlayer.ai usando interpolação: {namespace.dataKey}.
- data: um objeto que será salvo nos dados de sessão do usuário na chave de namespace.
mensagens: um array de mensagens para enviar de volta ao canal de 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 no estrutura de mensagem de chat.
action: 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 de conversa.

As 3 opções acima são executadas na ordem mostrada acima: variáveis de sessão são definidas primeiro, então as mensagens são enviadas e então você irá pular 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: 'random message 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 (corrente ou poupança) para alguém. Nós 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 tipo de conta (corrente - conta poupança) 
  const account = account_synonyms[accountType];
 
  if( accounts[account].amount + accounts[accounthlimit — amount < ) {
    nextDialogstate = transactionNoMoney 
  } else { 
    // transferir 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 payload do corpo conforme definido no passo do Chatlayer API 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 à requisiçã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 na sessão dele sob o namespace account. Esses dados podem ser usados nesse próximo estado de diálogo.

Como solução alternativa você também poderia enviar essa mensagem de chat como resposta das requisições do plugin de API usando a chave messages.

AnteriorChamadas de API PróximoRecursos avançados de API

Atualizado há 1 ano

Isto foi útil?