Trabalhar com variáveis globais

As variáveis armazenam as respostas de seus clientes às perguntas do seu agente. Por exemplo, você pode salvar o nome de um cliente em uma variável chamada UserName. O agente pode endereçar o cliente pelo nome enquanto a conversa continua.

Por padrão, o valor de uma variável só pode ser usado no tópico em que ela é criada. No entanto, é possível reutilizar o mesmo valor entre tópicos. Por exemplo, um tópico Bem-vindo solicita o nome e o email do cliente. No tópico Reserva de Compromisso, você deseja que o agente lembre o que o cliente inseriu e não pergunte novamente.

Uma maneira de reutilizar uma variável é passar a variável de um tópico para outro. A outra maneira é tornar a variável global no escopo, e é isso que este artigo cobre. As variáveis globais são chamadas assim porque estão disponíveis em todos os tópicos em todo o agente. Eles também podem ser definidos a partir de fontes externas.

As variáveis globais se aplicam durante uma única sessão do usuário. Você especifica quais variáveis são globais para distingui-las das variáveis no nível do tópico.

Criar uma variável global

Você cria uma variável global ao alterar o escopo de uma variável temática.

Observação

O nome de uma variável global deve ser exclusivo em todos os tópicos.

Aplicativo Web

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

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

   O nome da variável receberá o prefixo Global. para diferenciá-lo das variáveis no nível do tópico. Por exemplo, a variável UserName é exibida como Global.UserName.

3. Salve o tópico.

Clássico/Teams

1. Selecione a variável desejada.

2. No painel Propriedades da variável, em Uso, selecione Bot (acessível por qualquer tópico).

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

Usar variáveis globais

Aplicativo Web

Ao redigir uma mensagem em um nó de Mensagem ou em um nó de Pergunta, selecione o ícone {x} para exibir as variáveis que estão disponíveis no tópico. As variáveis globais são listadas na guia Personalizado, juntamente com quaisquer variáveis de tópico. As variáveis são classificadas em ordem alfabética.

Clássico/Teams

Ao redigir uma mensagem em um nó de Mensagem ou em um nó de Pergunta, selecione o ícone {x} para exibir as variáveis que estão disponíveis no tópico. As variáveis são listadas em ordem alfabética e todas as variáveis globais aparecem juntas porque todas começam com bot..

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

Encontre todos os tópicos usando uma variável global

Você pode encontrar onde uma variável global é definida e que outros tópicos a estão usando. Este recurso pode ser útil se você estiver trabalhando em um novo agente ou se tiver várias variáveis e ramificação de tópicos complexos.

Aplicativo Web

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 seção Referência, selecione Exibir todas as referências.

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

Clássico/Teams

Selecione a variável desejada na tela de criação. O painel Propriedades da variável é exibido.

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

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

Excluindo variáveis globais

Se você remover uma variável global usada em outros tópicos, as referências a essa variável nos tópicos são marcadas como Unknown. Você receberá um aviso sobre a exclusão da variável global antes de poder confirmar a operação.

Os nós que contêm referências à variável global excluída indicam que eles contêm uma variável desconhecida.

Os tópicos com nós que contêm referências a variáveis globais excluídas podem parar de funcionar. Certifique-se de remover ou corrigir todos os tópicos que estavam usando a variável excluída antes da publicação de seu agente.

Ciclo de vida de variáveis globais

Aplicativo Web

Por padrão, o valor de uma variável global persiste até a sessão terminar. O nó Desmarcar valores de variáveis redefine os valores de variáveis globais e é usado no tópico do sistema Redefinir conversa. Quando um redirecionamento dispara esse tópico (ou quando o usuário insere uma frase como "Recomeçar"), todas as variáveis globais são redefinidas.

Clássico/Teams

As variáveis globais são acessíveis de qualquer tópico, e seu valor persiste em toda a sessão.

O valor só é apagado quando o usuário do agente é redirecionado para o tópico do sistema Recomeçar ou quando o usuário dispara esse tópico diretamente (por exemplo, ao digitar "Recomeçar"). Nesse caso, todas as variáveis globais serão zeradas e não tem nenhum valor.

Inicialização da variável global

Se uma variável global for acionada antes de ser inicializada (ou "preenchida"), o agente dispara automaticamente a parte do tópico em que a variável global é definida pela primeira vez, mesmo quando estiver em um tópico diferente, antes de retornar ao original tópico. Esse comportamento permite que o agente tenha todas as variáveis preenchidas sem interromper a conversa.

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

Quando a conversa chega ao ponto no tópico "Reserva de compromisso", onde bot.UserName é referenciado, o agente será dinamicamente integrado ao nó da pergunta em que bot.UserName é definido pela primeira vez.

Depois que o cliente responder à pergunta, o agente retoma o tópico "Reserva de compromisso".

Comportamento da variável global ao implementar ações por meio de fluxos ou habilidades do Power Automate

Às vezes, você pode usar um fluxo ou habilidade para inicializar ou preencher uma variável.

No entanto, quando um usuário interage com o agente, a variável pode ser preenchida em um ponto anterior da conversa, ou você pode já ter definido as variáveis externamente.

Nessa situação, o fluxo ou habilidade ainda é executado e preencherá a variável, sobrescrevendo tudo o que foi previamente armazenado na variável.

Definir variáveis globais de fontes externas

Aplicativo Web

Para garantir que o agente inicie uma conversa com algum contexto, você pode usar uma variável global e definir seu valor de uma fonte externa. Digamos que seu site exija que os usuários façam login. Se você armazenar o nome de um usuário em uma variável global e passá-lo para seu agente, o agente poderá cumprimentar os clientes pelo nome antes que eles comecem a digitar a primeira pergunta. Outro cenário de exemplo é passar o contexto do Dynamics 365 Customer Service para um agente para que ele possa iniciar a conversa com conhecimento do que o cliente deseja alcançar.

Para evitar latências indesejáveis, você pode especificar quanto tempo o agente pode esperar por um valor. Você também pode definir um valor padrão a ser usado quando a fonte externa não responder em tempo hábil.

Observação

Os agentes publicados no canal Dynamics 365 Contact Center para casos de uso de IVR não oferecem suporte a valores de tempo limite configurados para variáveis globais definidas por fontes externas.

1. Crie um tópico dedicado para manter a configuração de todas as variáveis que devem ser definidas a partir de fontes externas. Você pode nomear este tópico como "Definir variáveis de contexto", por exemplo. Este tópico não serve para outros propósitos, portanto, não precisa ter frases de gatilho definidas.

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

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

4. Selecione o nome padrão da nova variável. O painel Propriedades da variável é exibido.

5. Substitua o nome padrão por um que corresponda exatamente ao nome da variável que está sendo passada do sistema externo.

6. Em Uso, selecione Global (qualquer tópico pode acessar) e Fontes externas podem definir valores.

7. Em Referência, selecione o ícone Mais (⋮) no canto superior direito e selecione Obter valor desse nó se estiver vazio.

8. (Opcional) Defina um atraso de tempo limite, em milissegundos. Esse valor determina quanto tempo o agente pode esperar que a variável seja definida por uma fonte externa antes de atingir o tempo limite e continuar com o valor padrão definido no nó Definir valor da variável. Essa configuração é relevante em cenários em que a variável depende de um processo de longa execução ou assíncrono, mas seu agente deve respeitar uma latência máxima para garantir uma boa experiência do usuário.

   Para variáveis provenientes de 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, insira o valor padrão a ser usado se o tempo limite for atingido. Em tempo de execução, seu agente esperará valores com o mesmo tipo de dados. Se você quiser que esse valor padrão seja uma cadeia de caracteres vazia, use Text("") como uma fórmula.

   

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

Assim configurado, seu agente está pronto para testar. Quando o agente é chamado, em vez de esperar indefinidamente que todas as variáveis sejam preenchidas, ele pode começar imediatamente a enviar quaisquer mensagens que não dependam das variáveis que estão sendo passadas. Quando o agente tenta acessar uma variável que está sendo definida externamente, ele pausa até que o valor chegue ou o tempo limite ocorra. Saiba mais sobre como otimizar agentes para minimizar a latência.

Importante

Durante o fluxo normal de uma conversa, se o agente definir uma variável que, de outra forma, seria definida por um valor externo, esse valor definido de dentro do agente prevalecerá. Qualquer valor passado no contexto é ignorado. Essa regra impede que seu agente substitua valores definidos intencionalmente em tópicos.

Clássico/Teams

Você pode definir uma variável global para ser inicializada de uma origem externa. Esta ação permite que o agente inicie a conversa com algum contexto.

Por exemplo, um cliente abre um chat do agente no seu site, e o site já sabe o nome do cliente. Permita que o agente saiba o nome do usuário antes de iniciar a conversa, e o agente poderá ter uma conversa mais inteligente com o cliente sem precisar perguntar nome dele novamente.

1. Selecione a variável global desejada.

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

Definir variáveis globais em um agente incorporado

Aplicativo Web

Se estiver incorporando seu agente em uma página da Web simples, você poderá acrescentar variáveis e suas definições à URL do agente. Ou, se quiser um pouco mais de controle, você pode usar um bloco de código <script> para chamar e usar variáveis de forma programada.

O nome da variável na cadeia de consulta do URL deve 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 que se seguem usa uma declaração básica para as variáveis. Em um cenário de produção, é possível passar outra variável que já armazenou o nome do usuário como o parâmetro de consulta ou a definição de variável (por exemplo, se você tiver o nome de usuário em um script de entrada).

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

Por exemplo:

• Você tem uma variável global chamada Global.UserName.
• O URL do agente é https://web.powerva.microsoft.com/webchat/bots/12345.
• Para informar o nome de usuário ao iniciar uma conversa do agente em um site, anexe a UserName= cadeia de caracteres de consulta como: https://web.powerva.microsoft.com/webchat/bots/12345?UserName=Ana.

O nome do parâmetro não faz distinção entre maiúsculas e minúsculas. username=Ana também funcionaria neste exemplo.

Clássico/Teams

Você pode anexar as variáveis e suas definições se simplesmente incorporar seu agente a uma página da Web simples ou pode usar um bloco de código <script> para chamar e usar variáveis de forma programada.

Observação

O nome da variável na cadeia de consulta deve corresponder ao da variável global, sem o prefixo bot.. Por exemplo, a variável global bot.UserEmail deve aparecer como UserEmail=.

Nos exemplos descritos aqui, é feita uma declaração simples para as variáveis. Em um cenário de produção, é possível passar outra variável que já armazenou o nome do usuário como o parâmetro de consulta ou a definição de variável (por exemplo, se você tiver o nome de usuário em um script de entrada).

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

   • Você tem uma variável global chamada bot.UserEmail.
   • O URL do agente é https://web.powerva.microsoft.com/webchat/bots/12345.
   • Para passar o nome de usuário ao iniciar uma conversa de agente em um site, você pode anexar a UserEmail= cadeia de caracteres de consulta como: https://web.powerva.microsoft.com/webchat/bots/12345?UserEmail=Ana@contoso.com.

2. O nome do parâmetro não faz distinção entre maiúsculas e minúsculas. Isso significa que useremail=Ana@contoso.com também funcionará neste exemplo.

Adicionar variáveis globais a uma tela personalizada

Você também pode adicionar a variável a uma tela personalizada.

Aplicativo Web

1. Na seção <script> na página em que você tem seu agente, defina as variáveis da seguinte maneira, substituindo variableName1 pelo nome da variável sem o prefixo Global. e variableDefinition1 para a definição. Separe as muitas 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. Em sua seção <script>, ligue para store quando inserir seu agente, como no exemplo a seguir, store é chamado antes de onde styleOptions é chamado (você precisará substituir BOT_ID por sua ID do 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));
   

Clássico/Teams

1. Na seção <script> na página em que você tem seu agente, defina as variáveis da seguinte maneira, substituindo variableName1 pelo nome da variável sem o prefixo bot. e variableDefinition1 para a definição. Separe as muitas 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. Em sua seção <script>, ligue para store quando inserir seu agente, como no exemplo a seguir, store é chamado antes de onde styleOptions é chamado (você precisará substituir BOT_ID por sua ID do 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));
   

Variáveis globais relacionadas à autenticação

Dependendo da configuração de autenticação do agente, você terá um conjunto de variáveis globais associadas ao provedor de autenticação selecionado. Para obter detalhes sobre quais conjuntos de variáveis estão disponíveis e como usá-los, consulte Adicionar autenticação de usuário aos tópicos.

---

Conteúdo relacionado

• Trabalhar com variáveis
• Personalizar a aparência de um agente