---
title: "JavaScript"
slug: "javascript"
updated: 2026-09-10T18:50:59Z
published: 2026-09-10T18:50:59Z
canonical: "docs.omnisiga.ai/javascript"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnisiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript

## JavaScript básico em caixas de código

| Família | Finalidade |
| --- | --- |
| JavaScript | Recursos da linguagem observados nos exemplos, como `JSON`, `Date`, condicionais, arrays e objetos. |

## 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:

- `&amp;&amp;` — 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.

---