Como desenvolver código na plataforma ?
Aqui você aprenderá como criar código dentro da plataforma Botmaker.
Aqui você aprenderá como criar código dentro da plataforma Botmaker.
Leitura estimada: 10 minutos
Primeiro acesse a opção Bots > Chatbots e depois selecione Ações de Códigos:
As ações do cliente são úteis para desenvolver intenções mais complexas ou quando você deseja adicionar código arbitrário a uma conversa. É uma excelente alternativa para conectar serviços externos para adquirir informações relevantes em tempo real na conversa com o usuário.
Como CRIAR uma ação de código
Primeiro, você precisará criar uma ação do cliente na tela Códigos. Olhar para baixo:
Dê um nome à ação (não se esqueça) e clique em “salvar”.
Com a intenção de ativar a ação, clique em “Respostas”. De lá vá para" Ação", escolher“Ações de código” e “Code Action” e aí selecione o código que será executado:
Recursos de código
Oferecemos suporte a 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", // accessed by "turfHelpers" var
"@turf/turf": "^6.5.0", // accessed by "turf" var
"axios": "^1.9.0",
"bluebird": "^3.5.1", // accessed by "bluebird" var
"fast-csv": "^4.3.6", // accessed by "csv" var
"googleapis": "^92.0.0", // accessed by "google" var
"js-sha256": "^0.9.0", // accessed by "sha256" var
"jsonwebtoken": "^9.0.2", // 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
"moment-timezone": "^0.5.34", // accessed by "momentTimezone" var
"node-fetch": "^2.6.6", // accessed by "fetch" var
"request": "^2.88.2",
"request-promise": "^4.2.5", // accessed by "rp" var
"secure-random": "^1.1.1", // accessed by "securedRandom" var
"sharp": "^0.34.1", // accessed by "sharp" var
"uuid": "^11.0.3", // accessed by "uuidv4" var
"xml2js": "^0.6.2", // accessed by "xml2js" var
"xml2json": "^0.7.1"
}
Entrada de ação do cliente
Ao ativar o código, serão fornecidas todas as informações que temos sobre o usuário, conversas e configurações gerais. 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": "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 de contexto
Um objeto somente leitura que possui informações relevantes que podem exigir ação de código. Fornece:
- userData: Todas as informações sobre um usuário, incluindo tags e variáveis, se houver;
- mensagem: informações sobre a última mensagem do usuário;
- params: Parâmetros opcionais que podem ser enviados usando uma regra.
Por exemplo:
const userFirstName = context.userData.FIRST_NAME;
O objeto de usuário
Este objeto permite ler e escrever variáveis que persistirão para o usuário. É um local muito útil para armazenar dados relacionados ao usuário.
Lembre-se de que os valores deverão ser do tipo string
- Para ler um valor: user.get('nomeVariável')=> irá retornar o valor da variável "nomeVariável" como string ou nulo caso ela não possua valor
- Para inserir um valor: user.set('nomeVariável', 'valor')
Por exemplo:
if ( !user.get('neverWasHere') )
user.set('neverWasHere','true');
O valor neverWasHere será verdadeiro para sempre ou mesmo quando outra ação do cliente definir um valor diferente.
Na seção de configuração de variáveis é possível alterar o tipo da variável e se ela ficará visível aos operadores.
Além disso, é possível que a variável expire junto com a seção, ou seja, após uma hora de inatividade.
Usar entidades EntityLoader
Quando um arquivo cvs for carregado no menu “registros” da plataforma, as ações do cliente terão acesso a ele. Você pode filtrar uma lista salva.
/*Entidade carregada:
identificação | nome
1 | Gabriel
2 | Dário
*/
//Use a função EntityLoader para ler e tratar as entidades carregadas
async function verifyUser(value) {
return new Promise(async(resolve, reject) => {
entityLoader(ENTITY_NAME, async(data) => {
if (!data) {
bmconsole.log('A entidade não existe ou está vazia.');
}
// esta linha valida se dentro da entidade carregada possui o valor buscado (value) na coluna informada (ENTITY_FIELD)
const exists = data.map((it) => it[ENTITY_FIELD]).includes(value);
// Imprime o valor encontrado
bmconsole.log(exists);
});
});
}
Neste exemplo você deve substituir o ENTITY_NAME pelo nome da entidade criada e o ENTITY_FIELD pela coluna a ser buscada.
O objeto conceptRedis
Uma instância de banco de dados está disponível para uso com ações do cliente. Você pode:
const redis =conectarRedis();
const minhaChave = redis.pegar('chave');
Suporte completo ao redis é fornecido. Confira o modo oficial: Biblioteca Redis
Resultado de uma ação do cliente
Quaisquer resultados adicionais que uma ação do cliente queira criar devem ser feitos usando o objeto de resultado.
- Para dizer algo ao usuário usando texto:`result.text('uma mensagem')`
- Para mostrar uma imagem ao usuário:`result.imagem ('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.arquivo ('https://example.com/meuarquivo.doc')`
- Para enviar á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') // um botão que vai abrir uma página
.addLocationButton() // Solicita ao usuário sua localização por GPS
.quickReplies() // Marca os botões para serem mostrados como pills
.addPhoneButton('call me', '+11233212312')
.addButton('click me', 'rule with name XX') // Quando se clica no botão, redireciona para a intenção definida
.send(); // send deve ser sempre chamado para o envio do botão à conversa
Vá para a outra regra
É possível executar uma regra, após completar a ação do cliente, com muita facilidade. Isso é útil porque depois de dizer algo ao usuário, alterar alguns dados ou modificar seu status, você desejará continuar o fluxo da conversa acionando uma regra.
result.gotoRule('um nome de regra');
FINALIZAÇÃO da ação do cliente
O comando result.done() deve ser executado quando a ação do cliente for concluída.
É muito importante chamar o result.done() no final de cada ação do cliente, para finalizar sua execução
rp({tipo:'https://script.google.com/macros/s/AKfycbyd5AcbAnWi2Yn0xhFRbyzS4qMq1VucMVgVvhul5XqS9HkAyJY/exec?tz=Asia/Tokyo Japan', json:true})
.then(json=> {
//dizendo a hora
result.text('A hora em Tóquio é' + json.fulldate);
//não esqueça de finalizar a execução
result.done();
})
.catch(erro => {
result.text('Problemas:' + erro +'|' +JSON.stringify(erro));
result.done();
});
Uso de listas personalizadas (Lista JSON)
Se você quiser usar opções para uma pergunta que é configurada dinamicamente e muda ao longo do tempo, é possível adicionar um valor a uma variável especial dentro de uma ação do cliente.
No código Javascript será necessário criar uma lista de objetos, cada um com os campos “id” e “nome”. Você pode adicionar outras chaves a esses objetos, mas isso não é obrigatório. Olhe para o exemplo:
const PAÍSES = ['Argentina','Bolívia','Brasil','Chile','México','Paraguai','Peru','Uruguai'];deixar minhaJSONList = [];
minhaJSONList =PAÍSES.mapa((país, índice) => {retornar {eu ia: índice,nome: país }; });
//result.text(JSON.stringify(myJSONList)); user.set('países', JSON.stringify(myJSONList));
resultado.feito();
Para usar esta variável em um intent, você precisará declarar que os valores válidos para a pergunta são de uma Lista JSON customizada e referenciar a variável usada no código.
Integrar com um serviço REST
Esses tipos de integrações geralmente são usados para obter ou enviar dados por meio de uma API. Se necessário, os dados podem ser salvos no bot usando variáveis. Veja como chamar um serviço REST externo para obter ou enviar informações no exemplo a seguir.
rp({tipo:'https://httpbin.org/anything',JSON:verdadeiro})
.então(resposta => {
//Você pode obter/definir variáveis de usuário
do utilizador.definir('dados', resposta.dados);
resultado.texto('Chamada bem sucedida para serviço remoto!: ' +JSON.restringir(resposta));
resultado.feito();
}) .pegar(erro => {
resultado.texto('Problemas!:' + err.mensagem);
resultado.feito();
});
Integrar com um serviço SOAP
Esses tipos de integrações geralmente são usados para obter ou enviar dados por meio de uma API. Se necessário, os dados podem ser salvos no bot usando variáveis. Veja abaixo como chamar um serviço SOAP externo para obter ou enviar informações.
const solicitação =`<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<soapenv:Cabeçalho/>
<soapenv:Corpo>
<tem:itemData>
<tem:dataOne>MeusDados</tem:strUser>
</tem:itemData>
</soapenv:Body>
</soapenv:Envelope>`;
rp({tipo:`https://www.custom-service.com/myService.asmx`,
método:'PUBLICAR',
cabeçalhos: {
'Tipo de conteúdo':'texto/xml',
'SOAPAção':'http://tempuri.org/MyAction',
'Comprimento do conteúdo':Amortecedor.comprimento de byte(solicitar)
},
corpo: solicitar
})
.então(resposta => {
xml2js.analisarString(resposta, (err, parsedResponse) => {
//Você pode obter/definir variáveis de usuário
do utilizador.definir('dados', parsedResponse.responseResult);
resultado.texto('Chamada bem sucedida para serviço remoto!: ' +JSON.restringir(parsedResposta));
resultado.feito();
});
}).pegar(erro => {
do utilizador.definir('erro',`Erro rp SOAP${err}`);
resultado.feito();
});
Crie uma ação do cliente com parâmetros
Pode ser criado usando a ação “Ação do Cliente com Parâmetros”:
Ou a partir do código, usando um botão que chama outra Ação do Cliente:
resultado.construtor de botões()
.addClientActionButton('Nome do botão',//Nome que aparecerá no botão
'Número de ações do cliente',//Número de ações do cliente
{
'chave':'valor',
'chave2':'outro_valor'
})//Objeto JSON com os parâmetros a serem enviados
.construirButtons();
Para usar parâmetros enviados para Client Action:
const minhaVar = context.params.key
const minhaVar2 = context.params.key2
Crie uma biblioteca de utilitários usando ações de código
Na biblioteca de utilitários você pode criar funções que deseja reutilizar para encontrá-las rapidamente. Dessa forma você evita código duplicado e agiliza o processo.
Então eles podem chamá-lo de qualquer outro código da seguinte maneira. O nome deve ser exatamente o mesmo:
Execute uma consulta a uma API externa a partir de uma ação do cliente Botmaker
Para executar uma consulta a uma API externa a partir de uma ação do cliente Botmaker, consulte o exemplo a seguir:
Escrito por: Equipe Botmaker
Atualizado: 25/02/2024