Contextos

Contextos disponíveis nas caixas de código

Como usar

• Os objetos disponíveis dependem do momento em que o código é executado: entrada do usuário, entrada no nó, retorno externo ou encerramento.
• As propriedades abaixo foram observadas no catálogo do Botengine e nos fluxos documentados. Elas não substituem a referência dos comandos dialog.*.
• Para alterar variáveis ou o fluxo, prefira os comandos documentados, como dialog.set(...), dialog.get(...), dialog.go(...) e dialog.visible(...).
• Não assuma que uma propriedade estará preenchida em todos os nós. Sempre trate null ou ausência de valor quando o dado for opcional.

Entrada atual — input

input representa a entrada que disparou a execução atual. O conteúdo varia conforme o canal e o tipo de nó.

input.text

Efeito: disponibiliza o texto digitado ou enviado pelo usuário.

Uso típico: validar a resposta, comparar opções ou encaminhar o fluxo.

if (utils.inputMatches(input.text, ['sim', 's'])) {
  dialog.go('node-confirmado');
} else {
  dialog.go('node-nao-confirmado');
}

input.mediaId

Efeito: disponibiliza o identificador de uma mídia recebida ou coletada anteriormente.

Uso típico: enviar a mídia para análise de imagem ou utilizar o identificador em uma integração.

dialog.imageAnalysis(input.mediaId, 'Leia o número do documento.');

input.payload

Efeito: disponibiliza o payload de uma resposta externa, sinal ou integração que retomou o fluxo.

Uso típico: extrair informações de um retorno assíncrono.

var resultado = JSON.parse(input.payload);
dialog.set('statusConsulta', resultado.status);

input completo

Alguns comandos recebem o objeto de entrada inteiro, e não apenas uma propriedade.

dialog.sendTemplateLocationMsg(input);

O formato exato de input depende do canal ou da integração que gerou a entrada. Valide os campos antes de utilizá-los.

Variáveis do fluxo — variables

variables representa os dados associados à sessão e ao fluxo. A forma documentada para alterar variáveis é usar dialog.set(...); a forma documentada para ler é dialog.get(...).

dialog.set(name, value)

Efeito: grava uma variável de sessão para ser usada em etapas posteriores do fluxo.

dialog.set('nomeCliente', input.text);

dialog.get(name)

Efeito: lê uma variável de sessão. Quando ela não existe, o retorno documentado é null.

var nome = dialog.get('nomeCliente');
if (nome != null) {
  dialog.say('Olá, ' + nome + '!');
}

variables.get(name)

Efeito: acessa uma variável pelo nome no objeto de variáveis disponível no script. Esse padrão aparece nos exemplos do catálogo para alimentar comandos dialog.* e utils.*.

var cpf = variables.get('cpf');
if (utils.equals(cpf, null)) {
  dialog.go('node-solicitar-cpf');
}

Para novos scripts, mantenha uma convenção única no fluxo. dialog.get(...) é a forma explicitamente documentada para leitura de variável de sessão; variables.get(...) é um padrão de acesso presente nos exemplos existentes.

variables.nomeDaVariavel

Efeito: acessa uma variável por propriedade direta. Esse padrão também aparece em scripts existentes.

var protocolo = variables.protocolo;
dialog.say('Seu protocolo é ' + protocolo + '.');

Prefira nomes simples e consistentes. Antes de publicar, confirme que o valor foi criado anteriormente com dialog.set(...) ou por um nó especializado.

variables.contact

Efeito: representa o objeto de contato associado à sessão depois que um contato é vinculado.

var contato = variables.contact;
if (contato != null) {
  dialog.say('Olá, ' + contato.name + '!');
}

Para buscar ou alterar contatos, use as funções contact.* da referência [[contact-code-commands-user-reference|Comandos contact.*]].

Sessão — session

session contém metadados do atendimento e do estado de execução. As propriedades abaixo são as utilizadas nos exemplos e fluxos documentados.

session.contactId

Efeito: identifica o contato vinculado à sessão atual.

var contatoId = session.contactId;
if (contatoId != null) {
  var contato = contact.findById(contatoId);
}

session.channel

Efeito: informa o canal por onde a sessão está sendo atendida.

if (session.channel == 'whatsapp') {
  dialog.setMediaUpload(true);
}

session.count

Efeito: informa a contagem de iterações ou mensagens processadas na sessão.

if (session.count == 0) {
  dialog.say('Olá! Vamos começar.');
}

session.currentDialogNodeId

Efeito: identifica o nó do diálogo que está ativo na sessão.

var noAtual = session.currentDialogNodeId;
dialog.emit('entrou-no-' + noAtual);

session.sessionSituation

Efeito: representa a situação atual da sessão, como atendimento pelo bot ou por humano.

if (session.sessionSituation == 'HUMAN') {
  dialog.set('retornoHumano', true);
}

session.threadId

Efeito: identifica a thread usada por integrações legadas do Assistants API v1.

dialog.sendToAssistant('asst_legacy', session.threadId, input.text);

session.lastResponseId

Efeito: identifica a resposta anterior usada para continuar uma conversa com o Assistants API v2.

dialog.sendToAssistantV2('asst_xyz', session.lastResponseId, 'call-2', input.text, null);

session.creation

Efeito: representa o momento de criação da sessão e pode ser usado em cálculos de duração quando o formato do runtime permitir.

var duracao = Date.now() - session.creation;
dialog.emit('tempo-desde-inicio', duracao);

Nem toda propriedade de session é preenchida em todos os canais ou versões do runtime. Use apenas propriedades confirmadas para o fluxo que está sendo criado.

Variáveis globais — globalVariables

globalVariables é disponibilizado pelo runtime para representar dados compartilhados entre fluxos e subprocessos ativos.

Estado do contrato

O catálogo atual confirma a disponibilidade do objeto, mas não documenta uma assinatura completa de leitura ou escrita para ele. A operação explicitamente documentada para gravação global é:

dialog.updateGlobalVariable('idTransacao', txId);

Efeito: grava uma variável global compartilhada entre fluxos e subprocessos ativos.

Para leitura, não utilize uma sintaxe presumida sem confirmar a versão do Botengine. Quando o dado for específico da sessão atual, prefira dialog.get(...) e dialog.set(...).

Resumo por momento de execução