Trabalhar com variáveis globais

1. Crie uma variável ou use o painel Variáveis para abrir uma variável existente.

2. No painel Propriedades da variável, selecione Global (qualquer tópico pode aceder).

   O nome da variável recebe o prefixo Global. para diferenciá-la das variáveis ao nível do tópico. Por exemplo, a variável UserName é apresentada como Global.UserName.

3. Guarde o tópico.

1. Selecione a variável pretendida.

2. No painel Propriedades da variável, em Utilização, selecione Bot (qualquer tópico pode aceder).

3. O nome da variável é marcado com um prefixo bot. para diferenciá-la das variáveis ao nível do tópico. Por exemplo, a variável UserEmail agora aparece como bot.UserEmail.

Quando estiver a compor uma mensagem num nó de Mensagem ou de Pergunta, selecione o ícone {x} para ver as variáveis disponíveis para o tópico. As variáveis globais aparecem no separador Personalizado juntamente com quaisquer variáveis de tópico. As variáveis estão listadas por ordem alfabética.

Quando estiver a compor uma mensagem num nó de Mensagem ou de Pergunta, selecione o ícone {x} para ver as variáveis disponíveis para o tópico. As variáveis estão listadas em ordem alfabética, e todas as variáveis globais aparecem juntas porque todas começam por bot..

Quando usar um nó de condição, um nó de ação de fluxo ou um nó de competência, também vê variáveis globais disponíveis lá.

1. Selecione a variável global desejada na tela de criação ou no painel Variáveis.

2. No painel Propriedades da variável, na secção Referência, selecione Ver todas as referências.

3. Mude para o separador Outro e selecione qualquer tópico em que a variável seja usada para ir diretamente para esse tópico e nó.

Selecione a variável pretendida na tela de criação. O painel Propriedades da variável aparece.

• Para ir diretamente para o nó onde a variável global foi criada, selecione Ir para a origem.

• Para ir para um tópico que usa esta variável, selecione o tópico desejado na secção Usado por .

Por predefinição, o valor de uma variável global persiste até que a sessão termine. O nó Limpar valores de variáveis repõe os valores de variáveis globais e é usado no tópico de sistema Repor Conversa. Quando um redirecionamento aciona esse tópico (ou quando o utilizador introduz uma frase como "Começar novamente"), todas as variáveis globais são repostas.

As variáveis globais são acessíveis a partir de qualquer tópico e o respetivo valor persiste ao longo de uma sessão.

O valor só é limpo quando o utilizador do agente é redirecionado para o tópico Começar Novamente ou quando o utilizador aciona este tópico diretamente (por exemplo, escrevendo "Começar novamente"). Neste caso, todas as variáveis globais são repostas e não têm um valor.

Inicialização de variável global

Se uma variável global for acionada antes de ser inicializada (ou "preenchida"), o agente aciona automaticamente a parte do tópico onde a variável global é definida pela primeira vez — mesmo quando está num tópico diferente — antes de regressar ao tópico original. Este comportamento permite ao agente ter todas as variáveis preenchidas sem interromper a conversa.

Por exemplo, o cliente inicia a conversa sobre a tópico "Marcação de compromisso", na qual é utilizada uma variável global bot.UserName. No entanto, a variável bot.UserName é definida pela primeira vez no tópico "Bem-vindo".

Quando a conversa chegar ao ponto no tópico "Marcação de compromisso" onde bot.UserName é referenciada, o agente vai perfeitamente para o nó de pergunta onde bot.UserName é definida pela primeira vez.

Depois do cliente responder à pergunta, o agente retoma o tópico "Marcação de compromisso".

Comportamento da variável global quando implementa ações através de competências ou fluxos do Power Automate

Por vezes, poderá utilizar um fluxo ou competência para inicializar ou preencher uma variável.

No entanto, quando um utilizador interage com o agente, a variável poderá ser preenchida num ponto anterior da conversa ou poderá ter já definido as variáveis externamente.

Nesta situação, o fluxo ou a competência continua a executar e preenche a variável, substituindo o que quer que estava armazenado anteriormente na variável.

Para garantir que o agente inicia uma conversa com algum contexto, pode usar uma variável global e definir o valor a partir de uma origem externa. Digamos que o seu site requer que os utilizadores iniciem sessão. Se armazenar o nome de um utilizador numa variável global e transmiti-lo ao seu agente, o agente poderá cumprimentar os clientes pelo nome antes que estes comecem a escrever a primeira pergunta. Outro cenário de exemplo é transmitir o contexto do Dynamics 365 Customer Service para um agente para que este possa iniciar a conversa com conhecimento do que o cliente deseja alcançar.

Para evitar latência indesejável, pode especificar quanto tempo o seu agente pode esperar por um valor. Também pode definir um valor predefinido a usar quando a origem externa não responder em atempadamente.

1. Crie um tópico dedicado para manter a configuração de todas as variáveis destinadas a serem definidas a partir de origens externas. Poderá nomear este tópico como "Definir variáveis de contexto", por exemplo. Este tópico não serve para outros fins, por isso não precisa de ter frases acionadores definidas.

2. Adicione um nó Definir valor da variável ao seu tópico dedicado.

3. Em Definir variável, abra o seletor de variáveis e selecione Criar uma nova variável.

4. Selecione o nome predefinido da nova variável. O painel Propriedades da variável aparece.

5. Substitua o nome predefinido por um que corresponda exatamente ao nome da variável que está a ser transmitida do sistema externo.

6. Em Utilização, selecione Global (qualquer tópico pode aceder) e Origens externas podem definir valores.

7. Em Referência, selecione os três pontos (⋮) no canto superior direito e selecione Obter valor deste nó se estiver vazio.

8. (Opcional) Defina um atraso de tempo limite, em milissegundos. Este valor determina quanto tempo o agente pode aguardar até que a variável seja definida por uma origem externa antes de atingir o tempo limite e continuar com o valor predefinido definido no nó Definir valor da variável . Esta definição é relevante em cenários em que a variável depende de um processo assíncrono ou de longa duração, mas o seu agente tem de respeitar uma latência máxima para garantir uma boa experiência de utilizador.

   Para variáveis provenientes do Omnicanal para Customer Service, sugerimos um valor de 10 segundos (10.000 ms) como tempo máximo de espera.

9. No nó Definir valor da variável, introduza o valor predefinido a usar se o tempo limite for atingido. Em runtime, o seu agente esperará valores com o mesmo tipo de dados. Se pretender que este valor predefinido seja uma cadeia vazia, use Text("") como uma fórmula.

   

10. Para quaisquer outros valores que espera que venham de um sistema externo, adicione mais nós Definir valor da variável ao seu tópico dedicado e configure as variáveis globais necessárias da mesma maneira.

Assim configurado, o seu agente está pronto a ser testado. Quando o agente é invocado, em vez de esperar indefinidamente que todas as variáveis sejam preenchidas, o agente pode começar imediatamente a enviar quaisquer mensagens que não dependam das variáveis que estão a ser transmitidas. Quando o agente tenta aceder a uma variável que está a ser definida externamente, é colocado em pausa até que o valor chegue ou o tempo limite ocorra. Obtenha mais informações sobre como otimizar agentes para minimizar a latência.

Pode definir uma variável global para ser inicializada a partir de uma origem externa. Esta ação permite ao agente iniciar a conversa com algum contexto.

Por exemplo, um cliente traz um chat de agente do seu site, e o site já sabe o nome do cliente. Informe o agente sobre o nome do utilizador antes de iniciar a conversa, e o agente pode ter uma conversa mais inteligente com o cliente sem ter que pedir o seu nome novamente.

1. Selecione a variável global desejada.

2. No painel Propriedades da variável, selecione Origens externas podem definir valores.

Se estiver a incorporar o seu agente numa página Web simples, poderá anexar variáveis e as respetivas definições ao URL do agente. Ou, se quiser um pouco mais de controlo, pode usar um bloco de código <script> para chamar e usar variáveis programaticamente.

O nome da variável na cadeia de consulta do URL tem de corresponder ao nome da variável global, sem o prefixo Global.. Por exemplo, uma variável global Global.UserName seria referida como UserName na consulta.

Os exemplos a seguir usam uma declaração básica para as variáveis. Num cenário de produção, pode passar como no parâmetro de consulta ou definição de variável outra variável que já armazene o nome do utilizador (por exemplo, se tiver o nome de utilizador a partir de um script de entrada).

Anexar as variáveis e as suas definições ao URL do agente como parâmetros de cadeia de consulta no formato botURL?variableName1=variableDefinition1&variableName2=variableDefinition2.

Por exemplo:

• Tem uma variável global chamada Global.UserName.
• O URL do seu agente é https://web.powerva.microsoft.com/webchat/bots/12345.
• Para transmitir o nome do utilizador ao iniciar uma conversa de agente no seu site, anexe a cadeia de consulta UserName= como: https://web.powerva.microsoft.com/webchat/bots/12345?UserName=Ana.

O nome do parâmetro não é sensível às maiúsculas e minúsculas. username=Ana também funcionaria neste exemplo.

Pode anexar as variáveis e as suas definições se estiver simplesmente a incorporar o seu agente numa página Web simples ou pode usar um bloco de código <script> para ligar e usar variáveis de forma programática.

Nos exemplos aqui descritos, é feita uma simples declaração para as variáveis. Num cenário de produção, pode passar como no parâmetro de consulta ou definição de variável outra variável que já armazene o nome do utilizador (por exemplo, se tiver o nome de utilizador a partir de um script de entrada).

1. Anexar as variáveis e as suas definições ao URL do agente como parâmetros de cadeia de consulta (no formato de botURL?variableName1=variableDefinition1&variableName2=variableDefinition2), por exemplo:

   • Tem uma variável global chamada bot.UserEmail.
   • O URL do seu agente é https://web.powerva.microsoft.com/webchat/bots/12345.
   • Para transmitir o nome do utilizador ao iniciar uma conversa de agente num site, pode anexar a cadeia de consulta UserEmail= como: https://web.powerva.microsoft.com/webchat/bots/12345?UserEmail=Ana@contoso.com.

2. O nome do parâmetro não é sensível às maiúsculas e minúsculas. Isto significa que useremail=Ana@contoso.com também funcionaria neste exemplo.

1. Na secção <script> na página onde tem o seu agente, defina as variáveis da seguinte forma, substituindo variableName1 pelo nome da variável sem o prefixo Global. e variableDefinition1 para a definição. Separe várias variáveis com vírgulas (,).

      const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
        if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
          dispatch({
             type: "WEB_CHAT/SEND_EVENT",
             payload: {
               name: "pvaSetContext",
               value: {
                  "variableName1": "variableDefinition1",
                  "variableName2": "variableDefinition2"
               }
             },
           });
         }
           return next(action);
       });
   

2. Na sua secção <script>, ligue para store quando incorpora o seu agente, como no exemplo seguinte onde store é chamado logo antes de onde styleOptions é chamado (tem de substituir BOT_ID pelo seu ID de agente):

   const BOT_ID = "12345-5678";
   const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
   fetch(theURL)
       .then(response => response.json())
       .then(conversationInfo => {
           window.WebChat.renderWebChat(
               {
                   directLine: window.WebChat.createDirectLine({
                       token: conversationInfo.token,
                   }),
                   store,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })
       .catch(err => console.error("An error occurred: " + err));
   

1. Na secção <script> na página onde tem o seu agente, defina as variáveis da seguinte forma, substituindo variableName1 pelo nome da variável sem o prefixo bot. e variableDefinition1 para a definição. Separe várias variáveis com vírgulas ,.

      const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
        if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
          dispatch({
             type: "WEB_CHAT/SEND_EVENT",
             payload: {
               name: "pvaSetContext",
               value: {
                  "variableName1": "variableDefinition1",
                  "variableName2": "variableDefinition2"
               }
             },
           });
         }
           return next(action);
       });
   

2. Dentro da sua secção <script>, ligue para store quando incorpora o seu agente, como no exemplo seguinte onde store é chamado logo antes de onde styleOptions é chamado (tem de substituir BOT_ID pelo seu ID):

   const BOT_ID = "12345-5678";
   const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
   fetch(theURL)
       .then(response => response.json())
       .then(conversationInfo => {
           window.WebChat.renderWebChat(
               {
                   directLine: window.WebChat.createDirectLine({
                       token: conversationInfo.token,
                   }),
                   store,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })
       .catch(err => console.error("An error occurred: " + err));