Scripts de ação do Virtual Agent

  • Versão de lançamento: Yokohama
  • Atualizado 3 de mar. de 2025
  • 10 min. de leitura

    • Você precisa gravar um conjunto de scripts de ação e subfluxo obrigatórios Workflow Studio para passar os dados do usuário para o VACS, aplicar transformações e enviar a resposta de volta para o endpoint da interface de bate-papo.

    Provedor e scripts de entrada/saída

    Um provedor, como a Twilio, fornece o recurso de bate-papo. Os scripts de ação do usuário executam ações do provedor, bem como a configuração de integração de bate-papo personalizada de conversação para ações de transformador de entrada e de saída para o chatbot ou para conversas personalizadas. São fornecidos exemplos de cada um dos scripts. Eles incluem descrições do que cada script faz, bem como a ação de entrada e a ação de saída. Também são exibidos exemplos do script JSON.

    Use Workflow Studio para criar esses scripts para transformar mensagens do servidor e do cliente. O provedor, o remetente e os scripts do transformador de entrada/saída são necessários. Você pode usar os scripts adicionais para acrescentar funcionalidade ao bate-papo.

    Tabela 1. Scripts
    Nome do script Finalidade Obrigatório (S/N)
    Atributo do provedor Contém um token de autenticação do provedor, um identificador do usuário, uma entrada do usuário e variáveis de contexto. S
    Ação do remetente

    Agrupa a solicitação e envia uma resposta de forma assíncrona por meio de Workflow Studio ou do Hub de integração.

    		 S
    Processador de resposta Executa ações da plataforma, como um status de mensagem de atualização, baseadas em uma resposta recebida para uma mensagem de saída.​ N
    Ação contextual Oferece suporte a ações contextuais. N
    Ação vincular à conta Fornece um retorno de chamada relacionado ao sucesso ou ao insucesso da vinculação da conta. N
    Transformador de saída Transforma o controle compatível de um servidor de bate-papo em renderização específica da interface de bate-papo. S
    Transformador de entrada Opcional. Você pode usar os controles avançados padrão se eles se aplicarem ao seu provedor de bate-papo. Você não precisa fornecer uma transformação de entrada separada para cada controle de entrada. Se um comportamento padrão não funcionar, é possível substituir o padrão pela sua própria transformação de entrada para um controle de servidor do Virtual Agent específico. S

    Script de ação de atributos do provedor.

    O script de ação de atributos do provedor extrai dados da mensagem de entrada. O script conhece o protocolo da integração de bate-papo personalizada de conversação e gera o conteúdo da mensagem de entrada, o ID do usuário do remetente e um token de autenticação opcional.
    Nota:
    Se o script de ação de atributos do provedor tiver uma ação contextual, o script deverá ter tanto request_context.contextual_action quanto request_context.typed_value para que a entrada do usuário (que corresponde a uma ação contextual) seja incluída na transcrição. Se você não definir request_context.typed_value, o conteúdo da mensagem não será exibido na transcrição.
    Tabela 2. Entrada/saída de script de ação de atributos do provedor
    Entrada Saída
    • Cabeçalhos (JSON) - Cabeçalhos da solicitação
    • Carga (JSON) - Corpo da solicitação​
    • Token (Cadeia de caracteres) - Token de autenticação.
    • provider_user_id (Cadeia de caracteres) - Nome do remetente, por exemplo, um nome de usuário em uma mensagem do Slack.
    • request_context (JSON) - Conteúdo real recebido.
      • typed_value - Conteúdo digitado, como uma resposta a uma pergunta, por exemplo.
      • attachment_value.url - URL do anexo.
      • attachment_value.content_type - Tipo de conteúdo do anexo.
      • attachment_value.name - Nome de arquivo do anexo.
      • Ação contextual - Ação a ser executada, como END_CONVERSATION, START_CONVERSATION, AGENT, por exemplo. Este script analisa a mensagem de entrada. Se houver uma palavra-chave reconhecida, uma das ações poderá ser definida, como outputs.request_context.contextual_action = "END_CONVERSATION" ;. A estrutura reconhece essa palavra-chave e invoca o script de ação contextual.
      • context_vars - Variáveis contextuais a serem passadas para uma conversa, como `outputs.request_context.context_vars = {language:" en "};`.
    Figura 1. Exemplo: entrada de script de ação de atributos do provedor Workflow Studio, incluindo cabeçalhos e carga.
    Uma entrada de ação em Workflow Studio com cabeçalhos e carga definidos para usar JSON.
    Figura 2. Exemplo: saída do script de ação de atributos do provedor Workflow Studio, incluindo token, request_context e provider_user_id
    Uma saída de ação em Workflow Studio especifica os valores de token, request_context e provider_user_id.

    Exemplo: script de ação de atributos do provedor.

    (function execute(inputs, outputs) {
    var headers = (inputs.headers);
    var payload = (inputs.payload);

    // check if an authentication token was included. this is optional.
    var smsUtil = new VASMSTwilioUtil();
    outputs.token = JSON.stringify(smsUtil.getToken(headers, payload));

    var data = payload.data;
    var request_context = {}; 
    // inspect the actual message. it could be an MMS (attachment) or raw text
    if (data['MediaUrl0']) {
        var attachment_value = {};
        attachment_value.url = data['MediaUrl0'];
        attachment_value.content_type = data['MediaContentType0'];
        attachment_value.name = smsUtil.getFileName(attachment_value.url , attachment_value.content_type);
        request_context.attachment_value = attachment_value;
    } else {
       request_context.typed_value = data['Body'];
    }

    // set the mandatory outputs
    outputs.request_context = request_context;
    outputs.provider_user_id = data.From;
})(inputs, outputs);

    Subfluxo do remetente

    Em vez de um script, o subfluxo do remetente lida com o processo de envio de uma mensagem para um provedor. A mensagem está contida em uma cadeia de caracteres payload como parte do subfluxo. O remetente tem um service_url e origin_service_url, enquanto o URL de saída varia de acordo com o provedor. Por exemplo, uma mensagem enviada por meio do MS Teams usa o valor tenant_id. Quando o Virtual Agent envia a mensagem que contém opções, o destinatário seleciona uma opção. O subfluxo atualiza a exibição da mensagem com base em sua escolha e remove as opções. A conversa continua com base na opção selecionada pelo usuário. O Virtual Agent está liberado para continuar processando mensagens em vez de tentar enviar solicitações externas. Ao criar um subfluxo, não há uma chamada de ação dentro do subfluxo. Para obter mais informações sobre subfluxos, consulte .

    Script de ação contextual

    O script de ação contextual executa ações especiais de palavra-chave, como digitar agente estando em um tópico Virtual Agent para ser imediatamente entregue a um agente dinâmico.

    Tabela 3. Entrada de script de ação contextual
    Entrada Saída
    • conversation_id (Cadeia de caracteres) - O ID da conversa.
    • request_context (JSON) - Solicitação aprovada pelo script de atributo do provedor que contém a ação a ser executada, como (END_CONVERSATION, START_CONVERSATION, AGENT).
    		 Nenhum

    Exemplo: script de ação contextual.

    (function execute(inputs, outputs) {
  var contextual_action = inputs.request_context.contextual_action;
  if (contextual_action === "END_CONVERSATION") {
    sn_cs.VASystemObject.endConversation(inputs.conversation_id);
  } else if (contextual_action === "AGENT") {
    sn_cs.VASystemObject.switchToLiveAgent(inputs.conversation_id);
  } else if (contextual_action === "START_CONVERSATION") {
    sn_cs.VASystemObject.startConversation(inputs.conversation_id);
  }
})(inputs, outputs);

    Script de ação vincular à conta

    O script de ação vincular à conta contém identificadores para o usuário que está fazendo a vinculação. O script também contém a conta à qual está vinculado.

    Tabela 4. Entrada de script de ação vincular à conta
    Entrada Saída
    • provider_user_id (Cadeia de caracteres) - Identificador do usuário que está fazendo a vinculação, como um número de telefone em um caso de SMS.
    • status (Cadeia de caracteres) - Sucesso/falha.
    • user_id (Cadeia de caracteres) - user_sys_id da ServiceNow para a conta à qual foi vinculada.
    		 Nenhum

    Exemplo: script de ação vincular à conta.

    (function execute(inputs, outputs) {
  
  var richControl = (inputs.rich_control);
  var value = richControl.value;
  outputs.result = richControl.header + ': ' + value.action;
  
})(inputs, outputs);

    Script de ação do processador de resposta

    O script de ação do processador de resposta executa ações especializadas baseadas na resposta a uma solicitação de envio de mensagem. A estrutura já faz o rastreamento básico de status de mensagens.

    Tabela 5. Entrada de script de ação da conta do processador de resposta.
    Entrada Saída
    • message_id (Cadeia de caracteres) - Identificador do registro sys_cs_message associado a essa resposta.
    • cabeçalhos (JSON) - Cabeçalhos recebidos.
    • corpo (Cadeia de caracteres) - Corpo recebido.
    • código de status (Número inteiro) - O código de status HTTP recebido.
    		 Nenhum

    Exemplo: script de ação do processador de resposta.

    (function execute(inputs, outputs) {
    gs.debug("Response from provider: message_id = " + inputs.message_id + ", status_code = " +
      inputs.status_code + ", headers = " + JSON.stringify(inputs.headers) + ", body = " + inputs.body);
})(inputs, outputs);

    Scripts do transformador de saída

    Os scripts do transformador de saída convertem as mensagens Virtual Agent de saída em um protocolo relacionado à integração do bate-papo personalizada de conversação.

    Entrada.

    • rich_controls (JSON): componente de controle avançado do servidor do Virtual Agent que será transformado.
    • carga (JSON): última resposta recebida de um solicitante.

    Saída.

    resultado (cadeia de caracteres) - Mensagem do componente apropriado ao provedor a ser enviada.

    Tabela 6. Exemplos: scripts do transformador de saída
    Nome do transformador de saída Exemplo de script.
    Virtual Agent - Transformador de saída de texto padrão do adaptador da Twilio para SMS 
    (function execute(inputs, outputs) {
  var rich_control = inputs.rich_control;
  outputs.result = rich_control['label'];
})(inputs, outputs);
    Virtual Agent - Transformador de saída do link padrão do adaptador da Twilio para SMS 
    (function execute(inputs, outputs) {
  var richControl = (inputs.rich_control);
  var value = richControl.value;
  outputs.result = richControl.header + ': ' + value.action;
})(inputs, outputs);
    Virtual Agent - Transformador de saída do seletor padrão do adaptador da Twilio para SMS 
    (function execute(inputs, outputs) {
  var rich_control = inputs.rich_control;
  var options = rich_control['options'];
  if (options && options.length > 0) {
      var optionsLength = options.length;
      var picker = rich_control['label'] || "";
      for (var x = 0; x < optionsLength; x++) {
          picker += "\n" + (x+1) +  ": " + options[x].label;
      }
  }
  outputs.text_message = picker;
})(inputs, outputs);
    Virtual Agent - Transformador de saída de multilink padrão do adaptador da Twilio para SMS 
    (function execute(inputs, outputs) {
  var rich_control = inputs.rich_control;
  var linkResult = rich_control['header'];
  var totalValues = rich_control['values'].length;
  for (var i = 0; i < totalValues; i++) {
    linkResult = linkResult + '\n';
    var linkValue = rich_control['values'][i];
    linkResult = linkResult + '\n' + linkValue['description'] + ': ' + linkValue['action'];
  }
  outputs.result  = linkResult;
})(inputs, outputs);
    Virtual Agent - Transformador de saída do cartão padrão do adaptador da Twilio para SMS. 
    (function execute(inputs, outputs) {
  var richControl = (inputs.rich_control);
  var data = JSON.parse(richControl.data);    
  var tableTitle = data.title;
  var fields = data.fields;
  var subtitle = data.subtitle;
  var url = data.url;    
  var message = subtitle ? getCardLine(tableTitle, subtitle) : tableTitle + "\n";
  for (var i= 0; i<fields.length; i++) {
     message += getCardLine(fields[i].fieldLabel, fields[i].fieldValue);
  }
  message += url;
  outputs.result = message;

  function getCardLine(key, value) {
      if (value == '' || value == null || key == '' || key == null)
          return;
      return key + ": " + value + "\n";
  }
})(inputs, outputs);

    Scripts do transformador de entrada

    Os scripts do transformador de entrada convertem as mensagens de integração de bate-papo padronizadas de conversação em um protocolo que é reconhecido por Virtual Agent. Ele determina o valor obrigatório a ser injetado ao controle avançado que é apresentado ao usuário.

    Entrada.

    • request_context (JSON) - A solicitação aprovada pelo script de Atributo do provedor.
    • rich_control (JSON) - O último controle avançado enviado ao solicitante que contém a "pergunta" original.

    Saída.

    resultado (JSON) - O resultado esperado pelo servidor Virtual Agent. Se o solicitante estiver respondendo a um seletor de tópico, será o sys_id do tópico. Se o solicitante estiver respondendo a um texto de entrada, será a resposta em texto.
    • valor - sys_id ou valor de texto.
    • search_text - Texto usado se o solicitante selecionar algo inesperado. Por exemplo, um usuário digitou algo com o qual o NLU pode ajudar, como "Nenhuma dessas opções corresponde ao que quero" em resposta a um componente de seletor de tópico.
    Tabela 7. Exemplos: scripts do transformador de entrada
    Nome do transformador de entrada Exemplo de script
    Virtual Agent - Transformador de entrada de texto padrão do adaptador da Twilio para SMS.

    Finalidade: encontrar a resposta em texto para a pergunta InputText apresentada

    		 
    (function execute(inputs, outputs) {
  var requestContext = inputs.request_context;
  var richControl = inputs.rich_control;
  var typedValue = requestContext['typed_value'];
  var attachmentValue = requestContext['attachment_value'];
  var smsUtil = new VASMSTwilioUtil();
  var result = {};
  if(richControl['itemType'] == 'image' || richControl['itemType'] == 'file')	{
    if (attachmentValue && attachmentValue.content_type.includes('image')) {
      result.url = attachmentValue.url;
      result.content_type = attachmentValue.content_type;
      result.name = attachmentValue.name;
      result.headers = attachmentValue.headers;
    } else if (typedValue) {
      result.url = typedValue;
      var contentType = smsUtil.getContentType(typedValue);
      if (typeof contentType === 'undefined')
        gs.error('Please enter a valid image link. Inbound image link: {0}', typedValue);
      else
        result.content_type = contentType;
    } else {
      gs.error('Please upload an image or enter a valid image link.');
    }
  }
  result['value'] = typedValue;
  result['search_text'] = '';
  outputs.result = result;
})(inputs, outputs);
    Virtual Agent - Transformador de entrada do seletor padrão do adaptador do Twilio para SMS

    Objetivo: encontrar o sys_id da opção selecionada pelo usuário para essa pergunta do seletor. Esse script usa o mesmo algoritmo do transformador de saída. Se nenhuma opção estiver selecionada e o usuário tiver digitado algo, "search_text" será definido e alimentado no NLU, se estiver habilitado nesta instância.

    		 
    (function execute(inputs, outputs) {
  var request_context = inputs.request_context;
  var rich_control = inputs.rich_control;
  var selectedValue = request_context["typed_value"];
  var result = {};
  result["value"] = "";
  result["search_text"] = "";
  if (rich_control['options']) {
    var options = rich_control['options'];
    var optionsLength = options.length;
    selectedValue === Number(selectedValue)
    if (selectedValue > 0 && selectedValue <= optionsLength) {
        var selectedOption = options[selectedValue - 1];
        result["value"] = selectedOption.value;
    } else {
        result["search_text"] = request_context["typed_value"];
    }
  }
  outputs.result = result;
})(inputs, outputs);