Recursos de API Virtual Agent disponíveis na versão na Store 2.0.x

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 12 min. de leitura

    • A API Virtual Agent versão 2.0.x fornece acesso a mais recursos que estão disponíveis em Virtual Agent e Bate-papo do agente, incluindo suporte avançado de controle e notificações.

    Suporte para controles avançados adicionais

    A API Virtual Agent agora oferece suporte aos seguintes controles avançados.

    Controles booleanos
    Os controles booleanos retornam respostas como cadeias de caracteres ( Yes ou No) para facilitar a localização.

    Para obter mais informações sobre localização de tópicos, consulte Localizando Virtual Agent conversas.

    Virtual Agent A API envia o seguinte exemplo de JSON para um controle booleano:
    {
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "7a36412253a13010ff59ddeeff7b12fb",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "Boolean",
      "group": "DefaultPicker",
      "required": true,
      "nluTextEnabled": false,
      "label": "Sample Response for boolean control",
      "options": [
        {
          "label": "Yes"
        },
        {
          "label": "No"
        }
      ]
    }
  ],
  "score": 1
}
    Controles personalizados
    Tópicos que usam controles personalizados agora são compatíveis. Para obter mais informações sobre controles personalizados, consulte Como personalizar Virtual Agent com controles personalizados.
    Controles de resposta do bot da tabela
    Tópicos que usam controles de resposta de bot de tabela agora são suportados. Para obter mais informações, consulte Controle de resposta do bot em tabela.

    Todos os registros são retornados da API Virtual Agent de uma vez. Virtual Agent aguardará uma resposta do cliente de API para enviar o próximo controle. Use a propriedade paginationBreak para exibir registros em blocos para o usuário. Por exemplo, se paginationBreak estiver definido como 10, o usuário verá 10 registros por vez. Quando o cliente estiver pronto para passar para o próximo controle, ele deverá enviar DONE.

    A API Virtual Agent envia o seguinte exemplo de JSON para um controle de resposta de bot de tabela:
    {
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Yes",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputTable",
      "group": "DefaultOutputTable",
      "label": "Sample Table Rich control",
      "headers": [
        "Number",
        "Short description"
      ],
      "data": [
        [
          "INC0000005",
          "CPU load high for over 10 minutes"
        ],
        [
          "INC0000015",
          "I can't launch my VPN client since the last software update"
        ],
        [
          "INC0000025",
          "Need to add more memory to laptop"
        ],
        [
          "INC0000035",
          "Reset my password"
        ],
        [
          "INC0000055",
          "SAP Sales app is not accessible"
        ],
        [
          "INC0009005",
          "Email server is down."
        ]
      ],
      "paginationBreak": 10,
      "totalSearchResultsCount": 6,
      "navigationBtnLabel": "Click for more"
    }
  ],
  "score": 1
}
    Controles de resposta do bot HTML
    Tópicos que usam controles de resposta de bot HTML agora são suportados. Para obter mais informações, consulte Controle de resposta do bot HTML.
    A API Virtual Agent envia o seguinte exemplo de JSON para um controle de resposta de bot HTML:
    {
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Yes",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputHtml",
      "group": "DefaultOutputHtml",
      "style": "inline",
      "height": 100,
      "width": 100,
      "value": "<html> <body> Sample Response for Html control </body> </html> ",
      "imageUrl": null,
      "imageHeight": 0,
      "imageWidth": 0,
      "links": null
    },
    {
      "uiType": "InputText",
      "group": "DefaultText",
      "required": true,
      "nluTextEnabled": false,
      "label": "some text",
      "maskType": "NONE"
    }
  ],
  "score": 1
}
    Controles de resposta do bot de várias respostas
    Tópicos que usam controles de resposta de bot de várias respostas agora são suportados. Para obter mais informações, consulte Controle de resposta do bot de várias respostas.
    A API Virtual Agent envia o seguinte exemplo de JSON para um controle de resposta de bot de várias respostas:
    {
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Done",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "MultiPartOutput",
      "group": "DefaultMultiPartOutput",
      "navigationBtnLabel": "Click for more",
      "content": {
        "uiType": "OutputText",
        "value": "Text response from multiflow control example",
        "maskType": "NONE"
      }
    }
  ],
  "score": 1
}
    Suporte a rich text
    Tópicos que usam rich text agora são compatíveis. Rich text inclui texto em negrito ou itálico, hiperlinks, listas com marcadores e emojis.

    Recursos Bate-papo do agente adicionais

    A API Virtual Agent agora oferece suporte aos seguintes recursos ao transferir para Bate-papo do agente.

    Passar nome do agente e avatar
    Quando o bot primário transfere um bate-papo para um atendente, Virtual Agent pode enviar o nome e o avatar do agente para o bot primário. Para habilitar isso, ative os Nomes e avatares do agente nas configurações do Bate-papo do agente.
    Um exemplo de carga de mensagem pode ser semelhante a este:
    { 
"requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c", 
"clientSessionId":"U94CSJLEN", 
"message":{ 
"text":"Live Agent support.", 
"typed":true 
}, 
"userId":"U94CSJLEN", 
"body":[ 
{ 
"uiType":"OutputText", 
"group":"DefaultText", 
"agentInfo":{ 
"sentFromAgent":true, 
"agentName":"Beth Anglin", 
"agentAvatar":"ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" 
}, 
"value":"Thank you for contacting support. I am looking into your question now and will be with you shortly." 
} 
], 
"agentChat":true, 
"score":1 
}

    Para obter mais informações, consulte Configuração do Bate-papo do agente.

    Tempo de espera do atendente
    Ao transferir para um agente dinâmico, o bot primário pode receber o tempo de espera e exibi-lo para o usuário. Para habilitar isso, selecione Tempo de espera no campo de status de espera do bate-papo em tempo real nas configurações do Bate-papo do agente. O valor spinnerType está definido como wait_time. Se o status de espera do bate-papo ao vivo estiver definido como Nenhum, o valor [ spinnerType será none.
    A API Virtual Agent envia o seguinte exemplo de JSON no parâmetro body da carga.
    {
"uiType":"ActionMsg",
"actionType":"StartSpinner",
"spinnerType":"wait_time",
"message":"Routing you to a live agent...",
"waitTime":"8 Seconds"
}

    Para obter mais informações, consulte Configuração do Bate-papo do agente.

    Enviar histórico de bate-papo do bot primário para Virtual Agent
    O bot primário pode passar o histórico de bate-papo para um atendente para que o agente possa ver o contexto da conversa.
    Virtual Agent converte o histórico de mensagens em HTML e, em seguida, em uma imagem.
    • A imagem convertida é enviada ao agente em tempo real como a primeira mensagem do bate-papo.
    • O bot primário deve enviar o histórico de mensagens na primeira solicitação. Em qualquer outra solicitação após a primeira solicitação, a carga do histórico de mensagens será ignorada.
    • Somente mensagens de texto são compatíveis.
    • O bot primário pode passar qualquer URL como um valor na mensagem de texto, mas o agente em tempo real só pode exibi-lo como parte da imagem. O atendente não poderá clicar no link.
    Exemplo de carga da mensagem:
    {​ 
      "value": "Help me with password reset",​ 
      "displayName": "able",​ 
      "type": "text"​ 
      "isBotMessage": false,​ 
    }
    Nota:
    No exemplo anterior, type faz distinção entre maiúsculas e minúsculas e deve ter um valor de text.

    Solicitações aprimoradas do bot primário

    A API Virtual Agent agora oferece suporte às solicitações a seguir do bot primário.

    Parâmetros do sistema e variáveis de contexto
    O bot primário pode passar parâmetros do sistema e variáveis de contexto como entrada e Virtual Agent honrará esses parâmetros. Parâmetros do sistema como liveagent_devicetype, liveagent_requester_session_language, liveagent_topic, topic, live_agent_onlye liveagent_devicetimezone são compatíveis. Variáveis de contexto personalizadas e variáveis de contexto Bate-papo do agente também são compatíveis.
    Exemplo de carga da mensagem:
    {​ 
"requestId": "f42f3550-5b44-4cde-aa52-xxxxxxxxxx",​ 
"clientSessionId": "xxxxxxxxxx",​ 
"token": "abcd",​ 
"message": {​ 
    "text": "Test",​ 
    "typed": true​ 
},​ 
"contextVariables": {​ 
       "requester_session_language": "es"​ 
},​ 
"userId": ""abel.tuter",​ 
"emailId": "abel.tuter@example.com"​ 
}​

    Para obter mais informações, consulte Variáveis de contexto do atendente. e Como configurar variáveis de contexto para armazenar informações relacionadas ao bate-papo.

    Fuso horário do usuário
    Defina o fuso horário do usuário passando-o na carga da solicitação. Depois de definida, essa configuração de fuso horário é mantida até que seja redefinida.
    Exemplo de carga da mensagem:
    {​ 

    "requestId": "xxxxxx-xxxxxx-xxxx-xxxx-xxxxxxxxxx",​ 
    "clientSessionId": "xxxxxxxx-xxxx",​ 
    "token": "xxxxx",​ 
    "action" : "SET_USER_TIMEZONE",​ 
    "userId": "able.tuter",​ 
    "emailId": "abel.tuter@example.com",​ 
     "timezone":"Asia/Kolkata"​ 
}
    Ao usar esta funcionalidade, considere o seguinte:
    • A conversa deve estar aberta (atual) para converter a data e a hora no fuso horário do usuário.
    • O bot primário deve enviar data e hora em um dos seguintes formatos:
      • Nome do fuso horário. Por exemplo, Asia/Kolkata ou America/New_York.
      • Formato de data e hora de 24 horas. Por exemplo: YYYY-MM-DD HH:MM:SS
    • A API Virtual Agent usa o fuso horário especificado pelo bot primário, mesmo que o fuso horário definido seja diferente do valor armazenado na tabela [sys_user].
    • Para definir o fuso horário do usuário, envie a ação SET_TIMEZONE. Se o nome do fuso horário não for válido, o valor do fuso horário será padronizado como hora UTC. Por exemplo, 2021-02-16 20:13:13.

    Suporte para omissão de nó

    A API Virtual Agent oferece suporte para ignorar um nó se for projetado para fazer isso no tópico. Por exemplo, em Designer do Virtual Agent, você pode designar um controle de entrada do usuário como ignorável no Avançado > Ocultar ou ignorar este nó área da folha de propriedades.

    Figura 1. Condição ou script que permite ao usuário ignorar o nó
    Neste exemplo, a opção Script está selecionada e define quando o usuário pode ignorar o nó.

    Para obter mais informações sobre como definir um nó como ignorável, consulte controles de entrada do usuário Designer do Virtual Agent.

    Se um nó estiver marcado como ignorável, o bot apresentará essa opção ao usuário. Se o usuário ignorá-lo, o bot primário deverá passar o comando ignorar, conforme ilustrado no exemplo a seguir. 
    {
"requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId": "835607",
"token": "snow",
"message": {
"text": "_skip_",
"typed": false
},
"emailId": "beth.anglin@example.com",
"userId": "beth.anglin"
}

    Suporte para handshake síncrono

    Nota:
    Esses requisitos se aplicam à versão 2.0.x da API Virtual Agent. Para obter maior funcionalidade de cumprimento síncrono, faça upgrade para a versão 3.0.x, que oferece suporte à transferência de agente em tempo real e outras melhorias. Para obter detalhes, consulte Aprimoramentos de handshake síncrono.
    Quando habilitado, Virtual Agent entrega respostas ao bot primário de forma síncrona. Se você quiser habilitar a comunicação com Virtual Agent no modo síncrono, deverá desativar manualmente os seguintes recursos para que o aperto de mão funcione:
    • Bate-papo do agente
    • Notificações
    • Indicadores de digitação
    Nota:
    Os tópicos que usam os seguintes recursos não são compatíveis com o modo síncrono: carregamento de arquivo, o Utilitário de ação e Pausar bloco de tópicos.
    Para desabilitar esses recursos e habilitar o suporte síncrono, siga estas etapas:
    1. Excluir o bot para o canal de bot de Bate-papo do agente.
      1. Navegue até Todos e insira sys_properties.list no filtro.
      2. Selecione a propriedade do sistema com.glide.cs.exclude.liveagent.support para abri-la.
      3. Adicione Bot To Bot ao campo Valor.
        Figura 2. Excluir o bot para o canal de bot de Bate-papo do agente.
        O campo Valor da propriedade do sistema contém "Alexa,Google Assistant,Bot to Bot". Esses canais não são compatíveis com Bate-papo do agente.
      4. Clique em Atualizar.
    2. Navegue até Todos, e, em seguida, insira sys_cs_channel.list no filtro de navegação.
    3. Selecione o registro de bot para bot.
    4. Desmarque a caixa de seleção Habilitar notificações para desabilitá-la.
    5. Desmarque a caixa de seleção Indicador de suporte à digitação para desabilitá-la.
    6. Marque a caixa de seleção Síncrono.
      Figura 3. Canal de bot para bot com suporte síncrono habilitado
      A configuração do canal bot a bot para o modo síncrono mostra as caixas de indicador Habilitar notificações e Suporte à digitação como desmarcadas. A caixa Síncrono está selecionada.
      Nota:
      Se o campo Síncrono não estiver visível, você poderá configurar o layout do formulário para mostrá-lo.
    7. Clique em Atualizar.

    Suporte a notificações

    Use a API Virtual Agent para enviar os seguintes tipos de notificações no bot para o canal de bot quando ele estiver habilitado no modo assíncrono:
    • Simples: notificações somente de texto. Notificações simples são entregues assim que chegam.
    • Cartão de imagem: uma imagem carregada no servidor ou especificada com um URL.
    • Cartão de registro: colunas especificadas de um registro em uma tabela.
    • Acionável: fornece ao usuário a oportunidade de executar determinadas ações. Notificações acionáveis são enfileiradas. O usuário pode recuperá-los sob demanda, enviando o comando Show Notification.

    Para obter mais informações, consulte Configurar notificações do Virtual Agent.

    A API Virtual Agent envia o seguinte exemplo de JSON para uma notificação simples:
    {
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Done",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputCard",
      "group": "DefaultOutputCard",
      "templateName": "Notification",
      "data": "{\"sys_id\":null,\"recordDisplayValue\":null,\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":null,\"tableLabel\":null,\"enableLink\":false,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[],\"table_name\":null,\"url\":\"http://192.168.1.9:8080/null.do?sys_id=null\"}"
    }
  ],
  "completed": true,
  "score": 1
}
    A API Virtual Agent envia o seguinte JSON de exemplo para uma notificação de cartão de imagem:
    {
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Done",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputCard",
      "group": "DefaultOutputCard",
      "templateName": "Notification",
      "data": "{\"sys_id\":null,\"recordDisplayValue\":null,\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":\"http://xxxxxx.service-now.com/2b2d0d2653a13010ff59ddeeff7b120d.iix\",\"tableLabel\":null,\"enableLink\":false,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[],\"table_name\":null,\"url\":\"http://192.168.1.9:8080/null.do?sys_id=null\"}"
    }
  ],
  "completed": true,
  "score": 1
}
    A API Virtual Agent envia o seguinte JSON de exemplo para uma notificação de cartão de registro:
    {
  "requestId": "asd2423-wrr434-weruyt-1234567",
  "clientSessionId": "",
  "nowSessionId": "",
  "message": {
    "text": "Done",
    "typed": false,
    "clientMessageId": "ABC-123"
  },
  "userId": "beth.anglin",
  "body": [
    {
      "uiType": "OutputCard",
      "group": "DefaultOutputCard",
      "templateName": "Notification",
      "data": "{\"sys_id\":\"552c48888c033300964f4932b03eb092\",\"recordDisplayValue\":\"INC0010112\",\"messageHeading\":\"[Heading]A notification has arrived. You can continue the conversation after viewing the notification.\",\"imageUrl\":null,\"tableLabel\":\"Incident\",\"enableLink\":true,\"message\":\"[message]A notification has arrived. You can continue the conversation after viewing the notification.\",\"fields\":[{\"fieldLabel\":\"Number\",\"fieldValue\":\"INC0010112\"},{\"fieldLabel\":\"Short description\",\"fieldValue\":\"Assessment : ATF Assessor\"}],\"table_name\":\"incident\",\"url\":\"http://192.168.1.9:8080/incident.do?sys_id=552c48888c033300964f4932b03eb092\"}"
    }
  ],
  "completed": true,
  "score": 1
}
    As notificações do canal de bot para bot estão desabilitadas por padrão. Para habilitá-las, faça o seguinte:
    1. Navegue até Todos, e, em seguida, insira sys_cs_channel.list no filtro de navegação.
    2. Abra o registro de bot para bot.

      Se solicitado, habilite a edição no registro.

    3. Marque a caixa de seleção Ativar notificações.
    4. Clique em Atualizar.

    Os administradores podem limitar o número de destinatários por notificação, modificando a propriedade com.glide.cs.per_notification_user_limit. O valor padrão é 1000.

    Alternância de tópico usando o nome do tópico

    Além de usar o ID do tópico ou o ID da intenção do tópico para alternar tópicos, você pode usar o tópico ou o nome da intenção do tópico. É recomendável que você envie apenas o ID do tópico ou o nome do tópico. Atualmente, se estiver incorreto ou se o bot já estiver no tópico especificado, Virtual Agent não enviará nenhuma resposta. O uso depende do modo que você está usando, da seguinte forma:
    • Descoberta de tópico NLU: use o nome ou o ID de intenção do tópico.
    • Descoberta de tópico da palavra-chave: use o nome ou o ID do tópico.

    O bot primário pode enviar a ação SWITCH junto com o nome do tópico para alternar diretamente para um tópico específico.

    Exemplo de carga da mensagem:
    {​ 
   "requestId": "xxxx-xxxx-xxxx-xxxx",
   "clientSessionId": "xxx-xxx-xxx-xxx",
   "action":"SWITCH",
   "topic":{
​      "name": "Topic Name"​
   },​
   "userId": "beth"​  
}

    Suporte a indicadores de digitação

    Você pode habilitar indicadores de digitação para usuários e agentes dinâmicos. Atualmente, os indicadores de digitação são exibidos da seguinte forma:
    • Exibido para o agente quando o usuário está digitando
    • Exibido para o usuário quando o bot está preparando uma resposta
    Quando o indicador de digitação está habilitado, a API Virtual Agent envia as ações StartTypingIndicator e EndTypingIndicatorna carga de resposta. Por exemplo:
    {​ 
        "uiType":"ActionMsg",​ 
        "actionType":"StartTypingIndicator"​ 
} ​
    Para enviar o indicador de digitação do usuário para um agente dinâmico, o cliente deve enviar a ação TYPING. Quando o usuário terminar de digitar, o cliente deverá enviar a açãoVIEWING.​ Por exemplo:
    {​ 
    "requestId": "xxxxxx-xxxxxx-xxxx-xxxx-xxxxxxxxxx",​ 
    "clientSessionId": "xxxxxxxx-xxxx",​ 
    "action": "TYPING/VIEWING",​ 
    "userId": "able.tuter",​ 
    "emailId": "abel.tuter@example.com",​ 
    "timezone":"Asia/Kolkata"​ 
}​
    Para habilitar indicadores de digitação, siga estas etapas.
    1. Navegue até Todos, e, em seguida, insira sys_cs_channel.list no filtro de navegação.
    2. Selecione o registro de bot para bot.
    3. Marque a caixa de seleção Indicador de digitação de suporte.
    4. Clique em Atualizar.