---
sourceDocument: Interfaces conversacionais do Xanadu
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/xanadu/conversational-interfaces

 Release :

    - xanadu

ft:locale :

    - pt-BR

ft:publication_title :

    - Interfaces conversacionais do Xanadu

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

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

# Recursos de Virtual Agent API disponíveis na versão na Store 3.0.x {#ariaid-title1}

* Versão de lançamento: Xanadu
* 
* Atualizado 1 de ago. de 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 min. de leitura

A Virtual Agent API versão 3.0.x fornece acesso a mais dos mesmos recursos que estão disponíveis em Virtual Agent e Bate-papo do agente, incluindo a capacidade de carregar arquivos de um URL privado e melhorias de sincronia.

## Finalizar conversas Virtual Agent abandonadas {#va-api-features-v3__section_y1m_khj_dsb}

Se uma conversa estiver incompleta devido a um erro, Virtual Agent poderá solicitar que o bot primário assuma o controle. Se o sinalizador takeControl for true, Virtual Agent (como o bot secundário) fechará a conversa automaticamente. Se o bot primário quiser iniciar uma conversa, ele poderá enviar a seguinte mensagem de ação: `"hi"/START_CONVERSATION`.  
Você pode solicitar que o bot primário assuma o controle nas seguintes situações:

* Tempo limite de ociosidade: o estado de interação é Encerrado e abandonado. O motivo do estado é Nenhuma atividade.
* Problemas técnicos: o estado de interação é Encerrado e abandonado. O motivo do estado é Problemas de bot.
* Entrada de usuário inválida: o estado da interação é Encerrado e abandonado. O motivo do estado é Entrada de usuário inválida.
{#va-api-features-v3__ul_zts_y3j_dsb}

Para solicitar que o bot primário assuma o controle, envie o sinalizador takeControl no corpo da carga para o bot primário com um valor de true.  
Exemplo de carga da mensagem:

    {​ 
       "requestId": "xxxx-xxxx-xxxx-xxxx",
       "clientSessionId": "xxx-xxx-xxx-xxx",
       "message": {
           "text":"invalid3",
           "typed":true
           }
       "body":[{
           "uiType":"OutputText",
           "group":"DefaultText",
           "value":"Sorry, I didn't get that. Could you help me by answering this?"
           },
           {
           "uiType":"Boolean",
           "group":"DefaultPicker",
           "required":true,
           "nluTextEnabled": false,
           "label":"Choose a value",
           "options":[
              {"label":"Yes"},
              {"label":"No"}
              ]
           }],
        "takeControl":true,
        "score":0
    } 

## Erros de alternância de tópico e solução de problemas aprimorados {#va-api-features-v3__section_b3w_cks_2rb}

A alternância de tópicos pode falhar por qualquer um dos seguintes motivos:

* A solicitação inclui o nome do tópico e a ID do tópico (descoberta de tópico por palavra-chave) ou o nome da intenção do tópico e a ID da intenção do tópico (descoberta de tópico NLU). Especifique um ou outro.
* A solicitação inclui um tópico ou nome de intenção ou ID inválido.
* O nome ou ID do tópico/intenção é válido, mas Virtual Agent não pode executá-lo porque é inativo ou não é um tópico. Por exemplo, se o nome ou ID se referir a um bloco de tópico ou objeto de controle personalizado.
* O tópico solicitado já está em execução.
* O tópico solicitado é válido, mas uma condição de segurança está impedindo o acesso. Por exemplo, o tópico pode não ter permissão para ser executado no canal ou alguma outra condição de controle de acesso pode ser aplicada.
{#va-api-features-v3__ul_ekg_rnt_2rb}  
Se a alternância de tópicos falhar, a Virtual Agent API responderá das seguintes maneiras, quer você esteja usando de forma síncrona ou assíncrona:

* Se a alternância de tópico falhar, a conversa será encerrada com uma mensagem informando que a conversa não pode continuar. A conversa não permanecerá mais em um estado aberto.
* A solicitação anterior é marcada como processada para que uma nova solicitação possa ser feita sem aguardar um tempo limite.
* O motivo da falha é registrado na tabela de log do sistema (Automated Test FrameworkLogs do sistemaErros).
{#va-api-features-v3__ul_xzw_wqt_2rb}

## Aprimoramentos de handshake síncrono {#va-api-features-v3__synchronous_support_enhancements}

A partir da versão 3.0.x, a Virtual Agent API pode ser transferida para um atendente de forma síncrona. Quando um usuário ou agente termina uma conversa, a transferência de volta para Virtual Agent também é feita de forma síncrona. Algumas mensagens do sistema e mensagens de tempo de espera também são enviadas de forma síncrona.  
Para usar a transferência síncrona para um agente dinâmico, esteja ciente das seguintes diretrizes:

* Configure o endpoint de resposta Virtual Agent. Bate-papo do agente mensagens serão entregues no endpoint que você especificar.
* Você deve desativar manualmente as notificações da instância.
* Se você estiver usando a transferência síncrona para um atendente, a Virtual Agent API enviará o indicador de digitação se estiver habilitado:

      {
        "uiType": "ActionMsg",
        "actionType": "StartTypingIndicator",
      }

* Os tópicos que usam os seguintes recursos não são compatíveis com o modo síncrono: [carregamento de arquivo](https://servicenow-prod.fluidtopics.net/SJmABV7W8HbB9xgn07_p4A "Use a coleção de controles de entrega fornecida por Designer do Virtual Agent para solicitar e capturar informações do usuário em uma conversa."), o [Utilitário de ação](https://servicenow-prod.fluidtopics.net/~FcrobCJkzR88ts0nSc7pg "Use o utilitário Ação em um tópico Virtual Agent para selecionar as propriedades de ação de fluxo que o nó deve criar. O utilitário Ação integra Virtual Agent com o produto ServiceNow Workflow Studio.") e [Pausar bloco de tópicos](https://servicenow-prod.fluidtopics.net/m6adthHDPEXvpUQFthWztQ "Virtual Agent fornece blocos de tópico pré-criados que os autores ou administradores do tópico podem usar para executar funções ou tarefas específicas da plataforma em conversas de bot. Por exemplo, determinados blocos de tópico permitem que você verifique a disponibilidade do agente ou gere Pesquisa com IA resultados.").
{#va-api-features-v3__ul_pmt_p2s_2rb}  
Para desabilitar esses recursos e habilitar o suporte síncrono, siga estas etapas:

1. Navegar até Todossys_cs_channel.list.
2. Selecione o registro de bot para bot.
3. Desmarque a caixa de seleção Habilitar notificações para desabilitá-la.
4. Se você não for transferir para um agente em tempo real no modo síncrono, desmarque a caixa de seleção Indicador de digitação de suporte para desabilitá-lo.
5. Marque a caixa de seleção Síncrono.  
   Figura 1. Canal de bot para bot com suporte síncrono habilitado
6. Clique em Atualizar.
{#va-api-features-v3__ol_icm_x3j_gqb}

## Suporte para mensagens de ação {#va-api-features-v3__section_c4v_wr3_dsb}

Além de passar mensagens para um bot secundário ServiceNow® Virtual Agent, o bot primário ou o cliente de bate-papo pode passar mensagens para um agente por meio de Bate-papo do agente. Use o parâmetro action passado no corpo da solicitação para especificar como o conteúdo deve ser tratado.  
A Virtual Agent API oferece suporte aos seguintes tipos de mensagem de ação:{#va-api-features-v3__table_g3b_cyp_dsb__entry__2}

| Valor actionType | Descrição |
|-|-|
| ChatSubHeader | Mensagem de saída indicando um dos seguintes eventos: * Falha de tradução dinâmica. * O piloto automático do atendente foi iniciado e concluído. {#va-api-features-v3__ul_kmy_xcg_hsb} |
| StartSpinner | Mensagem de saída que inicia um botão giratório quando uma mensagem está no estado pendente devido a processos assíncronos, como Pesquisa com IA ou o filtro de linguagem obscena. |
| EndSpinner | Mensagem de saída que interrompe o controle giratório que foi enviado anteriormente. |
| StartTypingIndicatorActionMsg | Mensagem de saída indicando que um usuário ou agente começou a digitar (depois que um agente aceitou o bate-papo). |
| EndTypingIndicatorActionMsg | Mensagem de saída indicando que um usuário ou agente parou de digitar. |
| SubscribeToSupportQueue | Indica que a conversa está definida para a fila de suporte. |
| SubscribeToChatPresence | Mensagem de saída indicando que uma conversa ao vivo com o agente foi iniciada. |
| SwitchToLiveAgent | Mensagem de saída indicando que um atendente aceitou a conversa. |
| SwitchToVirtualAgent | Mensagem de saída indicando que a sessão do agente em tempo real foi encerrada e a conversa foi retornada para Virtual Agent. |
| SwitchConversation | Mensagem de saída indicando que uma notificação foi enviada. Isso cria uma nova conversa, portanto, Virtual Agent alterna para a nova conversa. |
| Sistema | Mensagem de saída indicando um dos seguintes: * Um atendente entrou no bate-papo. * O atendente ou o usuário fechou o bate-papo. * A conversa com um atendente expirou. {#va-api-features-v3__ul_bdd_nlq_dsb} |
[Tabela 1. Tipos de mensagens de ação compatíveis]

{#va-api-features-v3__table_g3b_cyp_dsb}

## Suporte para o sinalizador silentMessage {#va-api-features-v3__section_t1b_lrq_dsb}

Uma mensagem silenciosa é uma mensagem que não requer uma resposta. Se Virtual Agent receber uma solicitação com silentMessage=true, todas as mensagens de bot subsequentes serão suprimidas até que Virtual Agent receba uma solicitação para desativar o modo silencioso (silentMessage=false).  
Exemplo de carga de mensagem do bot primário:

    { 
       "token": "BOT_TOKEN",
       "botToBot": true,
       "clientSessionId": "884502214730301027f83ee4070f589a",
       "clientVariables": {},
       "requestId": "48450221d23030107300b7756770bc9b",
       "silentMessage": "true",
       "timestamp": 1623916324820,
       "timezone": "GMT",
       "userId": "abel.tuter",
       "emailId": "abel.tuter@example.com" 
    }

Nota:  
Se silentMessage=true, as notificações não serão entregues.

## Carregamentos de arquivo seguros de um URL privado {#va-api-features-v3__section_xjy_j12_2rb}

A Virtual Agent API oferece suporte a carregamentos de arquivo de até 1 GB de um URL privado. O bot primário deve passar o ID do usuário, o ID da aplicação do provedor opcional e o nome do arquivo. Observe as seguintes diretrizes:

* O ID da aplicação do provedor é opcional.
* O ID do usuário e o ID da aplicação do provedor devem ser enviados antes do nome do arquivo na carga.
* O usuário final deve ter uma função especificada na propriedade glide.attachment.role. Para obter mais informações, consulte [Exigir uma função para anexar arquivos](https://www.servicenow.com/docs/access?context=t_DisablingTheDragAndDropFeature&version=xanadu&pubname=xanadu-platform-administration&ft:locale=en-US).
* A autenticação básica ou OAuth é compatível, mas a autenticação de mensagem não é.
{#va-api-features-v3__ul_dvc_vn2_2rb}  
Exemplo de carga de mensagem do bot primário:

    curl -X POST \
      https://instance.service-now.com/api/now/v1/cccif/media/upload \
      -H 'authorization: Basic YWRtaW46YWRtaW4=' \
      -H 'content-type: multipart/form-data; \
      -F user_id=xxxxxx \
      -F provider_application_id=optionalId \
      -F 'file=@SomeFile.png'

A Virtual Agent API envia o seguinte JSON de exemplo:

    {
      "result": {
        "mediaUrl": "http://123.456.7.8:8080//api/now/v1/cs/media/string",
        "name":"imagefile.png",
        "state":"pending",
        "attachmentId":"abcdefghijklmno12345"
      }
    }