---
sourceDocument: Interfaces conversacionais de Yokohama
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/yokohama/conversational-interfaces

 Release :

    - yokohama

ft:locale :

    - pt-BR

ft:publication_title :

    - Interfaces conversacionais de Yokohama

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# Virtual Agent scripts de ação

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

* Versão de lançamento: Yokohama
* 
* Atualizado 3 de mar. de 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 10 min. de leitura

Você precisa escrever um conjunto de obrigatórios Workflow StudioScripts de ação e subfluxo 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.

## Scripts de entrada/saída e do provedor {#va-action-scripts__section_c5w_qcb_xlb}

Um provedor, como Twilio, fornece a capacidade 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 personalizado conversacional para ações de transformador de entrada e saída para seu chatbot ou conversas personalizadas. São fornecidos exemplos de cada script. Eles incluem uma descrição do que cada script faz, bem como a entrada de ação e a saída de ação. Você também vê exemplos do script json.

Você usa Workflow Studiopara criar esses scripts para transformar mensagens de servidor e 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 adicionar mais funcionalidade ao bate-papo.  
{#va-action-scripts__table_qnf_xdb_xlb__entry__3}

| Nome do script | Finalidade | Necessário (S/N) |
|-|-|-|
| Atributo do provedor | Contém um token de autenticação do provedor, um identificador de usuário, entrada de usuário e variáveis de contexto. | Y |
| Ação do remetente | Empacota a solicitação e envia uma resposta assíncrona via Workflow StudioOu Hub de integração. | Y |
| Processador de resposta | Executa ações da plataforma, como atualizar o status da mensagem, com base 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 sobre se a vinculação da conta foi bem-sucedida ou não​. | 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. | Y |
| 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, você poderá substituir o padrão por sua própria transformação de entrada para um controle de servidor do Virtual Agent específico. | Y |
[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 de integração de bate-papo personalizado conversacional e gera o conteúdo da mensagem recebida, o ID de 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 deve ter request_context.contextual_action e 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 aparecerá na transcrição.
{#va-action-scripts__table_dtk_5fb_xlb__entry__2}

| Entrada | Saída |
|-|-|
| * Cabeçalhos (JSON) - Cabeçalhos de 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. * Attachment_value.url - URL do anexo. * Attachment_value.content_type - Tipo de conteúdo do anexo. * attachment_value.name - Nome do arquivo do anexo. * Ação contextual - Ação a ser executada, como END_CONVERSATION, START_CONVERSATION, AGENTE. Este script examina 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 esta 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";". {#va-action-scripts__ul_sqy_pgb_xlb} {#va-action-scripts__ul_rgm_hgb_xlb} |
[Tabela 2. Entrada/saída do script de ação de atributos do provedor]

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

## Subfluxo do remetente {#va-action-scripts__section_y2f_3m4_h4b}

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 um payloadcadeia de caracteres como parte do subfluxo. O remetente tem um service_urle. origin_service_url, Enquanto o URL de saída varia dependendo do provedor. Por exemplo, uma mensagem enviada pelo 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. . Virtual Agentestá liberado para continuar processando mensagens em vez de tentar enviar solicitações externas. Ao criar um subfluxo, não há uma ação chamada uma ação no subfluxo. Para obter mais informações sobre subfluxos, consulte .

## Script de ação contextual {#va-action-scripts__section_avl_hkb_xlb}

O script de ação contextual executa ações de palavra-chave especiais, como digitação <kbd class="ph userinput">agente </kbd>dentro de um Virtual Agenttópico para ser imediatamente entregue a um atendente.
{#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 passada do script de atributo do provedor que contém a ação a ser executada, como (END_CONVERSATION, START_CONVERSATION, AGENTE). {#va-action-scripts__ul_cvl_hkb_xlb} | Nenhum(a) |
[Tabela 3. 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);

## Vincular script de ação de conta {#va-action-scripts__section_mvv_skb_xlb}

O script de ação da conta de link contém identificadores para o usuário que está vinculando. 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á vinculando, como um número de telefone em um caso de SMS. * Status (cadeia de caracteres) - sucesso/falha. * User_id (cadeia de caracteres) - ServiceNow user_sys_id da conta à qual foi vinculada. {#va-action-scripts__ul_ovv_skb_xlb} | Nenhum(a) |
[Tabela 4. Vincular entrada de script de ação de conta]

{#va-action-scripts__table_nvv_skb_xlb}

Exemplo: Vincular script de ação de 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 acompanhamento básico do status da mensagem.
{#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 esta resposta. * Cabeçalhos (JSON) - Cabeçalhos recebidos. * Corpo (cadeia de caracteres) - Corpo recebido. * Código de status (inteiro) - O código de status HTTP recebido. {#va-action-scripts__ul_nwm_dlb_xlb} | Nenhum(a) |
[Tabela 5. 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 a saída Virtual Agentmensagens para um protocolo relacionado à integração de bate-papo personalizado conversacional.

Entrada.  
* Rich_control (json) - Virtual Agentcomponente de controle avançado do servidor que deve ser transformado.
* Carga (JSON) - A última resposta recebida de um solicitante.
{#va-action-scripts__ul_n1m_y24_xlb}

Saída.

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

| Nome do transformador de saída | Exemplo de script |
|-|-|
| Virtual Agent - Adaptador SMS Twilio Texto padrão Transformador de saída | (function execute(inputs, outputs) { var rich_control = inputs.rich_control; outputs.result = rich_control['label']; })(inputs, outputs); |
| Virtual Agent - Adaptador SMS Twilio Link padrão Transformador de saída | (function execute(inputs, outputs) { var richControl = (inputs.rich_control); var value = richControl.value; outputs.result = richControl.header + ': ' + value.action; })(inputs, outputs); |
| Virtual Agent - Adaptador SMS Twilio Seletor padrão Transformador de saída | (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 - Adaptador SMS Twilio Padrão Transformador de saída de vários links | (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 - Adaptador SMS Twilio Cartão padrão Transformador de saída | (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 6. Exemplos: Scripts de 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 transformadores de entrada convertem mensagens de integração de bate-papo personalizadas conversacionais recebidas em um protocolo que o. Virtual Agentreconhece. Ele determina o valor necessário a ser injetado no controle avançado que é apresentado ao usuário.

Entrada.  
* Request_context (JSON) - A solicitação passada do 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 Virtual Agentservidor. Se o solicitante estiver respondendo a um seletor de tópico, ele será o sys_id do tópico. Se o solicitante estiver respondendo a um texto de entrada, será a resposta de texto.

* valor - sys_id ou valor de texto.
* Search_text - Texto usado se o solicitante selecionou algo inesperado. Por exemplo, um usuário digitou algo que a NLU poderia ajudar, como "Nenhuma dessas opções corresponde ao que eu quero" em resposta a um componente do seletor de tópicos.
{#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 - Adaptador SMS Twilio Padrão Transformador de entrada de texto Objetivo: Encontrar a resposta de texto para a pergunta inputText feita | (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 - Adaptador SMS Twilio Padrão Transformador de entrada do seletor Objetivo: Localizar o sys_id da opção que o usuário selecionou para esta pergunta do seletor. Este script usa o mesmo algoritmo do transformador de saída. Se nenhuma opção for selecionada e o usuário digitar algo, o "search_text" será definido e alimentado na 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 7. Exemplos: Scripts de transformador de entrada]

{#va-action-scripts__table_k2g_cmb_xlb}