JavaScript

JavaScript básico em caixas de código

Antes de usar

• Os scripts são executados em um runtime JavaScript baseado em Nashorn/JVM.
• Esta página documenta apenas recursos observados nos scripts e exemplos existentes; não deve ser tratada como uma referência completa de JavaScript moderno.
• Para ações do fluxo, use as APIs da plataforma: dialog.*, utils.* e contact.*.
• Valide valores nulos e entradas externas antes de convertê-los ou acessá-los.

JSON

JSON.stringify(value)

Efeito: converte um objeto ou array JavaScript em uma string JSON. É útil para enviar payloads a integrações, sinais e comandos que recebem JSON serializado.

var payload = JSON.stringify({
  nome: dialog.get('nome'),
  protocolo: dialog.get('protocolo')
});

dialog.webhook(
  {'Content-Type': 'application/json'},
  'https://api.example.com/eventos',
  'POST',
  payload
);

JSON.parse(text)

Efeito: converte uma string JSON em objeto JavaScript para que seus campos possam ser lidos.

var resultado = JSON.parse(input.payload);
if (resultado.status == 'ok') {
  dialog.go('node-sucesso');
}

Só use JSON.parse(...) quando o conteúdo for realmente JSON válido. Um texto inválido interrompe a execução se não for tratado pelo fluxo.

Datas e números

Date.now()

Efeito: retorna o timestamp atual em milissegundos desde o epoch Unix.

var inicio = Date.now();
dialog.set('inicioProcessamento', inicio);

parseInt(value, radix)

Efeito: converte um valor textual em número inteiro. Use o radix 10 quando o valor for decimal.

var nota = parseInt(dialog.get('nota'), 10);
if (nota >= 9) {
  dialog.go('node-promotor');
}

Verifique se o valor realmente contém um número antes de utilizá-lo em uma comparação.

Condicionais

if e else

Efeito: executam trechos diferentes de código de acordo com uma condição.

var status = dialog.get('status');

if (status == 'aprovado') {
  dialog.go('node-aprovado');
} else {
  dialog.go('node-reprovado');
}

else if

Efeito: permite testar várias condições em sequência.

var idade = parseInt(dialog.get('idade'), 10);

if (idade < 18) {
  dialog.go('node-menor');
} else if (idade < 60) {
  dialog.go('node-adulto');
} else {
  dialog.go('node-idoso');
}

Operadores lógicos

Efeito: combinam ou negam condições:

• && — todas as condições precisam ser verdadeiras;
• || — pelo menos uma condição precisa ser verdadeira;
• ! — nega uma condição.

var nome = dialog.get('nome');
var cpf = dialog.get('cpf');

if (nome != null && cpf != null) {
  dialog.go('node-dados-completos');
} else {
  dialog.go('node-solicitar-dados');
}

Arrays e objetos

Array literal: [valor1, valor2]

Efeito: cria uma lista de valores. Arrays são usados por comandos como dialog.setTags(...), dialog.sendInteractiveList(...) e utils.choose(...).

var opcoes = ['cancelar', 'consultar', 'falar com atendente'];
dialog.set('opcoesDisponiveis', opcoes);

Objeto literal: {chave: valor}

Efeito: cria uma estrutura de dados com propriedades nomeadas. Objetos são usados para atributos, payloads e variáveis compostas.

var cliente = {
  nome: dialog.get('nome'),
  email: dialog.get('email')
};

dialog.set('cliente', cliente);

Acesso a propriedade: objeto.propriedade

Efeito: lê uma propriedade de um objeto.

var status = resultado.status;
dialog.set('statusConsulta', status);

Acesso por chave: objeto['propriedade']

Efeito: lê uma propriedade usando uma chave textual. É útil quando o nome do campo está em uma variável ou quando a chave contém caracteres especiais.

var campo = 'numeroContrato';
var valor = cliente[campo];
dialog.set('contrato', valor);

Texto e composição de mensagens

Concatenação com +

Efeito: combina textos e valores em uma única string.

var nome = dialog.get('nome');
dialog.say('Olá, ' + nome + '!');

Conversão implícita em mensagem

Efeito: ao concatenar um número ou outro valor com texto, o JavaScript converte o valor para representação textual.

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

Para formatações específicas, prefira preparar o valor antes e validar se ele não é null.

Validação defensiva

Comparação com null

Efeito: verifica se um valor existe antes de acessar propriedades ou enviá-lo ao usuário.

var contato = contact.get();

if (contato != null) {
  dialog.say('Olá, ' + contato.name + '!');
} else {
  dialog.go('node-cadastrar-contato');
}

Conversão depois da validação

Efeito: evita converter valores ausentes em números inválidos.

var notaTexto = dialog.get('nota');

if (notaTexto != null) {
  var nota = parseInt(notaTexto, 10);
  dialog.assess('avaliacao-nps', nota);
}

O que não está coberto por esta página

Esta página não documenta métodos avançados de JavaScript, APIs Java, acesso a arquivos, rede direta, reflexão ou bibliotecas externas. Nas caixas de código, utilize as APIs do Botengine e as funções listadas nas referências do projeto.

Convenções recomendadas para uso

Leitura e escrita de variáveis

A referência de contexto explicita dialog.get(...) como a forma documentada de leitura de variável de sessão e dialog.set(...) como forma documentada de gravação. variables.get(...) e variables.nomeDaVariavel aparecem em exemplos existentes; para novos scripts, mantenha uma convenção única no fluxo.

var cpf = dialog.get('cpf');
if (cpf != null) {
  dialog.say('CPF recebido: ' + cpf);
}

Navegação

Use dialog.go(...) para navegação normal. dialog.redirect(...) é sinônimo, mas a fonte recomenda go() em novos scripts.

dialog.go('node-confirmacao');

Tratamento de dados externos

Quando um retorno externo vier em input.payload, valide e faça o parsing antes de acessar propriedades:

if (input.payload != null) {
  var resultado = JSON.parse(input.payload);
  dialog.set('statusConsulta', resultado.status);
}

HTTP: webhook x REST

• dialog.webhook(...): dispara e segue sem aguardar resposta.
• dialog.rest(...): aguarda resposta e roteia por faixa de status.
• dialog.oauthRest(...): equivalente a rest(...), com gestão transparente de OAuth2.

Assistentes IA: v1 x v2

A documentação recomenda dialog.sendToAssistantV2(...) para novos fluxos. dialog.sendToAssistant(...) pertence à integração legada v1. Não misture as duas APIs no mesmo fluxo, pois o estado não é compartilhado.

Sinais e espera

dialog.awaitSignal(...) pode suspender um fluxo indefinidamente se não houver timeout. A própria referência recomenda combinar a espera com dialog.createNamedTimeout(...).

Contatos

Use contact.get() quando o contato já estiver vinculado à sessão. Quando o fluxo pode precisar criar o contato, prefira contact.upsert(...) ou contact.upsertBy(...). Atenção especial a identificadores: customId não deve ser tratado como telefone normalizado e valores inconsistentes podem gerar duplicidade.

Segurança e segredos

A referência de utils.* informa que 3DES depende de uma chave configurada no ambiente. Não coloque chaves ou segredos diretamente na caixa de código.

Limites e pontos que exigem confirmação no ambiente

• O runtime é descrito como JavaScript baseado em Nashorn/JVM; a referência de JavaScript é deliberadamente parcial.
• globalVariables é disponibilizado pelo runtime, mas a fonte não documenta uma assinatura completa de leitura/escrita para ele. A operação explicitamente documentada é dialog.updateGlobalVariable(...).
• A disponibilidade de algumas propriedades de session pode variar conforme canal e versão do runtime.
• findBy(...) documenta vários tipos de identificador; implementações mais recentes também registram bsuid, mas a própria fonte recomenda confirmar a versão do serviço antes do uso.
• dialog.createNamedTimeout(...) contém uma observação de nomenclatura: o parâmetro targetNode aparece como targetNone no código original e é tratado na documentação como o nó destino.
• A análise de imagem por dialog.imageAnalysis(...) exige mediaId previamente produzido no fluxo; para URL pública, use dialog.imageAnalysisByUrl(...).
• dialog.sendSMS(...) exige mensagem não vazia e aceita Transactional ou Promotional.
• dialog.checkPFCompleta(...) retorna false silenciosamente quando mediasJson é JSON malformado.