---
title: "Funções utils.*"
slug: "funcoes-utils"
updated: 2026-09-10T18:49:48Z
published: 2026-09-10T18:49:48Z
canonical: "docs.omnisiga.ai/funcoes-utils"
---

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

# Funções utils.*

## Funções `utils.*`

| Família | Finalidade |
| --- | --- |
| `utils.*` | Funções auxiliares para cálculo, transformação, comparação, data/hora, codificação e criptografia. |

## Como usar

- As funções `utils.*` normalmente calculam ou transformam um valor; elas não enviam mensagens nem mudam o fluxo sozinhas.
- Combine o resultado com comandos `dialog.*`, por exemplo `dialog.set(...)`, `dialog.say(...)` ou `dialog.go(...)`.
- Datas e horários usam timestamps em milissegundos quando a assinatura recebe `timestamp`.
- Informe o fuso como identificador IANA, por exemplo `America/Sao_Paulo`.
- As funções de comparação podem receber valores vindos de variáveis de sessão e ajudam a evitar comparações inconsistentes entre texto, número e booleano.
- A função de criptografia 3DES depende de uma chave configurada no ambiente. Não coloque chaves ou segredos diretamente na caixa de código.

---

## Tempo

#### `utils.nowInSeconds()`

Retorna o timestamp atual em segundos (epoch UTC).

```
var agora = utils.nowInSeconds();
```

#### `utils.now()`

Retorna o timestamp atual em milissegundos (epoch UTC).

```
var agora = utils.now();
```

#### `utils.hourOfDay()`

Retorna a hora atual (0–23) no fuso UTC.

```
if (utils.hourOfDay() < 8 || utils.hourOfDay() >= 18) { dialog.go('node-fora-de-horario'); }
```

#### `utils.hourOfDay(timezone)`

Retorna a hora atual (0–23) no fuso informado.

```
var hora = utils.hourOfDay('America/Sao_Paulo');
```

#### `utils.minutesOfHour()`

Retorna os minutos do horário atual (0–59) em UTC.

```
var minuto = utils.minutesOfHour();
```

#### `utils.minutesOfHour(timezone)`

Retorna os minutos do horário atual (0–59) no fuso informado.

```
var minuto = utils.minutesOfHour('America/Sao_Paulo');
```

#### `utils.getDayOfTheWeek()`

Retorna o dia da semana atual em `America/Sao_Paulo`. 1=segunda … 7=domingo (ISO-8601).

```
if (utils.getDayOfTheWeek() >= 6) { dialog.go('node-fim-de-semana'); }
```

#### `utils.getDayOfTheWeek(timestamp)`

Dia da semana para timestamp em milissegundos, no fuso `America/Sao_Paulo`.

```
var dia = utils.getDayOfTheWeek(Date.now());
```

#### `utils.getDayOfTheWeek(timezone)`

Dia da semana atual no fuso informado.

```
var dia = utils.getDayOfTheWeek('America/Sao_Paulo');
```

#### `utils.getDayOfTheWeek(timestamp, timezone)`

Dia da semana para timestamp + fuso explícitos.

```
var dia = utils.getDayOfTheWeek(Date.now(), 'America/Sao_Paulo');
```

#### `utils.todayAsString(timezone)`

Retorna a data atual como string `'yyyy/MM/dd'` no fuso informado.

```
var hoje = utils.todayAsString('America/Sao_Paulo');
```

#### `utils.nowAsString(timezone, format)`

Retorna o momento atual como string no formato e fuso informados.

```
var agora = utils.nowAsString('America/Sao_Paulo', 'dd/MM/yyyy HH:mm');
```

#### `utils.compareDates(d1, d2, format)`

Compara duas strings de data no formato especificado. Retorna negativo se d1 < d2, zero se iguais, positivo se d1 > d2.

```
if (utils.compareDates(variables.get('dataVenc'), utils.todayAsString('America/Sao_Paulo'), 'yyyy/MM/dd') < 0) {
  dialog.go('node-vencido');
}
```

#### `utils.getGreetings(language, fuso)`

Retorna saudação contextualizada (`'Bom dia'`, `'Boa tarde'` ou `'Boa noite'`) com base na hora e fuso (offset em horas relativo ao UTC, ex: -3 para BRT).

```
dialog.say(utils.getGreetings('pt', -3) + ', ' + variables.get('nome') + '!');
```

---

## Comparação e matching

#### `utils.inputMatches(text, patterns)`

Verifica se um texto corresponde a algum dos padrões, com tolerância a erros de digitação (Levenshtein normalizado + regex). Remove acentos antes de comparar.

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

#### `utils.insensitiveInputMatches(text, patterns)`

Semelhante ao `inputMatches`, mas sem normalização de acentos e sem fuzzy. Faz match case-insensitive por regex simples.

```
if (utils.insensitiveInputMatches(input.text, ['SIM', 'sim', 'Sim'])) { dialog.go('node-confirmado'); }
```

#### `utils.inputDistance(text, patterns, isOneOf)`

Retorna a distância de edição (Levenshtein) entre o texto e a lista de padrões.

- `isOneOf=true`: retorna a menor distância encontrada (positivo = match próximo, -1 = nenhum).
- `isOneOf=false`: retorna a menor distância negada (negativo = match próximo, 0 = nenhum).

```
var dist = utils.inputDistance(input.text, ['cancelar', 'cancel'], true);
if (dist >= 0) { dialog.go('node-cancelamento'); }
```

#### `utils.equals(value, comparator)`

Verifica igualdade com aware de tipo: String por igualdade, Number por valor numérico, Boolean por parse. Use no lugar de `===` quando o valor pode vir de variáveis de sessão com tipo incerto.

```
if (utils.equals(variables.get('status'), 'ativo')) { dialog.go('node-ativo'); }
```

#### `utils.greaterThan(value, comparator)`

Verifica se `value &gt; comparator` (numérico ou string).

```
if (utils.greaterThan(variables.get('tentativas'), '3')) { dialog.go('node-bloqueio'); }
```

#### `utils.lessThan(value, comparator)`

Verifica se `value &lt; comparator`.

```
if (utils.lessThan(variables.get('tentativas'), '3')) { dialog.go('node-tentar-novamente'); }
```

#### `utils.greaterThanOrEquals(value, comparator)`

Verifica se `value &gt;= comparator`.

```
if (utils.greaterThanOrEquals(variables.get('idade'), '18')) { dialog.go('node-maior'); }
```

#### `utils.lessThanOrEquals(value, comparator)`

Verifica se `value &lt;= comparator`.

```
if (utils.lessThanOrEquals(variables.get('idade'), '17')) { dialog.go('node-menor-idade'); }
```

#### `utils.contains(text, matcher)`

Verifica se um texto contém uma substring.

```
if (utils.contains(input.text, 'cancelar')) { dialog.go('node-cancelamento'); }
```

#### `utils.startsWith(text, matcher)`

Verifica se um texto começa com uma string específica.

```
if (utils.startsWith(input.text, '/')) { dialog.go('node-comando'); }
```

#### `utils.endsWith(text, matcher)`

Verifica se um texto termina com uma string específica.

```
if (utils.endsWith(input.text, '.pdf')) { dialog.go('node-recebeu-pdf'); }
```

---

## Aleatoriedade

#### `utils.choose(options)`

Escolhe aleatoriamente uma opção do array informado (usa `SecureRandom`). Retorna `null` se o array for nulo ou vazio.

```
var saudacao = utils.choose(['Olá!', 'Oi!', 'Bem-vindo!']);
dialog.say(saudacao);
```

---

## String

#### `utils.truncate(text, maxLength, reverse)`

Trunca um texto ao número máximo de caracteres. Com `reverse=true` mantém os últimos caracteres.

```
var resumo = utils.truncate(variables.get('descricao'), 100, false);
var sufixo = utils.truncate(variables.get('cpf'), 3, true);
```

#### `utils.truncate(text, maxLength)`

Versão sem `reverse` — sempre mantém os primeiros `maxLength` caracteres.

```
var resumo = utils.truncate(variables.get('descricao'), 100);
```

---

## Codificação

#### `utils.toBase64(str)`

Codifica uma string em Base64 (UTF-8).

```
var encoded = utils.toBase64(variables.get('payload'));
```

#### `utils.fromBase64(b64)`

Decodifica uma string Base64 para texto. Retorna `null` se a entrada for nula ou exceder 32 KB.

```
var decoded = utils.fromBase64(variables.get('payloadBase64'));
```

---

## Criptografia

#### `utils._3DESEncrypt(message)`

Criptografa uma mensagem com 3DES/CBC/PKCS5 usando a chave configurada em `env.properties` (`three-des-key` e `three-des-iv`). Retorna a mensagem cifrada em Base64.

```
var cifrado = utils._3DESEncrypt(variables.get('dado'));
```

#### `utils._3DESDecrypt(message)`

Descriptografa uma mensagem 3DES/CBC/PKCS5 (a entrada deve ser a saída de `_3DESEncrypt`).

```
var original = utils._3DESDecrypt(variables.get('dadoCifrado'));
```

---

---