Scripts de ação do Virtual Agent

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 11 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);

    Script de ação do remetente (desativado no Quebec, verifique o subfluxo do remetente)

    O script de ação do remetente sabe como enviar uma mensagem ao provedor. O script deve invocar de forma assíncrona um subfluxo Workflow Studio ou Integration Hub. O Virtual Agent está liberado para continuar processando mensagens em vez de tentar enviar solicitações externas.

    Tabela 3. Entrada de script de ação do remetente
    Entrada Saída
    • Resultados (JSON) - Matriz de mensagens a serem enviadas.
    • Carga (JSON) - Última carga recebida de um solicitante.
    • app_inbound_id (Cadeia de caracteres) - Identificador do remetente, como o número de telefone "De" em um caso de SMS.
    • channel_user_id (Cadeia de caracteres) - Identificador do destinatário, como o número de telefone "Para" em um caso de SMS.
    		 Nenhum

    Exemplo: script de ação do remetente.

    (function execute(inputs, outputs) {
    var results = inputs.results;
    // transform the inputs to something this custom subflow knows about
    var sendInputs = {
        app_inbound_id : inputs["app_inbound_id"],
        channel_user_id: inputs["channel_user_id"],
        messages: JSON.stringify(results)
    };

    // invoke an asynchronous subflow which will send the external request. so this sender script will immediately return,
    // freeing up the chat server thread to do further message processing while putting the external request work on the
    // Workflow Studio/Integration Hub
    sn_fd.FlowAPI.startSubflowQuick('sn_va_sms_twilio.va_sms_twilio_adapter_send_sms', sendInputs);
})(inputs, outputs);

    Script de subfluxo do remetente

    O script de subfluxo do remetente sabe como enviar uma mensagem ao provedor. O script deve invocar de forma assíncrona um subfluxo Workflow Studio ou Integration Hub. 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.

    }else{
  outputs.sendmessage = true;
  messages = inputs.results.results;
  outputs.from = from;
  outputs.to = to;
  outputs.messages = getMessages(messages);
}

    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 4. 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 5. 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 6. 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 7. 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 8. 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);