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 a diferenciar das variáveis ao nível do tópico. Por exemplo, a variável UserName torna-se Global.UserName.

3. Guardar o tema.

1. Seleciona a variável que queres.

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

3. O nome da variável recebe o prefixo bot. para a diferenciar das variáveis ao nível do tópico. Por exemplo, a variável UserEmail torna-se bot.UserEmail.

Quando compor uma mensagem num nó Mensagem ou num nó Pergunta , selecione o ícone {x} para visualizar as variáveis a que o tópico pode aceder. Também pode utilizar variáveis globais em nós de Ferramenta que chamam pedidos ou fluxos de trabalho. As variáveis globais aparecem no separador Personalizado juntamente com quaisquer variáveis do tópico. As variáveis estão listadas por ordem alfabética.

Quando compor uma mensagem num nó Mensagem ou num nó Pergunta , selecione o ícone {x} para visualizar as variáveis a que o tópico pode aceder. 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. Seleciona a variável global que queres no canvas de autoria ou no painel de 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 que pretende na tela de criação. O painel Propriedades da variável aparece.

• Para ir diretamente ao nó onde criou a variável global, selecione Ir à fonte.

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

Por defeito, um valor global de variável persiste até ao fim da sessão . O nó Limpar valores de variáveis repõe os valores das variáveis globais. O tópico de sistema Repor Conversação utiliza este nó. 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.

Pode aceder a variáveis globais de qualquer tema, e o seu valor mantém-se 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 global das variáveis ao implementar ações através de fluxos ou competências 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, use uma variável global e defina o seu valor a partir de uma fonte externa. Suponha que o seu site exige 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 exemplo de cenário é passar o contexto do Dynamics 365 Customer Service para um agente, para que este possa iniciar a conversa com conhecimento do que o cliente quer alcançar.

Para evitar latência indesejável, especifique 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 padrão por um que corresponda exatamente ao nome da variável que está a ser passada pelo 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 timeout, 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 Atendimento ao Cliente, use 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 utilizar se o tempo limite for atingido. Em tempo de execução, o seu agente espera valores com o mesmo tipo de dado. 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.

Quando configuras o teu agente desta forma, ele está pronto para testar. 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 seu agente tenta aceder a uma variável que está a ser definida externamente, ele pausa até o valor chegar ou ocorrer o timeout. Saiba mais em 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. Seleciona a variável global que queres.

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, para uma variável Global.UserName global use apenas UserName na consulta.

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

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 distingue maiúsculas de minúsculas: username=Ana também funciona neste exemplo.

Pode adicionar variáveis e as suas definições se simplesmente estiver a incorporar o seu agente numa página web simples. Ou pode usar um <script> bloco de código para chamar e usar variáveis programaticamente.

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

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 passar o nome de utilizador ao iniciar uma conversa com um agente num site, anexe a UserEmail= cadeia de consulta como: https://web.powerva.microsoft.com/webchat/bots/12345?UserEmail=Ana@contoso.com.

2. O nome do parâmetro não distingue maiúsculas de minúsculas: useremail=Ana@contoso.com também funciona 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));