Manipulação de Objetos

Variáveis do Contexto da Conversa

Durante o fluxo da conversa, informações sobre o contexto da conversa podem ser guardadas em alguma destas etapas ou ações:

• Mensagem de Texto ou Cartão:

  • Ao 'Salvar Resposta', a informação pode ser um campo do objeto Usuário ou algum outro objeto personalizado. Caso seja do usuário a informação será salva diretamente na base de dados, caso contrário será armazenada temporariamente como variável do contexto da conversa, podendo ser acessada através do nome do objeto seguido do nome do campo, como exemplo: endereco.cep

• Intenções:

  • No caso de NLP, tenho algum matching de intenção, as entidades desta intenção serão armazenadas temporariamente como variáveis do contexto da conversa, podendo ser acessadas acrescentado 'context.objetcs.' a frente do nome das variáveis das intenções, como exemplo: context.objetcs.refeicao

Query de Objetos e Update de Registros

Você tem a opção aqui de fazer queries(consultas) de registros de objetos personalizados. Para que fiquem disponíveis durante a execução do código. O resultado será retornado como tipo array. Para acessar o resultado de uma query basta adicionar '__s' ao lado direito do nome do objeto, por exemplo: pedido__s

Por enquanto as opções de execução da query são:

• Limite de registros: responsável por limitar a quantidade de registros retornados pela query.

• Condição de Tempo: caso a quantidade de registros da query seja maior que o limite, define uma ordem de retorno dos registros: por mais recentes ou mais antigos.

Além dos campos personalizados cada registro da query terá disponível os seguintes campos do sistema:

• id: ID do registro

• obj_id: ID do Objeto do registro

• parents: objeto controlador do objeto atual (ou pai do objeto atual)

  • parents.id: ID do objeto controlador

  • parents.name: Nome do objeto controlador

• grandparents: objeto controlador do objeto controlador do objeto atual (ou avô do objeto atual)

  • grandparents.id: ID do objeto controlador

  • grandparents.name: Nome do objeto controlador

• createdAt: horário (em milissegundos) de quando o registro foi criado.

• updatedAt: horário (em milissegundos) de quando o registro foi atualizado.

Segue abaixo um exemplo de como tratar o retorno da query:

// Soma o total do valor dos últimos pedidos do usuário atual
var total = 0;
for (var x in pedido__s){
   // Acessa um pedido por vez
   var pedido = pedido__s[x];

   // Dentro de cada pedido, acessa o campo Valor e adiciona ao Total
   total += pedido.valor;
}

Por padrão o registro do objeto User, referente ao usuário atual, e as variáveis de Contexto da Conversa estarão sempre disponíveis. Portanto não precisa fazer query para o objeto User. Para acessar o campo do sistema ID do usuário atual, basta usar: user.id. E para acessar, por exemplo, uma variável de contexto chamada produto_atual basta usar: context.objetcs.produto_atual

Qualquer alteração de valor dos campos personalizados destes objetos será refletida na base de dados depois da execução do código.

Criação de Registros

Você pode também criar novos registros de objetos personalizados. Basta definir estes registros como tipo objeto do javascript (formato JSON). Lembrando de preencher os campos obrigatórios. E quando tiver pronto, adicioná-los ao respectivo objeto que poderá ser usado da seguinte forma: Nome do Objeto + '__c', por exemplo: item_do_pedido__c

Aqui temos um exemplo de como criar um registro:

// Declara a variável que terá as informações do novo Item do Pedido
var novo_item_pedido = {}

// Preenche os campos do novo registro
novo_item_pedido.numero = '12345';
novo_item_pedido.produto = context.objetcs.produto_id;
novo_item_pedido.quantidade = context.objetcs.produto_quantidade;
novo_item_pedido.valor = context.objetcs.produto_valor;

// Preencha o campo controlador que veio da querym neste caso o ID do Pedido
if (pedido__s[0]){
   novo_item_pedido.pedido = pedido__s[0].id;

   // Adiciona o novo registro para ser criado
   item_do_pedido__c.push(novo_item_pedido);
}

Caso você esteja criando um registro de um objeto que possui objeto Controlador (ou seja, possui um relacionamento de 1 para N), você precisa informar o ID deste registro controlador no respectivo campo. Caso contrário este registro não será criado.

Exclusão de Registros

Também existe a opção de excluir registros de objetos personalizados. Basta fazer a query, conforme mencionado acima, pegar o id dos registros que devem ser excluídos, e adicioná-los ao respectivo objeto que poderá ser usado da seguinte forma: Nome do Objeto + '__d', por exemplo: pedido__d

Segue abaixo exemplo de como excluir um registro:

// Percorre todos os pedidos retornados pela query
for (var i in pedido__s){

   // Identifica o pedido com Status Incompleto
   if (pedido__s[i].status === 'incompleto'){

      // Adiciona o ID do registro para ser excluído
      pedido__d.push( pedido__s[i].id );
   }
}

Caso você esteja excluindo um registro de um objeto que possui abaixo dele algum objeto Controlado (ou seja, possui um relacionamento de 1 para N), todos os registros controlados por ele serão excluídos também.

Envio de Mensagem de Texto

Existe a alternativa para enviar mensagens ao usuário usando código Javascript. É importante para os casos, por exemplo, onde o envio de mensagem depende de informações disponíveis depois de realizada uma query. Segue abaixo exemplo de como enviar mensagem:

// Define uma variável com as informações necessárias para enviar a mensagem
var message_1 = {
   type: 'text',
   text: 'O total do seu pedido atual é R$ ' + context.objetcs.pedido_total,
   quick_replies: [{
      caption: 'Confirmar',
      type: 'context_variable',
      value: {pedido_confirmado: context.objetcs.pedido}
   }]
};

// Adiciona a mensagem para ser enviada
send_message.push(message_1);

Segue abaixo as informações que precisam ser fornecidas para criar uma mensagem de texto. Quando usado no código precisa estar com o tipo objeto do Javascript (formato JSON).

• type: sempre coloque 'text'. Obrigatório.

• text: coloque aqui o texto que deseja enviar. Obrigatório e limite de 320 caracteres.

• quick_replies: array com informações de cada quick reply. Não obrigatório e limite de até 10 replies.

  • caption: texto que aparece visível ao usuário. Obrigatório e limite de até 20 caracteres.

  • type: pode ser 'text' representando um texto simples. Ou pode ser 'context_variable' representando um tipo objeto do Javascript contendo informações que poderão ser acessadas durante o tempo do contexto da conversa atual. Obrigatório.

  • value: depende do type acima, se for 'text', preencher aqui o texto. Se for 'context_variable' preencher aqui o objeto no formato JSON. Obrigatório.

Envio de Mensagem de Cartões

Aqui temos a opção de enviar mensagens que contenha cartões.

// Define uma variável com as informações necessárias para enviar a mensagem
var message_2 = {
   type: 'cards',
   cards: [{
      title: 'Opção 1',
      subtitle: 'Detalhes da opção',
      image_url: '
https://cosmobots.io/static/media/testing.png
',
      buttons: [{
         caption: 'Selecionar',
         type: 'context_variable',
         value: {produto_selecionado: produto__s[0].id}
      },{
         caption: 'Acessar Detalhes',
         type: 'url',
         value: '
www.teste.com
'
      }]
   }],
};

// Adiciona a mensagem para ser enviada
send_message.push(message_2);

Segue abaixo as informações que precisam ser fornecidas para criar uma mensagem de cartões. Quando usado no código precisa estar com o tipo objeto do Javascript (formato JSON).

• type: sempre coloque 'cards'. Obrigatório.

• cards: array com informações de cada cartão. Obrigatório.

  • title: título do cartão. Obrigatório e limite de até 80 caracteres.

  • subtitle: subtítulo do cartão. Não Obrigatório e limite de até 80 caracteres

  • image_url: url da imagem do cartão. Não Obrigatório e limite de até 120 caracteres.

  • buttons: array com informações de cada botão. Não Obrigatório e limite de até 3 botões.

    • caption: texto que aparece visível ao usuário. Obrigatório e limite de até 20 caracteres

    • type: pode ser 'url' ou 'context_variable' representando um tipo objeto do Javascript contendo informações que poderão ser acessadas durante o tempo do contexto da conversa atual. Obrigatório.

    • value: depende do type acima, se for 'url', preencher aqui a url válida. Se for 'context_variable' preencher aqui o objeto no formato JSON. Obrigatório.

Existe um tempo limite de execução de 15 segundos do código javascript. Portanto se passar desse limite a execução do código será interrompida e será retornado um erro que pode ser consultado no histórico da conversa.