---
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 Virtual Agent

# Scripts 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) 9 min. de leitura

Use os métodos e variáveis de script ServiceNow® Virtual Agent para escrever scripts de bate-papo, como resposta, gatilho e scripts de fluxo. As variáveis também podem fornecer contexto para seus tópicos e conversas de suporte ao vivo.

scripts Virtual Agent podem fornecer contexto para tópicos, como reter informações sobre um usuário ou a entrada de um usuário. Você pode usar essas informações para personalizar uma conversa, por exemplo, para apresentar uma atendimento em script ou uma confirmação. Os scripts também podem especificar determinadas ações que serão realizadas sobre as informações obtidas durante uma conversa. Essas ações podem ser usadas para criar ou atualizar registros ServiceNow.

Os scripts são executados no servidor no escopo em que um tópico está definido. Todas as proteções de escopo se aplicam. Se você estiver desenvolvendo uma conversa para uma aplicação com escopo, será necessário usar a API com escopo. Você pode usar a maioria das APIs executadas em scripts de servidor.

## Entrada do usuário e variáveis de registro ServiceNow {#virtual-agent-scripts__section_ssh_pxw_sdb}

Em Virtual Agent, as seguintes variáveis estão disponíveis para uso em scripts criados para um tópico.  

Variáveis de entrada do usuário

:   Ao adicionar um controle de entrada a um tópico, o sistema cria automaticamente uma variável para armazenar a entrada do usuário (uma cadeia de caracteres, um valor Booliano etc.). A sintaxe é `vaInputs.myvar`, em que `myvar` é o nome que você atribuiu ao nó de entrada.

    Por exemplo, um aviso de entrada de texto com o nome <kbd class="ph userinput">Primeiro aviso</kbd> tem uma variável definida pelo sistema chamada `vaInputs.first_prompt`. Espaços no nome são substituídos por um sublinhado e os caracteres maiúsculos são alterados para minúsculos.

variáveis de registro ServiceNow

:   Se você criar um script para um tópico que consulta uma tabela ServiceNow, o objeto de registro (GlideRecord) retornado ficará disponível automaticamente para uso no tópico. A sintaxe da variável é `vaInputs.myvar`, em que `myvar` é o objeto de registro. Para obter detalhes sobre como consultar tabelas ServiceNow para retornar um objeto de registro, consulte [Consulta de tabelas no script](https://www.servicenow.com/docs/access?context=c_UsingGlideRecordToQueryTables&version=xanadu&pubname=xanadu-api-reference&ft:locale=en-US).

    Use a referência com pontos em variáveis que contêm um registro ServiceNow para especificar um campo específico na tabela. A sintaxe é `vaInputs.myvar.field`. Para obter detalhes sobre referência com pontos em um script, consulte [Exemplos de referência com pontos](https://www.servicenow.com/docs/access?context=dot-walking-examples&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US).

Acesso a entrada do usuário e variáveis de registro ServiceNow

:   Use objetos vaInputs para acessar variáveis de registro ServiceNow em scripts. Por exemplo, o `vaInputs.myvar == "expected value"`. Para acessar valores de entradas do usuário que não são registros, use `vaInputs.myvar.getValue()`.

    Os métodos a seguir estão disponíveis.  
    {#virtual-agent-scripts__table_uht_pzs_cpb__entry__2}

    | Método | Descrição |
    |-|-|
    | vaInputs.myvar == "expected value" | Avalia se `myvar` corresponde a um valor esperado. Nota: Os valores das variáveis de entrada do usuário são atribuídos usando controles de entrada do usuário. Esses valores não podem ser alterados nos seus scripts. * A versão Xanadu oferece suporte a outros tipos de dados. Para obter mais informações, consulte [Tipos de dados de entrada em tópicos Virtual Agent](https://servicenow-prod.fluidtopics.net/uPsxMHHTekvnOXgK_EHFpA "Você pode definir entradas de tipos de dados Glide Virtual Agent (com.glide.cs.chatbot) usados normalmente em Designer do Virtual Agent sem escrever um script. Defina o tipo de dados de entrada no nó inicial de um controle personalizado ou bloco de tópicos."). * Por padrão, a variável do usuário está disponível e é uma referência ao registro sys_user do usuário. {#virtual-agent-scripts__ul_dsz_rbt_cpb} |
    | vaInputs.myvar.getValue(); | Retorna o valor. |
    | vaInputs.myvar.getDisplayValue(); | Retorna o valor de exibição se o valor armazenado não for um registro ServiceNow. Para variáveis que contêm registros ServiceNow, este método retorna o valor de exibição, como definido pelo campo de exibição dessa tabela. O exemplo a seguir mostra o rótulo e os valores de seleção para uma entrada do usuário. Nesse caso, `myVar.getValue()` retornaria um valor de 10, 20 ou 30, enquanto `myVar.getDisplayValue()` retornaria Apple, Orange ou Pear. Figura 1. Exemplo da lista de seleção |
    | vaInputs.myvar.getDefaultValue(); | Retorna o valor padrão em uma mensagem de confirmação. |
    | vaInputs.myvar.getDefaultDisplayValue(); | Retorna o valor de exibição para o valor padrão em uma mensagem de confirmação. |
    | vaInputs.myvar.unbindEntity(); | Remove o valor das variáveis de entrada que o serviço de previsão NLU preencheu com entidades extraídas (desvincula-o do valor de entrada inicial). Por exemplo, se o usuário decidir mudar sua opção em um prompt de confirmação, você poderá desvincular o valor da entidade da variável de entrada. O usuário será avisado novamente quando fizer um loop de volta para o nó de entrada correspondente. Nota: NLU deve estar habilitado no tópico. Em Designer do Virtual Agent, selecione a guia Propriedades para configurar o NLU. Para obter informações sobre como definir entidades NLU, consulte [Entidades](https://www.servicenow.com/docs/access?context=entities&version=xanadu&pubname=xanadu-intelligent-experiences&ft:locale=en-US). |
    [Tabela 1. Métodos vaInputs]

    {#virtual-agent-scripts__table_uht_pzs_cpb}

## Variáveis de script {#virtual-agent-scripts__section_kpv_qxj_12b}

Você pode definir variáveis de script para informações que não estão armazenadas em tabelas ServiceNow, mas que podem ser usadas para compartilhar essas informações em outro lugar em um tópico. As variáveis de script são semelhantes às variáveis do bloco de anotações do fluxo de trabalho que armazenam valores primitivos, como números inteiros, valores boolianos ou cadeias de caracteres. Um valor de cadeia de caracteres pode ser um valor em script estático ou dinâmico. Use a barra lateral de Variáveis para definir variáveis de script para um tópico em Designer do Virtual Agent.  
Figura 2. Barra lateral de variáveis  
Nota:  
As variáveis de script devem ser usadas por autores de tópicos com conhecimento avançado em script.

A sintaxe da variável é `vaVars.myvar`, em que `myvar` é o nome que você atribui à variável. Por exemplo, você pode atribuir um valor à variável usando `vaVars.myvar = value;`. Ao contrário das variáveis de entrada do usuário, as variáveis de script podem ter valores atribuídos em um script.

Para informações sobre como definir uma variável de script em um tópico, consulte [Definir variáveis de script para um tópico](https://servicenow-prod.fluidtopics.net/xg4szln9T5gLJGfnnf83rQ "Use a barra lateral Variáveis para definir variáveis de script para um tópico. As variáveis de script podem armazenar informações que não foram encontradas nas tabelas ServiceNow. Essas informações podem ser compartilhadas em outro lugar em um tópico.").

## Variáveis de contexto {#virtual-agent-scripts__section_mc5_tvw_22b}

As variáveis de contexto funcionam em um escopo global, e as variáveis de sistema funcionam dentro do escopo do tópico. Você pode usar variáveis de contexto em parâmetros do sistema no URL do cliente web. Essas variáveis podem ser usadas em qualquer lugar na conversa usando o objeto `vaContext`. Use essas opções para criar links para Virtual Agent com variáveis predefinidas.

O exemplo de link a seguir contém um parâmetro, `sysparm_city=milan`. Além de abrir uma conversa Virtual Agent, o uso deste link cria uma variável chamada `city` com um valor de `milan`. Esta variável pode ser acessada em um script usando `vaContext.city`.

    https://<instance>.service-now.com/$sn-va-web-client-app.do?sysparm_city=milan

Várias variáveis Atendente estão disponíveis para uso em scripts de tópico. Essas variáveis incluem o seguinte:

* <var class="keyword varname">aplicação</var>
* <var class="keyword varname">idioma</var>
* <var class="keyword varname">portal</var>
* <var class="keyword varname">search_text</var>
* <var class="keyword varname">short_description</var>
{#virtual-agent-scripts__ul_nvm_krg_rwb}

A sintaxe da variável é `vaContext.LiveAgent_myvar`, em que `myvar` é uma das [variáveis de contexto do atendente](https://servicenow-prod.fluidtopics.net/XAQdFgdZ6l4y1cipnVPZig "Use variáveis de contexto de bate-papo para transmitir determinadas informações do tópico para atendentes ou para controlar como as conversas de bot são roteadas para os atendentes. O Virtual Agent inclui algumas variáveis padrão, e você pode definir novas.") disponíveis. Acesse a variável usando `vaContext.LiveAgent_myvar = value;`.

Para usar variáveis de Atendente em scripts de tópico, abra o tópico em Designer do Virtual Agent. Na guia Propriedades, selecione o ícone de lápis ao lado de Variáveis do atendente para adicioná-las ao tópico.

Para informações sobre variáveis de contexto do atendente incluídas com Virtual Agent, consulte [Variáveis de contexto do atendente.](https://servicenow-prod.fluidtopics.net/XAQdFgdZ6l4y1cipnVPZig "Use variáveis de contexto de bate-papo para transmitir determinadas informações do tópico para atendentes ou para controlar como as conversas de bot são roteadas para os atendentes. O Virtual Agent inclui algumas variáveis padrão, e você pode definir novas.").

## Métodos do vaSystem {#virtual-agent-scripts__section_bdc_wtr_h2b}

Você pode usar métodos no objeto vaSystem para fazer várias tarefas. Algumas dessas tarefas incluem o seguinte:

* Anexar imagens a registros.
* Acessar a cadeia de caracteres de pesquisa que foi usada para encontrar o tópico atual.
* Verificar se um atendente está disponível para receber uma conversa.
* Conectar o usuário a um atendente.
{#virtual-agent-scripts__ul_rgh_w31_fpb}  
Nota:  
O uso de métodos de sistema não documentados não é recomendado, pois eles não são compatíveis e podem ser descontinuados ou alterados a qualquer momento sem aviso prévio.
{#virtual-agent-scripts__table_xvn_c5r_h2b__entry__2}

| Método | Descrição |
|-|-|
| vaSystem.applyLinkTemplate(String sysId, String tableName, String actionName) | Cria um link externo específico para um portal. |
| vaSystem.attachRecordToConversation(String tableName, String sysId) | Anexe registros ServiceNow à lista Tarefas relacionadas em um registro de interação do Virtual Agent. Esses registros são atualizados ou criados durante uma conversa Virtual Agent. |
| vaSystem.attachToRecord(String mediaId, String tableName, String sysId) | Anexe uma imagem carregada a um registro ServiceNow. O método usa os seguintes parâmetros: * `mediaId`: o caminho da imagem a ser anexada. Para usar uma imagem inserida pelo cliente, use `getValue()` em uma variável de entrada de imagem. Por exemplo, `vaInputs.image_input.getValue()`. * `tableName`: uma cadeia de caracteres que contém o nome da tabela. * `sys_id`: o sys_id do registro. {#virtual-agent-scripts__ul_dlj_4yr_h2b} |
| vaSystem.connectToAgent() | Conecta o cliente a um atendente. Para mais informações sobre esse método, consulte [Transferir conversas Virtual Agent para um atendente](https://servicenow-prod.fluidtopics.net/iQnOhSkOB0~8qK9QRVLS4w "Gerencie o suporte ao bate-papo ao vivo, incluindo a interface de suporte do bate-papo usada quando uma conversa Virtual Agent é transferida para um atendente."). |
| vaSystem.didConnectToLiveAgent() | Retorna um valor booleano (verdadeiro ou falso) se a conversa atual foi conectada a um atendente. |
| vaSystem.getClosingMessage() | Retorna uma mensagem de encerramento para uma conversa da propriedade do sistema: com.glide.cs.general.closing_message. (A mensagem é diferente para aplicativos de mensagens de terceiros, como Microsoft Teams e Slack). |
| vaSystem.getConversationId() | Retorna o ID da conversa atual. |
| vaSystem.getGreetingMessage() | Retorna a mensagem de saudação a partir da mensagem de IU com a chave "Olá, sou seu Virtual Agent. Conte-me como posso ajudá-lo hoje." |
| vaSystem.getInteractionSysId() | Retorna o ID de interação da conversa atual. |
| vaSystem.getSearchText() | Retorna o último enunciado digitado pelo usuário. |
| vaSystem.getTopicSelectionMessage() | Retorna uma mensagem de IU com a chave "Qual é o seu problema ou solicitação? Ou confira em que posso ajudar". (A mensagem é diferente para aplicativos de mensagens de terceiros, como Microsoft Teams e Slack). Este método é retornado da propriedade do sistema com.glide.cs.topic_picker_msg. |
| vaSystem.getTranscript() | Acessa a transcrição da conversa. |
| vaSystem.isLiveAgentAvailable() | Verifica se um agente ao vivo está disponível para receber uma conversa transferida do bot. Para transferir uma conversa para um atendente, chame este método antes de usar `vaSystem.connectToAgent()`. |
| vaSystem.isLiveAgentConfigured() | Retorna se o bate-papo ao vivo está habilitado. |
| vaSystem.resetAllEntities() | Redefine todas as entidades registradas na conversa. |
| vaSystem.sendBatchedMessages() | Envia imediatamente mensagens da fila. |
| vaSystem.sendSeparatorMessage() | Envia uma linha de mensagem separadora e retorna a mensagem de encerramento de `getClosingMessage()`. |
| vaSystem.sendSystemMessage(String message, Boolean showAvatar) | Envia uma mensagem do sistema e retorna uma mensagem de saudação de `getGreetingMessage()`. |
| vaSystem.sendTopicPickerControl(String topicSelectionMessage, String topicPickerButtonLabel) | Envia o controle do seletor de tópicos com valores associados para a mensagem e o rótulo do botão "Mostrar tudo". |
| vaSystem.switchTopicByName() | Permite que o usuário pule do tópico da conversa atual para o nome do tópico especificado. O botão X está disponível para que o usuário possa encerrar a conversa. Depois que o tópico termina, o usuário reinicia o tópico global. Quando a conversa terminar, o usuário poderá selecionar Clique aqui para iniciar uma nova conversa na parte inferior da janela de bate-papo para reiniciar o tópico. O parâmetro opcional resumeBehavior especifica como o fluxo de conversa é retomado, da seguinte forma: * Se resumeBehavior=resume, Virtual Agent retoma o tópico da chamada. * Se resumeBehavior=skip, Virtual Agent pula o tópico da chamada. {#virtual-agent-scripts__ul_x2k_rxk_gtb} Se resumeBehavior não for especificado, o comportamento padrão da instância será usado. |
| vaSystem.switchTopicById(sysid) | Permite que o usuário pule do tópico da conversa atual para o ID do tópico especificado. O botão X está disponível para que o usuário possa encerrar a conversa. Depois que o tópico termina, o usuário reinicia o tópico global. Quando a conversa terminar, o usuário poderá selecionar Clique aqui para iniciar uma nova conversa na parte inferior da janela de bate-papo para reiniciar o tópico. O parâmetro opcional resumeBehavior especifica como o fluxo de conversa é retomado, da seguinte forma: * Se resumeBehavior=resume, Virtual Agent retoma o tópico da chamada. * Se resumeBehavior=skip, Virtual Agent pula o tópico da chamada. {#virtual-agent-scripts__ul_hwt_21l_gtb} Se resumeBehavior não for especificado, o comportamento padrão da instância será usado. |
| vaSystem.topicDiscovery(String searchTextOverride, Boolean keywordImpl) | Executa a descoberta de tópico com base no termo no parâmetro searchTextOverride. O método usa os seguintes parâmetros: * `searchTextOverride`: uma cadeia de caracteres em que a descoberta de tópico será executada. * `keywordImpl`: um Booliano que determina se palavras-chave devem ser usadas. {#virtual-agent-scripts__ul_rq2_zst_ssb} |
[Tabela 2. Métodos usados em scripts de tópico Virtual Agent]

{#virtual-agent-scripts__table_xvn_c5r_h2b} {#virtual-agent-scripts__table_mqd_wqp_1jb__entry__2}

| Método | Descrição |
|-|-|
| sn_cs.VASystemObject.getTranscriptById(\<conversation sysId\>) | Acessa a transcrição da conversa Virtual Agent atual. |
[Tabela 3. Método que pode ser usado fora de tópicos Virtual Agent]

{#virtual-agent-scripts__table_mqd_wqp_1jb}
**Conceitos relacionados**   

* [Domain Separation e Virtual Agent](https://servicenow-prod.fluidtopics.net/mhf7E~4jc3GZPeh7AQVXLg "Domain Separation é compatível com o aplicativo Virtual Agent. O Domain Separation permite separar dados, processos e tarefas administrativas em agrupamentos lógicos chamados de domínios. Você pode controlar vários aspectos dessa separação, incluindo quais usuários podem ver e acessar os dados.")
* [Registro de interação do Virtual Agent](https://servicenow-prod.fluidtopics.net/rjxD6tMxWvyqfKgnw3u4nQ "Sempre que uma conversa do Virtual Agent ocorre, um registro de interação captura toda a conversa como um tipo de registro de bate-papo na tabela Interações [interaction]. O registro inclui todos os elementos de tópico usados na conversa, bem como as transferências para o atendente.")  
**Referência relacionada**   

* [Tipos de dados de entrada em tópicos Virtual Agent](https://servicenow-prod.fluidtopics.net/uPsxMHHTekvnOXgK_EHFpA "Você pode definir entradas de tipos de dados Glide Virtual Agent (com.glide.cs.chatbot) usados normalmente em Designer do Virtual Agent sem escrever um script. Defina o tipo de dados de entrada no nó inicial de um controle personalizado ou bloco de tópicos.")
* [Entidades do sistema NLU](https://servicenow-prod.fluidtopics.net/1q7QkxPIy_M4s13LkNEf9g "Use entidades NLU definidas globalmente para identificar informações do sistema que Virtual Agent podem extrair da conversa. Você pode definir entidades como variáveis de entrada \"sem nó\" para um tópico. Essas variáveis podem ser preenchidas com base nas previsões do provedor de serviços NLU ou fornecidas fora do escopo do tópico.")
* [Parâmetros de URL Virtual Agent](https://servicenow-prod.fluidtopics.net/FOFNPMRAswUJOiFxOlJCZw "Virtual Agent fornece vários parâmetros do sistema que os administradores podem adicionar a um URL de instância para controlar como o conteúdo da página é renderizado.")
* [Feedback de latência em Virtual Agent](https://servicenow-prod.fluidtopics.net/ON3wnzBqQCP0F9GBmggWsw "A propriedade do sistema com.glide.cs.message.processing.enabled notifica os solicitantes sempre que o grande modelo de linguagem (LLM) de IA generativa estiver processando a solicitação no cliente Web Virtual Agent e no painel Now Assist.")