---
sourceDocument: Interfaces conversacionais de Yokohama
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/yokohama/conversational-interfaces

 Release :

    - yokohama

ft:locale :

    - pt-BR

ft:publication_title :

    - Interfaces conversacionais de Yokohama

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# Virtual Agent API Recursos disponíveis na versão Store 3,0.x

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

* Versão de lançamento: Yokohama
* 
* Atualizado 30 de jan. de 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 6 min. de leitura

Virtual Agent APIa versão 3,0.x fornece acesso a mais dos mesmos recursos que estão disponíveis em Virtual Agente. Bate-papo do agente, Incluindo a capacidade de carregar arquivos de um URL privado e aprimoramentos de handshake síncrono.

## Encerrado abandonado Virtual Agentconversas {#va-api-features-v3__section_y1m_khj_dsb}

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

* Tempo limite ocioso: O estado de interação é Encerrado abandonado . O motivo do estado é Nenhuma atividade .
* Problemas técnicos: O estado de interação é Encerrado abandonado . O motivo do estado é Problemas de bot .
* Entrada de usuário inválida: O estado de interação é Encerrado 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. takeControlsinalizador no corpo da carga para o bot primário com um valor de true.  
Carga de mensagem de exemplo:   

    {​ 
       "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 troca de tópicos e solução de problemas aprimorados {#va-api-features-v3__section_b3w_cks_2rb}

A troca de tópicos pode falhar por qualquer um dos seguintes motivos:

* A solicitação inclui o nome do tópico e o ID do tópico (descoberta de tópico de palavra-chave) ou o nome da intenção do tópico e o 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 ou ID de intenção inválido.
* O nome ou ID do tópico/intenção é válido, mas Virtual Agentnão é possível executá-lo porque está inativo ou não é um tópico. Por exemplo, se o nome ou ID se referir a um bloco de tópicos ou ativo 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 troca de tópicos falhar, Virtual Agent APIresponde das seguintes maneiras, independentemente de você usá-lo de forma síncrona ou assíncrona:

* Se a troca 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, Virtual Agent APIpode transferir para um atendente de forma síncrona. Quando um usuário ou agente termina uma conversa, o transfere de volta para Virtual Agenttambém é feito 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 atendente, esteja ciente das seguintes diretrizes:

* Configure o. Virtual Agentendpoint de resposta. Bate-papo do agenteas mensagens serão entregues no endpoint especificado.
* Você deve desativar manualmente as Notificações da instância.
* Se você estiver usando transferência síncrona para um atendente, Virtual Agent APIenvia 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 no modo síncrono: [carregamento de arquivo](https://servicenow-prod.fluidtopics.net/Rwp03gWqB~lzBK~VXQ3APg "Use a coleção de controles de entrada fornecida por Designer do Virtual Agentpara solicitar e capturar informações do usuário em uma conversa."). [Utilitário de ação](https://servicenow-prod.fluidtopics.net/mZARBJwOiJ9T1hAkfekh7g "Use o utilitário Ação em um Virtual Agenttópico para selecionar as propriedades da ação de fluxo que o nó deve criar. O utilitário Ação se integra Virtual Agentcom o. ServiceNow Workflow Studioproduto.")e o. [Pausar bloco de tópicos](https://servicenow-prod.fluidtopics.net/auOsQQoPvm3_w3ewte3CFQ "Virtual Agent fornece blocos de tópicos pré-criados que os autores ou administradores de tópicos podem usar para executar funções ou tarefas específicas relacionadas à plataforma em conversas de bot. Por exemplo, determinados blocos de tópicos permitem que você verifique a disponibilidade do agente ou gere Pesquisa com IAresultados.").
{#va-api-features-v3__ul_pmt_p2s_2rb}  
Para desabilitar esses recursos e habilitar o suporte síncrono, siga estas etapas:

1. Navegar até Tudosys_cs_channel.list.
2. Selecione o registro de bot para bot.
3. Limpe o. Habilitar notificações para desabilitá-la.
4. Se você não for transferir para um atendente no modo síncrono, limpe Indicador de digitação de suporte para desabilitá-la.
5. Selecione Síncrono caixa de seleção.  
   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 ServiceNow® Virtual Agentbot secundário, 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. actionparâmetro passado no corpo da solicitação para especificar como o conteúdo deve ser tratado.  
Virtual Agent API compatível com os seguintes tipos de mensagem de ação:{#va-api-features-v3__table_g3b_cyp_dsb__entry__2}

| Valor actionType | Descrição |
|-|-|
| Subcabeçalho do Chat | Mensagem de saída indicando que ocorreu uma das seguintes situações: * Falha na 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 girador quando uma mensagem está no estado pendente devido a processos assíncronos, como Pesquisa com IAou o filtro de linguagem obscena. |
| EndSpinner | Mensagem de saída que interrompe o girador que foi enviado anteriormente. |
| IndicadorTipoIniciarActionMsg | Mensagem de saída indicando que um usuário ou agente começou a digitar (depois que um agente aceitou o bate-papo). |
| EndTypingIndicadorActionMsg | Mensagem de saída indicando que um usuário ou agente parou de digitar. |
| AssinarToSupportQueue | Indica que a conversa está definida para a fila de suporte. |
| AssinarPresença do Bate-papo | Mensagem de saída indicando que uma conversa do atendente foi iniciada. |
| AlternaLiveAgent | Mensagem de saída indicando que um atendente aceitou a conversa. |
| SwitchToVirtualAgent | Mensagem de saída indicando que a sessão do atendente foi encerrada e que 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 Agentalterna para a nova conversa. |
| Sistema | Mensagem de saída indicando um dos seguintes itens: * Um atendente entrou no gato. * O atendente ou o usuário fecharam o bate-papo. * O tempo limite da conversa com um atendente expirou. {#va-api-features-v3__ul_bdd_nlq_dsb} |
[Tabela 1. Tipos de mensagem de ação compatíveis]

{#va-api-features-v3__table_g3b_cyp_dsb}

## Sinalizador de suporte para silentMessage {#va-api-features-v3__section_t1b_lrq_dsb}

Uma mensagem silenciosa é uma mensagem que não requer uma resposta. Se Virtual Agentrecebe uma solicitação com silentMessage=true, todas as mensagens de bot subsequentes serão suprimidas até Virtual Agentrecebe uma solicitação para desativar o modo silencioso ( silentMessage=false).  
Carga de mensagem de exemplo 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 foram entregues.

## Carregamentos de arquivos seguros a partir de um URL privado {#va-api-features-v3__section_xjy_j12_2rb}

Virtual Agent API Compatível com carregamentos de arquivos 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 no glide.attachment.rolepropriedade. Para obter mais informações, consulte [Uma função é necessária para anexar arquivos](https://www.servicenow.com/docs/access?context=t_DisablingTheDragAndDropFeature&version=yokohama&pubname=yokohama-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}  
Carga de mensagem de exemplo 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'

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"
      }
    }

## Aprimoramentos do Bate-papo do agente em Virtual Agent APIversão 3.14.3 {#va-api-features-v3__section_qft_pcv_c2c}

* Quando o bot primário transfere um bate-papo para um atendente, Virtual Agent APIEnvia o ID do agente, além do nome do agente e avatar, para o bot primário.
* Virtual Agent API envia o histórico de bate-papo do bot primário para o atendente em qualquer lugar na solicitação durante uma conversa em andamento. Este comportamento é controlado pela seguinte propriedade do sistema: Allow_storeing_history_in_ongoing-conversation. Defina o valor da propriedade como verdadeiro para enviar o histórico de bate-papo em qualquer lugar na solicitação.
* O registro de interação contém a transcrição do histórico de bate-papo junto com o carimbo de data/hora de mensagens individuais.
{#va-api-features-v3__ul_fd3_rcv_c2c}