Scripts Virtual Agent

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

    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 Primeiro aviso 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.

    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.

    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.

    Tabela 1. Métodos vaInputs
    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.
    • Por padrão, a variável do usuário está disponível e é uma referência ao registro sys_user do usuário.
    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
    Os campos de rótulo incluem Maçã, Laranja e Pêra para as opções. Os valores de cada um são 10, 20 e 30.
    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.

    Variáveis de script

    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
    Barra lateral na página Designer do Virtual Agent para adicionar manualmente variáveis de script que são usadas em scripts de tópico.
    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.

    Variáveis de contexto

    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:
    • aplicação
    • idioma
    • portal
    • search_text
    • short_description

    A sintaxe da variável é vaContext.LiveAgent_myvar, em que myvar é uma das variáveis de contexto do atendente 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..

    Métodos do vaSystem

    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.
    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.
    Tabela 2. Métodos usados em scripts de tópico Virtual Agent
    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.
    vaSystem.connectToAgent() Conecta o cliente a um atendente. Para mais informações sobre esse método, consulte Transferir conversas Virtual Agent 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.

    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.

    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.
    Tabela 3. Método que pode ser usado fora de tópicos Virtual Agent
    Método Descrição
    sn_cs.VASystemObject.getTranscriptById(<conversation sysId>)

    Acessa a transcrição da conversa Virtual Agent atual.