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

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.

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:

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

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:

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

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.