Desenvolvimento de código na plataforma
Aqui vamos aprender como desenvolver códigos dentro da plataforma Botmaker.
Aba de código na plataforma
As ações de cliente são uteis para o desenvolvimento de intenções mais complexas ou então quando for desejado adicionar códigos arbitrários em uma conversa. É uma excelente alternativa para conectar serviços externos para adquirir informações relevantes em tempo real na conversa com o usuário.
Por exemplo:
Você pode solicitar ao usuário que ele diga uma cor. Após enviada, você pode conectar a Google Translating API para fazer o bot responder a mesma cor em outra língua.

Como disparar um código

Primeiramente, você terá de criar uma Ação de Cliente na tela de Códigos. Veja abaixo:
Criar
Dê um nome à ação (não se esqueça dele), e clique em Salvar.
Na intenção em que a ação deverá ser disparada, clique em "+Ação", escolha "Client Action" e selecione o código a ser executado:
Salvar

Features de código

Suportamos Node.js v6.14.0, juntamente à lista de libraries abaixo:
{
"@turf/helpers": "^6.1.4", // accessed by "turfHelpers" var
"@turf/turf": "^5.1.6", // accessed by "turf" var
"bluebird": "^3.5.1", // accessed by "bluebird" var
"googleapis": "^32.0.0", // accessed by "google" var
"js-sha256": "^0.9.0", // accessed by "sha256" var
"jsonwebtoken": "^8.3.0", // accessed by "jwt" var
"lodash": "^4.17.10", // accessed by "_" var
"md5": "^2.2.1", // accessed by "md5" var
"moment": "^2.22.2", // accessed by "moment" var
"redis": "^2.8.0",
"request": "^2.87.0",
"request-promise": "^4.2.2", // accessed by "rp" var
"secure-random": "^1.1.1", // accessed by "securedRandom" var
"xml2js": "^0.4.19", // accessed by "xml2js" var
"aws-sdk": "^2.485.0" // accessed by "awsSdk" var
}
No caso de você desejar usar outra library, escreva-nos um email para [email protected], e nosso time irá acatar a solicitação!

Input da Ação de Cliente

Quando o código for disparado, toda informação que tivermos do usuário, conversas e configurações gerais serão fornecidas. O json abaixo descreve o input que uma Cloud Function poderá 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": "Usuario",
"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 context

Um objeto somente-leitura que tem informações relevantes que uma ação de código possa requer. Ela fornece:
  • userData: toda informação referente a um usuário, incluíndo tags e variáveis - se houver;
  • message: informação referente à última mensagem do usuário;
  • params: params opcionais que podem ser enviados por uma regra.
Por exemplo:
const userFirstName = context.userData.FIRST_NAME;

O objeto user

Esse objeto permite ler e escrever variáveis que persistirão ao usuário. É um local muito útil para guardar dados relacionados ao usuário.
Tenha em mente que os valores terão de ser do tipo de string
  • Para ler um valor: user.get('valueKey') => retornará uma string com valor ou nula
  • Para escrever um valor: user.set('valueKey', 'value')
Por exemplo:
if ( !user.get('neverWasHere') )
user.set('neverWasHere', 'true');
o valor neverWasHere será true para sempre, ou até quando outra ação de cliente configurar um valor diferente
Na seção de configuração de variáveis é possível alterar o tipo de variável e se será visível aos operadores.
Também é possível que a variável expire juntamente com a seção, ou seja, depois de uma hora de inatividade.

Usar entidades entityLoader

Quando for feito upload de um arquivo cvs no menu "Registros" da plataforma, as Ações de Cliente terão acesso a ele. Uma lista guardada poderá ser filtrada.
/*Entidad cargada:
id | name
1 | Gabriel
2 | Dario
*/
//Utilizar la función entityLoader para leer las entidades cargadas
entityLoader('entity name', json => {
// here you got your entity object loaded as json
if (!json) {
user.set('error', 'No hay datos');
result.done();
return;
}
//Buscamos el dato que necesitamos
const data = json.find(row => row.id === 2);
result.text('Muestro el nombre ->' + data.name);
});

O objeto conncetRedis

Uma instância db instance está disponível para ser utilizada com Ações de Clientes. Você pode:
const redis = connectRedis();
const myKey = redis.get('key');
Suporte completo à redis é fornecido. Dê uma olhada no node oficial: redis library.

Resultado de uma Ação de Cliente

Qualquer resultado adicional que uma Ação de Cliente queira criar, precisa ser feito usando o objeto result.
  • Para dizer algo ao usuário usando texto: result.text('a message')
  • Para mostrar uma imagem ao usuário: result.image('https://example.com/image.jpg')
  • Para mostrar um vídeo ao usuário: result.video('https://example.com/video.mp4')
  • Para enviar um arquivo ao usuário: result.image('https://example.com/myfile.doc')
  • Para enviar um áudio ao usuário: result.audio('https://example.com/audio.mp3')
Também é possível enviar ao usuário um texto com botões de ação.
result.buttonsBuilder()
.text('select an option')
.addURLButton('click me', 'https://www.google.com') // a button that will open a page
.addLocationButton() // ask the user for its location using GPSs
.quickReplies() // marks the button so it's showed as pills
.addPhoneButton('call me', '+11233212312')
.addButton('click me', 'rule with name XX') // when user clicks it will fire the rule named XX
.send(); // send must by always called to finalize

Ir à outra regra

É possível executar uma regra, após finalizada a Ação de Cliente, de forma muito fácil. É útil pois, depois de dizer algo ao usuário, alterar algum dado ou modificar o estado dele, você desejará continuar o fluxo da conversa disparando alguma regra.
result.gotoRule('a rule name');

Término de Ação de Cliente

result.done() deverá ser executado quando a Ação de Cliente for finalizada.
É muito importante chamar result.done() em todo fluxo que exista uma Ação de Cliente, de modo a finalizar a execução do mesmo
O seguinte código mostra uma Ação de Cliente bem implementada, com o método done() chamado em todo o fluxo.
rp({uri: 'https://script.google.com/macros/s/AKfycbyd5AcbAnWi2Yn0xhFRbyzS4qMq1VucMVgVvhul5XqS9HkAyJY/exec?tz=Asia/Tokyo Japan', json: true})
.then(json=> {
// saying the time
result.text('The time in Tokyo is ' + json.fulldate);
// do not forget to end the execution
result.done();
})
.catch(error => {
result.text('Problems: ' + error + '|' + JSON.stringify(error));
result.done();
});

Usando listas personalizadas (JSON List)

Se quiser usar opções para uma Question que sejam configuradas dinamicamente e que mudem de acordo com o tempo, é possível adicionar um valor a uma variável especial dentro de uma Client Action.
No código Javascript, precisará ser criada uma lista de objetos, cada um contendo os campos "id" e "name". Você pode adicionar outras chaves a esses objetos, mas não é obrigatório. Veja o exemplo:
const COUNTRIES = ['Argentina', 'Bolivia', 'Brazil', 'Chile', 'México', 'Paraguay', 'Perú', 'Uruguay']; let myJSONList = [];
myJSONList = COUNTRIES.map((country, index) => { return { id: index, name: country }; });
//result.text(JSON.stringify(myJSONList)); user.set('countries', JSON.stringify(myJSONList));
result.done();
Para usar essa variável em uma intenção, será necessário declarar que os valores válidos para a Question são de uma Custom JSON List e referenciar a variável utilizada no código.
Finalmente, devemos ver algo como:

Criar uma Client Action com parâmetros

Pode ser criada usando a ação "Client Action with params":
Ou desde um código, usando um botão que chama outra Client Action:
result.buttonsBuilder()
.addClientActionButton('Nombre del boton', //Nombre que aparecerá en el boton
'Nombre de la Client Action', //Nombre de la client action
{
'key': 'valor',
'key2': 'otro_valor'
}) //Json Object con los parametros que se enviará
.buildButtons();
Para usar os parâmetros enviadas à Client Action:
//En la client action destino
const myVar = context.params.key
const myVar2 = context.params.key2