---
title: "Contextos"
slug: "contextos"
updated: 2026-09-10T18:50:47Z
published: 2026-09-10T18:50:47Z
canonical: "docs.omnisiga.ai/contextos"
---

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

# Contextos

## Contextos disponíveis nas caixas de código

| Família | Finalidade |
| --- | --- |
| Contextos | Dados disponibilizados pelo runtime, como `input`, `variables`, `session` e `globalVariables`. |

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

| Momento | Contextos normalmente relevantes | Exemplos |
| --- | --- | --- |
| Entrada do usuário | `input.text`, `variables`, `session` | Validar texto, salvar resposta, navegar |
| Recebimento de mídia | `input.mediaId`, `variables`, `session` | Analisar imagem, salvar resultado |
| Retorno externo | `input.payload`, `variables`, `session` | Fazer parsing, salvar status, seguir para sucesso/erro |
| Entrada do nó | `variables`, `session` | Preparar mensagem ou decisão |
| Atendimento humano | `variables.contact`, `session.contactId`, `session.sessionSituation` | Exibir contexto, identificar contato |

---