---
title: "Comandos input.*"
slug: "comandos-input"
updated: 2026-10-02T20:22:05Z
published: 2026-10-02T20:22:05Z
canonical: "docs.omnisiga.ai/comandos-input"
---

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

# Comandos input.*

O objeto `input` reúne os dados da entrada que está sendo processada pela caixa de código. No canal **E-mail**, ele disponibiliza informações como remetente, destinatário, assunto, conteúdo, protocolo e anexos.

Esses dados podem ser utilizados para classificar mensagens, direcionar o fluxo, armazenar informações na sessão, responder ao remetente e enviar dados para integrações.

## Como interpretar `input`

`input` representa o evento que está sendo processado naquele momento. Ele não deve ser utilizado como armazenamento permanente da sessão.

Para manter uma informação disponível em etapas posteriores do fluxo, utilize `dialog.set(...)`.

### Regra principal

- Leia os dados necessários diretamente de `input`.
- Use `dialog.set(...)` para guardar informações que precisarão ser utilizadas depois.
- Valide `null`, valores vazios e o tipo do dado antes de utilizá-lo.
- Não presuma que os dados da mensagem original continuarão disponíveis depois de uma operação externa.

## Em qual evento cada `input` aparece

| Evento da caixa de código | Conteúdo esperado | Observação |
| --- | --- | --- |
| `onInput` | Entrada da mensagem de e-mail | É o melhor momento para ler remetente, assunto, corpo e anexos. |
| `onEnter` | Contexto da interação que levou à entrada na caixa | Pode conter os dados da mensagem durante o processamento; em entradas programáticas pode ser `null`. |
| `onExit` | Contexto da transição atual | Não dependa desse evento para recuperar a mensagem original. Salve previamente os dados necessários. |
| `onExternal` | Dados do retorno de uma operação externa | O `input` passa a representar o retorno externo. |
| `onEnter` de timeout, erro, inatividade ou execução única | Pode ser `null` | Proteja o acesso antes de utilizar `input.*`. |

Exemplo de validação:

```
if (input == null) {
  dialog.set('erroContexto', 'A entrada atual não está disponível');
} else {
  dialog.set('tipoCanalAtual', String(input.channel));
}
```

## Campos específicos do E-mail

Os campos abaixo representam informações da mensagem recebida por e-mail.

| Campo | Conteúdo | Uso comum |
| --- | --- | --- |
| `input.bodyPlain` | Corpo em texto puro | Processar ou armazenar o conteúdo sem HTML. |
| `input.bodyHtml` | Corpo HTML da mensagem | Preservar a formatação original ou enviar o conteúdo para uma integração. |
| `input.html` | Representação HTML registrada para a mensagem | Utilizar quando uma integração exigir o conteúdo HTML. |
| `input.text` | Representação textual usada pelo motor | Comparar, classificar, armazenar ou enviar para análise. |
| `input.sender` | Remetente do e-mail | Identificar o remetente e enviar uma resposta. |
| `input.from` | Origem registrada na mensagem | Consultar a origem quando esse dado for necessário. |
| `input.to` | Destinatário registrado | Identificar o endereço que recebeu a mensagem. |
| `input.recipient` | Destinatário registrado pelo serviço de e-mail | Diagnosticar o roteamento ou montar payloads específicos. |
| `input.subject` | Assunto do e-mail | Classificar, direcionar ou responder à mensagem. |
| `input.domain` | Domínio associado ao atendimento | Selecionar domínio, template ou montar respostas. |
| `input.referenceProtocol` | Protocolo associado à mensagem original | Continuar o atendimento ou guardar o protocolo. |
| `input.attachments` | Lista de anexos da mensagem | Ler nome, tipo, URL e tamanho dos arquivos recebidos. |

### Diferenças entre `sender`, `from`, `to` e `recipient`

Esses campos são mantidos separadamente e podem apresentar valores diferentes.

Como regra prática:

- use `input.sender` como endereço para responder ao remetente;
- use `input.to` e `input.recipient` para analisar o roteamento da mensagem;
- use `input.from` quando o processamento exigir esse campo;
- quando a diferença entre os valores for importante para o negócio, preserve os quatro valores para análise.

### Anexos

Os anexos recebidos por e-mail ficam em `input.attachments`.

Cada item possui as seguintes propriedades:

| Campo | Conteúdo |
| --- | --- |
| `attachment.contentType` | Tipo MIME do arquivo, quando informado. |
| `attachment.mediaUrl` | URL da mídia armazenada. |
| `attachment.name` | Nome do arquivo. |
| `attachment.size` | Tamanho numérico do arquivo. |

No atendimento por e-mail, não use `input.file`, `input.image`, `input.audio` ou `input.video` como substitutos de `input.attachments`.

## Campos comuns de mensagens

O objeto `input` também possui campos utilizados por outros canais. Alguns deles normalmente ficam vazios no atendimento por e-mail.

### Identificação, roteamento e sessão

| Campo | Uso no atendimento por e-mail | Observação |
| --- | --- | --- |
| `input.id` | Identificar a mensagem recebida | Útil para auditoria e correlação. |
| `input.channel` | Identificar o canal | No e-mail, o valor esperado é `EMAIL`. |
| `input.organizationId` | Identificar a organização | Dado de contexto. |
| `input.sessionId` | Identificar o atendimento | Útil para correlação com integrações. |
| `input.dialogId` | Identificar o diálogo em execução | Útil para diagnóstico e integrações controladas. |
| `input.gdId` | Identificar o grupo/configuração do diálogo | Dado de contexto do fluxo. |
| `input.dId` | Identificar o diálogo original | Dado de contexto da mensagem. |
| `input.timestamp` | Indicar o momento da mensagem | O valor do e-mail é normalizado para milissegundos. |
| `input.contactId` | Identificar o contato associado, quando disponível | Trate como opcional no atendimento por e-mail. |

### Mídia e localização

Os campos abaixo pertencem ao contexto geral de mensagens, mas normalmente não representam os anexos de um e-mail:

| Campo | Situação esperada no E-mail |
| --- | --- |
| `input.audio` | Normalmente ausente. |
| `input.image` | Normalmente ausente. |
| `input.file` | Normalmente ausente. |
| `input.video` | Normalmente ausente. |
| `input.latitude` | Normalmente ausente. |
| `input.longitude` | Normalmente ausente. |
| `input.author` | Pode ser `null`. |

Os anexos de e-mail devem ser lidos por meio de `input.attachments`.

### Campos de outros canais

Os campos abaixo não fazem parte do uso normal do canal E-mail:

- `input.originId`
- `input.originAccountId`
- `input.messengerRecipientId`
- `input.pvar`
- `input.idOfReplyTo`
- `input.channelMode`
- `input.idReactTo`
- `input.wppContacts`

Para identificar o remetente de um e-mail, utilize `input.sender`.

## Métodos auxiliares

### `input.hasMedia()`

Indica se os campos genéricos de mídia ou localização estão preenchidos.

```
if (input != null && input.hasMedia()) {
  dialog.set('possuiMidiaGenerica', true);
}
```

No e-mail, não use esse método como único teste para identificar anexos. Os arquivos recebidos devem ser verificados em `input.attachments`.

### `input.getMediaType()` e `input.getMediaId()`

Esses métodos calculam informações a partir dos campos genéricos de mídia.

Para anexos de e-mail, prefira percorrer `input.attachments` e acessar `mediaUrl`, `name`, `contentType` e `size`.

## Utilização dos dados da mensagem

### Ler o texto da mensagem

Use `input.text` quando precisar da representação textual consumida pelo motor. Quando for necessário preservar o conteúdo do e-mail, utilize `input.bodyPlain`, `input.bodyHtml` ou `input.html`.

```
var texto = '';

if (input != null) {
  texto = input.bodyPlain || input.text || '';
}

if (texto.trim() == '') {
  dialog.set('emailSemTexto', true);
} else {
  dialog.set('textoEmail', texto);
}
```

Não use `JSON.parse(input.text)` sem confirmar que o conteúdo realmente está em JSON.

### Ler e classificar o assunto

```
var assunto = input != null && input.subject != null
  ? String(input.subject).trim()
  : '';

dialog.set('assuntoEmail', assunto);

if (utils.contains(assunto.toLowerCase(), 'urgente')) {
  dialog.setTicketPriority('alta');
  dialog.go('node-urgente');
} else {
  dialog.go('node-triagem');
}
```

Também é possível utilizar `utils.inputMatches`, `utils.contains`, `utils.startsWith` e `utils.endsWith` para comparar `input.subject` ou `input.text`.

### Guardar dados na sessão

Quando um dado precisar ser utilizado em outra etapa, salve-o na sessão.

```
if (input != null) {
  dialog.set('emailRemetente', input.sender);
  dialog.set('emailDestino', input.to);
  dialog.set('emailAssunto', input.subject);
  dialog.set('emailProtocolo', input.referenceProtocol);
  dialog.set('emailRecebidoEm', input.timestamp);
}
```

Depois, os valores podem ser recuperados com `dialog.get(...)` ou `variables.get(...)`, conforme a convenção adotada pelo fluxo.

### Responder ao remetente

Para enviar uma resposta diretamente ao remetente, utilize `input.sender` no parâmetro de destinatário.

```
if (input != null && input.sender != null && input.sender.trim() != '') {
  var vars = {
    protocolo: input.referenceProtocol,
    assunto: input.subject
  };

  dialog.sendEmail(
    input.domain,
    input.sender,
    'Recebemos sua mensagem',
    'recebimento-email',
    vars
  );
}
```

### Responder usando HTML

```
var nome = variables.get('nomeCliente') || 'cliente';

var html = '<p>Olá, ' + nome + '.</p>' +
           '<p>Recebemos sua solicitação sobre: ' +
           (input.subject || 'assunto não informado') + '.</p>';

dialog.sendEmail(
  input.domain,
  input.sender,
  'Solicitação recebida',
  html
);
```

Trate e valide valores controlados pelo usuário antes de inseri-los em HTML gerado pelo fluxo.

### Ler anexos

Percorra `input.attachments` para obter nome, URL e outras informações dos arquivos recebidos.

```
var urls = [];
var nomes = [];

if (input != null && input.attachments != null) {
  for (var i = 0; i < input.attachments.size(); i++) {
    var anexo = input.attachments.get(i);

    if (anexo != null) {
      nomes.push(anexo.name);

      if (anexo.mediaUrl != null && anexo.mediaUrl.trim() != '') {
        urls.push(anexo.mediaUrl);
      }
    }
  }
}

dialog.set('nomesAnexos', nomes);
dialog.set('quantidadeAnexos', urls.length);
```

### Reenviar anexos em um e-mail

Quando o serviço aceitar URLs de arquivos como anexos, elas podem ser utilizadas no envio de e-mail.

```
var anexos = [];

if (input.attachments != null) {
  for (var i = 0; i < input.attachments.size(); i++) {
    var mediaUrl = input.attachments.get(i).mediaUrl;

    if (mediaUrl != null && mediaUrl.trim() != '') {
      anexos.push(mediaUrl);
    }
  }
}

if (anexos.length > 0 && input.sender != null) {
  var vars = { protocolo: input.referenceProtocol };

  dialog.sendEmail(
    input.domain,
    input.sender,
    'Documentos do atendimento',
    'documentos-atendimento',
    vars,
    anexos
  );
}
```

Não confunda `mediaUrl` com um identificador interno de mídia. Os comandos utilizam contratos diferentes para URLs e IDs de mídia.

### Enviar dados para uma integração

Use `dialog.webhook(...)` quando não for necessário aguardar uma resposta. Quando o retorno for necessário, utilize `dialog.rest(...)` ou `dialog.oauthRest(...)`.

```
var payload = JSON.stringify({
  id: input.id,
  sessionId: input.sessionId,
  sender: input.sender,
  recipient: input.recipient,
  subject: input.subject,
  text: input.bodyPlain || input.text,
  protocol: input.referenceProtocol
});

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

Não envie automaticamente conteúdo sensível, corpo HTML ou URLs de anexos para serviços externos sem avaliar a exposição dos dados.

### Usar conteúdo do e-mail em análises

Os campos textuais do e-mail podem ser utilizados em comandos de classificação ou análise.

```
var texto = input.bodyPlain || input.text || '';

dialog.intentClassification(
  texto,
  ['cobranca', 'suporte', 'cancelamento', 'elogio']
);
```

Conforme a integração utilizada, também podem ser aplicados comandos como `dialog.sentimentAnalysis(...)`, `dialog.namedEntities(...)`, `dialog.chatCompletion(...)` e `dialog.sendToAssistantV2(...)`.

## Dados disponíveis após operações externas

Depois de executar `dialog.rest(...)`, `dialog.oauthRest(...)` ou outra operação assíncrona, o `input` recebido em `onExternal` representa o retorno da operação, e não necessariamente a mensagem de e-mail original.

### Retorno de uma requisição REST

Os principais campos disponíveis são:

- `input.body` — corpo da resposta;
- `input.statusCode` — código HTTP;
- `input.token` — token utilizado em fluxo OAuth, quando aplicável;
- `input.channel`, `input.sessionId` e `input.dialogId` — contexto do atendimento.

Exemplo:

```
var status = input.statusCode;
var corpo = input.body;

if (status >= 200 && status < 300) {
  dialog.set('retornoConsulta', corpo);
  dialog.go('node-consulta-ok');
} else {
  dialog.set('erroConsulta', corpo);
  dialog.go('node-consulta-erro');
}
```

### Preservar o remetente antes de uma chamada externa

Quando o callback externo precisar do remetente do e-mail, salve o valor antes da chamada.

```
dialog.set('emailRemetente', input.sender);

dialog.rest(
  {'Content-Type': 'application/json'},
  'https://api.example.com/consulta',
  'POST',
  JSON.stringify({
    email: input.sender,
    texto: input.bodyPlain || input.text
  })
);
```

No `onExternal`, utilize `dialog.get('emailRemetente')` em vez de depender de `input.sender`.

### `input.payload`

`input.payload` não faz parte da mensagem de e-mail recebida. Esse campo pertence a alguns tipos de entrada externa.

Em callbacks externos, confirme o tipo real da entrada antes de utilizar `payload`, `response` ou `body`.

## Campos que não devem ser presumidos no E-mail

- `input.author` pode ser `null`.
- `input.contactId` deve ser tratado como opcional.
- `input.file`, `input.image`, `input.audio`, `input.video`, `input.latitude` e `input.longitude` não representam os anexos do e-mail.
- `input.payload` não pertence ao contexto normal do e-mail.
- `input.response` pertence a tipos de entrada externa.
- `input` pode ser `null` em execuções programáticas, timeout, erro, inatividade e algumas entradas de `onEnter`.
- Alterar propriedades de `input` não é uma forma de persistir dados na sessão. Para isso, use `dialog.set(...)`.

## Exemplo completo de triagem de e-mail

```
if (input == null || String(input.channel) != 'EMAIL') {
  dialog.set('erroContexto', 'Este nó exige entrada do canal E-mail');
  dialog.go('node-erro-contexto');
} else {
  var texto = input.bodyPlain || input.text || '';
  var assunto = input.subject || '';
  var remetente = input.sender || '';

  if (remetente.trim() == '') {
    dialog.set('erroEmail', 'Remetente ausente');
    dialog.go('node-erro-email');
  } else {
    dialog.set('emailRemetente', remetente);
    dialog.set('emailAssunto', assunto);
    dialog.set('emailTexto', texto);
    dialog.set('emailProtocolo', input.referenceProtocol);

    if (utils.contains((assunto + ' ' + texto).toLowerCase(), 'cancelar')) {
      dialog.go('node-cancelamento');
    } else {
      dialog.go('node-triagem');
    }
  }
}
```

## Resumo dos principais usos de `input.*`

| Objetivo | Comandos e funções |
| --- | --- |
| Ler, comparar e direcionar o fluxo | `utils.inputMatches`, `utils.insensitiveInputMatches`, `utils.inputDistance`, `utils.equals`, `utils.contains`, `utils.startsWith`, `utils.endsWith`, `dialog.go`, `dialog.redirect`, `dialog.changeFlow`, `dialog.runOnEnter` |
| Persistir dados | `dialog.set`, `dialog.updateVariable`, `dialog.visible`, `dialog.updateGlobalVariable` |
| Responder | `dialog.say`, `dialog.sendEmail`, `dialog.sendChatHistoryEmail` |
| Encaminhar para atendimento humano | `dialog.toHuman`, `dialog.setOnBotReturn`, `dialog.setTicketPriority`, `dialog.setTicketSLA`, `dialog.setTicketLabel` |
| Chamar integrações | `dialog.webhook`, `dialog.rest`, `dialog.oauthRest` |
| Classificar e analisar conteúdo | `dialog.intentClassification`, `dialog.sentimentAnalysis`, `dialog.namedEntities`, `dialog.chatCompletion`, `dialog.sendToAssistant`, `dialog.sendToAssistantV2` |
| Analisar anexo por URL | `dialog.imageAnalysisByUrl`, quando a URL do anexo estiver acessível pelo provedor |
| Organizar sessão e atendimento | `dialog.setSessionOption`, `dialog.setSessionProperty`, `dialog.addTag`, `dialog.removeTag`, `dialog.setTags`, `dialog.assess` |
| Registrar eventos ou iniciar fluxos derivados | `dialog.emit`, `dialog.emitSignal`, `dialog.createSubProcess`, `dialog.createCustomerForm` |

A tabela apresenta usos práticos. Um valor de `input.*` também pode ser utilizado em concatenações, objetos, arrays, condicionais e argumentos de outros comandos, desde que o tipo esperado seja respeitado.

## Boas práticas

- Verifique se `input` existe antes de acessar suas propriedades.
- Salve na sessão os dados que serão necessários depois da mensagem original.
- Para responder ao remetente, prefira `input.sender`.
- Para e-mails com anexos, percorra `input.attachments` em vez de utilizar os campos genéricos de mídia.
- Em operações externas, não dependa do `input` original; preserve previamente os dados necessários.
- Ao utilizar conteúdo recebido do cliente em HTML ou integrações externas, trate os dados de acordo com as regras de segurança e exposição de informações adotadas pelo fluxo.

## Limitações

- A disponibilidade e o preenchimento de alguns campos dependem do evento que disparou a caixa de código.
- `input` pode estar vazio em execuções que não tenham uma mensagem recebida como origem.
- Depois de uma operação externa, os dados da mensagem original precisam estar salvos na sessão caso sejam necessários novamente.
- Os anexos de e-mail são representados por `input.attachments`; os campos genéricos de mídia não devem ser utilizados como substituição.