Primeiro, acesse a página principal do Botmaker.

Vá até o menu lateral esquerdo e procure a palavra "Código".

Clique ali e você será redirecionado para esta tela de Ações de código.

As ações do cliente são úteis para o desenvolvimento de intenções mais complexas ou quando se deseja adicionar códigos arbitrários em uma conversa. É uma excelente alternativa para conectar serviços externos e obter informações relevantes em tempo real na conversa com o usuário.

Por exemplo:

Você pode pedir que o usuário diga uma cor. Assim que ele enviar, é possível conectar a API de tradução do Google para que o bot responda com a mesma cor em outro idioma.

Como disparar um código

Primeiro, será necessário criar uma ação do cliente na tela Códigos. Clique em “Criar nova ação de código”.

Atribua um nome à ação (não se esqueça), a versão do NodeJS e o tipo de ação.

Você pode trabalhar sobre um modelo de código para apoiar a criação da ação.

Depois de finalizar a criação, clique no botão “Publicar” para que ela fique disponível para uso.

Características do código

Suportamos Node.js v22, juntamente com a lista de bibliotecas abaixo:

 {
    "@google-cloud/pubsub": "^5.0.0",
    "@google-cloud/vision": "^5.1.0",
    "@turf/helpers": "^6.1.4",
    "@turf/turf": "^6.5.0",
    "axios": "^1.9.0",
    "bluebird": "^3.5.1",
    "fast-csv": "^4.3.6",
    "googleapis": "^92.0.0",
    "js-sha256": "^0.9.0",
    "jsonwebtoken": "^9.0.2",
    "lodash": "^4.17.10",
    "md5": "^2.2.1",
    "moment": "^2.22.2",
    "moment-timezone": "^0.5.34",
    "node-fetch": "^2.6.6",
    "request": "^2.88.2",
    "request-promise": "^4.2.5",
    "secure-random": "^1.1.1",
    "sharp": "^0.34.1",
    "uuid": "^11.0.3",
    "xml2js": "^0.6.2",
    "xml2json": "^0.7.1"
  }

Caso queira usar outra biblioteca, envie um e-mail para architecture@botmaker.com, e nossa equipe analisará o pedido.

Entrada de ação do cliente

Quando o código for ativado, todas as informações que temos sobre o usuário, as conversas e as configurações gerais serão fornecidas. O JSON abaixo descreve a entrada que uma função de nuvem pode usar.

{
  "context": {
    "userData": {
      "CHAT_PLATFORM_ID": "webchat",
      "CHAT_CHANNEL_ID": "YPDXTZKM8Y3NXLXVQYAN-webchat-null",
      "PLATFORM_CONTACT_ID": "0BBSX05QRF-3318782UBYKNLUIRBM0KL8XMDTM",
      "LAST_MODIFICATION": "2018-07-23T03:43:51.243Z",
      "HAS_TALKED": true,
      "_id_": "O0IUBYCHJYSA4PNB0QH7",
      "LAST_SEEN": "2018-07-23T03:43:52.279Z",
      "variables": {
        "svar": "sdas"
      },
      "tags": [
        "testtest2"
      ]
    },
    "message": {
      "BUSINESS_ID": "YPDXTZKM8Y3NXLXVQYAN",
      "CREATION_TIME": "2018-07-23T03:43:52.281Z",
      "FROM_NAME": "Usuário",
      "CUSTOMER_ID": "O0IUBYCHJYSA4PNB0QH7",
      "_id_": "LBIJGWZN4SJADFT2HUD2",
      "FROM": "0BBSX05QRF-3318782UBYKNLUIRBM0KL8XMDTM",
      "OBJECT_TYPE": "Message",
      "SESSION_CREATION_TIME": "2018-07-23T03:43:52.281Z",
      "AUDIOS_URLS": [],
      "MESSAGE": "test",
      "CHAT_PLATFORM_ID": "webchat",
      "CHAT_CHANNEL_ID": "YPDXTZKM8Y3NXLXVQYAN-webchat-null",
      "LAST_MODIFICATION": "2018-07-23T03:43:52.281Z",
      "TO": "me",
      "TAGS": {}
    },
    "params": {}
  }
}

O objeto de contexto

Um objeto somente leitura que contém informações relevantes que podem ser necessárias em uma ação de código. Ele fornece:

• userData: todas as informações sobre um usuário, incluindo tags e variáveis, se existirem;
• message: informações sobre a última mensagem do usuário;
• params: parâmetros opcionais que podem ser enviados por uma regra.

Por exemplo:

const userFirstName = context.userData.FIRST_NAME;

O objeto user

Este objeto permite ler e escrever variáveis que persistem para o usuário. É um local muito útil para armazenar dados relacionados ao usuário.

Observe que os valores devem ser do tipo string.

• Para ler um valor: user.get('valueKey') → retorna uma string com o valor ou null
• Para escrever um valor: user.set('valueKey', 'value')

Exemplo:

if ( !user.get('neverWasHere') )
  user.set('neverWasHere', 'true');

O valor neverWasHere permanecerá verdadeiro para sempre, até que outra ação do cliente defina um valor diferente.

Na seção de configuração de variáveis, é possível alterar o tipo da variável e definir se ela será visível para os operadores.

Também é possível fazer com que a variável expire junto com a sessão, ou seja, após uma hora de inatividade.

Usar entidades entityLoader

Quando um arquivo CSV é carregado no menu “Registros” da plataforma, as ações do cliente terão acesso a ele. É possível filtrar uma lista salva.

/* Entidade carregada:
id | name
1 | Gabriel
2 | Dario
*/

// Utilizar a função entityLoader para ler as entidades carregadas
entityLoader('entity name', json => {

  if (!json) {
    user.set('error', 'Não há dados');
    result.done();
    return;
  }

  const data = json.find(row => row.id === 2);
  result.text('Mostrando o nome ->' + data.name);
});

O objeto DB

Adicionamos um novo componente nas CAs, chamado “db”. Ele não precisa ser importado, ao contrário do Redis, e é usado de forma semelhante às funcionalidades de “user” ou “result” dentro das CAs. Este novo componente permite o uso de vários métodos, detalhados a seguir.

GET

Propósito: recuperar um par de valores (pair) de um banco de dados próprio, utilizando uma key como argumento.

SET

Propósito: armazenar um par de valores em um banco de dados próprio, usando uma key e um valor (sempre tipo string).

EXISTS

Propósito: verificar se um registro existe no banco de dados. Retorna true se existir e false caso contrário.

DEL

Propósito: eliminar um registro do banco de dados, removendo tanto a chave quanto o par associado.

ZADD

Propósito: adicionar um registro a uma coleção ordenada por score. Aceita key, value, score e expiração (em segundos).

ZRANGEBYSCORE

Propósito: retornar uma coleção de registros cuja score esteja entre min e max.

ZREMRANGEBYSCORE

Propósito: remover registros cuja score esteja dentro de um intervalo entre min e max.

Uso do objeto db nas CA Endpoint ou Cron

Nas Client Actions do tipo “Endpoint” ou “Cron”, todos esses métodos podem ser usados simplesmente adicionando antes do db o prefixo request..
Se for importada outra Client Action como biblioteca que também usa o objeto db, também deve ser adicionado o request. — ou seja, não é possível usar o mesmo método da biblioteca utilizado em CAs que não sejam desse tipo.

Resultado de uma ação do cliente

Qualquer resultado adicional que uma ação do cliente queira criar deve ser feito usando o objeto result.

• result.text('uma mensagem') → envia texto
• result.image('https://example.com/image.jpg') → envia imagem
• result.video('https://example.com/video.mp4') → envia vídeo
• result.file('https://example.com/myfile.doc') → envia arquivo
• result.audio('https://example.com/audio.mp3') → envia áudio

Também é possível enviar texto com botões de ação:

result.buttonsBuilder()
  .text('selecione uma opção')
  .addURLButton('clique aqui', 'https://www.google.com')
  .addLocationButton()
  .quickReplies()
  .addPhoneButton('ligar', '+11233212312')
  .addButton('clique aqui', 'rule with name XX')
  .send();

Ir para outra regra

É possível executar uma regra após concluir a ação do cliente, o que é útil para continuar o fluxo da conversa.

result.gotoRule('nome da regra');

Finalização da ação do cliente

result.done() deve ser executado quando a ação do cliente for finalizada.

É muito importante chamar result.done() em todos os fluxos que tenham uma ação do cliente.

Exemplo:

rp({uri: 'https://script.google.com/macros/s/...', json: true})
  .then(json => {
    result.text('A hora em Tóquio é ' + json.fulldate);
    result.done();
  })
  .catch(error => {
    result.text('Problemas: ' + error + '|' + JSON.stringify(error));
    result.done();
  });

Uso de listas personalizadas (Lista JSON)

Se quiser usar opções de uma pergunta configurada dinamicamente, é possível adicionar uma lista de objetos JSON dentro de uma ação do cliente.

const COUNTRIES = ['Argentina', 'Bolívia', 'Brasil', 'Chile', 'México', 'Paraguai', 'Peru', 'Uruguai'];
let myJSONList = [];

myJSONList = COUNTRIES.map((country, index) => { 
  return { id: index, name: country }; 
});

user.set('countries', JSON.stringify(myJSONList));
result.done();

Para usar uma ação de código dentro de um bot, vá até o Botdesigner.
Na interseção de um fluxo, clique no botão “Mais”.

Selecione “Ação” dentro das opções de blocos.

Depois, clique em “Ações de Código” e escolha entre “Ações de código” ou “Ações de código com parâmetros”.

Você poderá escolher entre as ações de código publicadas.

Integrar com um serviço REST

Essas integrações são usadas, em geral, para obter ou enviar dados através de uma API.
Se necessário, os dados podem ser salvos em variáveis do bot.

Exemplo:

rp({uri: 'https://httpbin.org/anything', json: true})
  .then(response => {
    user.set('data', response.data);
    result.text('Chamada bem-sucedida!: ' + JSON.stringify(response));
    result.done();
  })
  .catch(err => {
    result.text('Problemas!: ' + err.message);
    result.done();
  });

Integrar com um serviço SOAP

Da mesma forma, é possível integrar com serviços SOAP:

const request = `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
   <tem:itemData>
      <tem:dataOne>My Data</tem:dataOne>
   </tem:itemData>
</soapenv:Body>
</soapenv:Envelope>`;

rp({
  uri: `https://www.custom-service.com/myService.asmx`,
  method: 'POST',
  headers: {
    'Content-type': 'text/xml',
    'SOAPAction': 'http://tempuri.org/MyAction',
    'Content-Length': Buffer.byteLength(request)
  },
  body: request
})
  .then(response => {
    xml2js.parseString(response, (err, parsedResponse) => {
      user.set('data', parsedResponse.responseResult);
      result.text('Chamada bem-sucedida!: ' + JSON.stringify(parsedResponse));
      result.done();
    });
  })
  .catch(err => {
    user.set('error', `Erro rp SOAP ${err}`);
    result.done();
  });

Criar uma ação do cliente com parâmetros

Pode ser criada usando “Ação do cliente com parâmetros” — por exemplo, a partir de um botão que chama outra Client Action:

result.buttonsBuilder()
  .addClientActionButton('Nome do botão', 'Nome da Client Action', { 
     'key': 'valor',
     'key2': 'outro_valor'
  })
  .buildButtons();

Para usar os parâmetros enviados à Client Action:

const myVar = context.params.key;
const myVar2 = context.params.key2;

Criar uma biblioteca de utilidades usando ações de código

Na biblioteca de utilidades, é possível criar funções reutilizáveis para evitar duplicação de código e agilizar o processo.

Depois, elas podem ser chamadas de qualquer outro código da seguinte forma — o nome deve ser exatamente o mesmo:

Executar uma consulta a uma API externa desde uma Client Action do Botmaker

Para executar uma consulta a uma API externa a partir de uma Client Action, veja o exemplo a seguir:

Lembre-se de visitar nossa Central de Ajuda para obter mais informações.