---
sourceDocument: Interfaces conversacionais do Xanadu
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/xanadu/conversational-interfaces

 Release :

    - xanadu

ft:locale :

    - pt-BR

ft:publication_title :

    - Interfaces conversacionais do Xanadu

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# Scripts de ação do Virtual Agent

# Scripts de ação do Virtual Agent {#ariaid-title1}

* Versão de lançamento: Xanadu
* 
* Atualizado 1 de ago. de 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 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 {#va-action-scripts__section_c5w_qcb_xlb}

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.  
{#va-action-scripts__table_qnf_xdb_xlb__entry__3}

| 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 |
[Tabela 1. Scripts]

{#va-action-scripts__table_qnf_xdb_xlb}

## Script de ação de atributos do provedor. {#va-action-scripts__section_jqc_y2b_xlb}

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.
{#va-action-scripts__table_dtk_5fb_xlb__entry__2}

| Entrada | Saída |
|-|-|
| * Cabeçalhos (JSON) - Cabeçalhos da solicitação * Carga (JSON) - Corpo da solicitação {#va-action-scripts__ul_gkf_dgb_xlb} | * 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 "};\`. {#va-action-scripts__ul_sqy_pgb_xlb} {#va-action-scripts__ul_rgm_hgb_xlb} |
[Tabela 2. Entrada/saída de script de ação de atributos do provedor]

{#va-action-scripts__table_dtk_5fb_xlb}  
Figura 1. Exemplo: entrada de script de ação de atributos do provedor Workflow Studio, incluindo cabeçalhos e carga.  
Figura 2. Exemplo: saída do script de ação de atributos do provedor Workflow Studio, incluindo 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) {#va-action-scripts__section_vwt_ljb_xlb}

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.
{#va-action-scripts__table_tb3_qjb_xlb__entry__2}

| 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. {#va-action-scripts__ul_dj3_5jb_xlb} | Nenhum |
[Tabela 3. Entrada de script de ação do remetente]

{#va-action-scripts__table_tb3_qjb_xlb}

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 {#va-action-scripts__section_y2f_3m4_h4b}

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 {#va-action-scripts__section_avl_hkb_xlb}

O script de ação contextual executa ações especiais de palavra-chave, como digitar <kbd class="ph userinput">agente</kbd> estando em um tópico Virtual Agent para ser imediatamente entregue a um agente dinâmico.
{#va-action-scripts__table_bvl_hkb_xlb__entry__2}

| 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). {#va-action-scripts__ul_cvl_hkb_xlb} | Nenhum |
[Tabela 4. Entrada de script de ação contextual]

{#va-action-scripts__table_bvl_hkb_xlb}

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 {#va-action-scripts__section_mvv_skb_xlb}

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.
{#va-action-scripts__table_nvv_skb_xlb__entry__2}

| 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. {#va-action-scripts__ul_ovv_skb_xlb} | Nenhum |
[Tabela 5. Entrada de script de ação vincular à conta]

{#va-action-scripts__table_nvv_skb_xlb}

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 {#va-action-scripts__section_lwm_dlb_xlb}

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.
{#va-action-scripts__table_mwm_dlb_xlb__entry__2}

| 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. {#va-action-scripts__ul_nwm_dlb_xlb} | Nenhum |
[Tabela 6. Entrada de script de ação da conta do processador de resposta.]

{#va-action-scripts__table_mwm_dlb_xlb}

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 {#va-action-scripts__section_sjb_qlb_xlb}

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.
{#va-action-scripts__ul_n1m_y24_xlb}

Saída.

resultado (cadeia de caracteres) - Mensagem do componente apropriado ao provedor a ser enviada.
{#va-action-scripts__table_tjb_qlb_xlb__entry__2}

| 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); |
[Tabela 7. Exemplos: scripts do transformador de saída]

{#va-action-scripts__table_tjb_qlb_xlb}

## Scripts do transformador de entrada {#va-action-scripts__section_j2g_cmb_xlb}

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.
{#va-action-scripts__ul_whj_yf4_xlb}

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.
{#va-action-scripts__ul_dz1_bg4_xlb}
{#va-action-scripts__table_k2g_cmb_xlb__entry__2}

| 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); |
[Tabela 8. Exemplos: scripts do transformador de entrada]

{#va-action-scripts__table_k2g_cmb_xlb}