Recursos compatíveis em Virtual Agent API

  • Versão de lançamento: Australia
  • Atualizado 12 de mar. de 2026
  • 14 min. de leitura

    • Você pode usar o. Virtual Agent API para integrar muitos dos mesmos recursos que estão disponíveis em Virtual Agent e. Bate-papo do agente em seu ambiente de bate-papo. O suporte a recursos varia de acordo com seu ServiceNow e o número da versão do app da loja do Virtual Agent API.

    Para obter informações sobre os modelos de solicitação e de resposta para a API Virtual Agent, bem como exemplos de casos de uso comuns, consulte API Virtual Agent Bot Integration.

    Versão 4.3.0

    Suporte para bate-papo premium na API do Virtual Agent

    Versão 4.1.1

    Suporte para resposta sintetizada na API do Virtual Agent
    • Com resposta sintetizada habilitada por Now Assist experiência, Virtual Agent API envia a resposta com citações para o bot primário. As citações estão incluídas em citationsjuntamente com links de citação separados.
    • Aqui está um JSON de exemplo para resposta sintetizada com citações e links de citação:
      {
  "clientSessionId": "va_api_conv_16875",
  "score": 1,
  "interactionId": "0dce3e37ffe1f610f71affffffffff8a",
  "requestId": "1765195564288",
  "streamActive": false,
  "streamState": "END",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "feedback": {
        "messageId": "dcde7a7739e1f610beed69f9e5960355",
        "feedbackEnabled": true
      },
      "maskType": "NONE",
      "citations": [
        {
          "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33",
          "sysId": "24d9243187032100deddb882a2e3ec33",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "What is Spam?",
          "index": 0,
          "source": "internal",
          "category": "kb",
          "citationLabel": "What is Spam?",
          "table": "kb_knowledge",
          "citationRef": "[1]"
        },
        {
          "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2",
          "sysId": "0b48fd75474321009db4b5b08b9a71c2",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "How to Deal with Spam",
          "index": 1,
          "source": "internal",
          "category": "kb",
          "citationLabel": "How to Deal with Spam",
          "table": "kb_knowledge",
          "citationRef": "[2]"
        },
        {
          "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=3020c9b1474321009db4b5b08b9a712d",
          "sysId": "3020c9b1474321009db4b5b08b9a712d",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "What are phishing scams and how can I avoid them?\n\t\t",
          "index": 2,
          "source": "internal",
          "category": "kb",
          "citationLabel": "What are phishing scams and how can I avoid them?\n\t\t",
          "table": "kb_knowledge",
          "citationRef": "[3]"
        }
      ],
      "streamId": "4fcef677ffe1f610f71affffffffffee",
      "uiType": "OutputText",
      "messageId": "dcde7a7739e1f610beed69f9e5960355",
      "relatedList": [],
      "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often includes phishing scams, foreign bank scams, pyramid schemes, quack health products, pornographic site ads, offers for bulk emailing services, chain letters, and pirated software. Most reputable marketers do not use spam for advertising. To reduce spam:\n\n- Do not reply to spam, as it confirms your address to spammers.\n- Be cautious when sharing your email address online.\n- Adjust browser security settings to limit personal information exposure.\n- Avoid forwarding chain mail, as most are hoaxes.\n- Use judgment when unsubscribing or responding to unfamiliar sources \u200b[1]\u200b\u200b[2]\u200b.\n\nPhishing scams, a dangerous form of spam, attempt to trick you into revealing personal information by pretending to be legitimate organizations. Always verify requests for sensitive information and avoid clicking suspicious links \u200b[3]\u200b.\n\n[1] [What is Spam?](http://10.160.66.170:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33)\n[2] [How to Deal with Spam](http://10.160.66.170:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2)\n[3] [What are phishing scams and how can I avoid them?\n\t\t](http://10.160.66.170:8080/sp?id=kb_article&sys_id=3020c9b1474321009db4b5b08b9a712d)",
      "group": "DefaultText"
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}
    • Para obter mais informações, consulte Habilite a resposta sintetizada em Virtual Agent API.
    Suporte para resposta agentic na API do Virtual Agent
    • Virtual Agent API compatível com resposta agential por meio de Now Assist experiência. Com resposta agentiva habilitada em Virtual Agent API, as mensagens de saída são mostradas ao usuário como carregamento ou processamento.
    • Virtual Agent API envia mensagem para o bot primário por meio de um novo DynamicLoaderparâmetro.
    • Aqui está um exemplo JSON para resposta agentic:
      {
  "clientSessionId": "va_api_conv_16875",
  "score": 1,
  "interactionId": "0dce3e37ffe1f610f71affffffffff8a",
  "requestId": "1765195564288",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "progressMessages": [
        {
          "message": "Searched for relevant documents and actions",
          "status": "COMPLETED"
        },
        {
          "message": "Generated the response",
          "status": "COMPLETED"
        }
      ],
      "actionType": "DynamicLoader",
      "defaultHeader": "View AI Steps",
      "uiType": "ActionMsg",
      "parentMessageId": "87cef677ffe1f610f71affffffffff4d",
      "header": "View AI Steps",
      "messageId": "87cef677ffe1f610f71affffffffff4d",
      "shouldUpdateParentMessage": true
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}
    Suporte para fluxo de resposta na API do Virtual Agent
    • Virtual Agent API compatível com fluxo de resposta por Now Assist experiência. Para saber mais, consulte Habilitar Now Assist experiência em Virtual Agent API.
      Nota:
      O bot primário deve passar as respostas de streaming para o usuário final. Para obter mais informações, consulte Respostas de streaming de bate-papo.
    • Virtual Agent API compatível com os seguintes estados para fluxo de resposta:
      • INICIAR
        {
  "clientSessionId": "va_api_conv_16875",
  "requestId": "1762864530268",
  "streamActive": true,
  "streamState": "START",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "streamId": "cb928c9f53097e10f71a6dc230e5e639",
      "uiType": "StreamStart",
      "streamSequence": 1,
      "value": "Looking into your request"
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}
      • EM ANDAMENTO
        {
  "clientSessionId": "va_api_conv_16875",
  "requestId": "1762864530268",
  "streamActive": true,
  "streamState": "INPROGRESS",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "streamId": "cb928c9f53097e10f71a6dc230e5e639",
      "uiType": "StreamChunk",
      "streamSequence": 2,
      "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often"
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}
      • FIM
        {
  "clientSessionId": "va_api_conv_16875",
  "score": 1,
  "interactionId": "d592c89f53097e10f71a6dc230e5e68c",
  "requestId": "1762864530268",
  "streamActive": false,
  "streamState": "END",
  "message": {
    "typed": true,
    "text": "what is spam?"
  },
  "body": [
    {
      "feedback": {
        "messageId": "6f92cc9f34097e108001c582b67b2a1f",
        "feedbackEnabled": true
      },
      "maskType": "NONE",
      "citations": [
        {
          "citationHref": "http://192.168.29.27:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33",
          "sysId": "24d9243187032100deddb882a2e3ec33",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "What is Spam?",
          "index": 0,
          "source": "internal",
          "category": "kb",
          "citationLabel": "What is Spam?",
          "table": "kb_knowledge",
          "citationRef": "[1]"
        },
        {
          "citationHref": "http://192.168.29.27:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2",
          "sysId": "0b48fd75474321009db4b5b08b9a71c2",
          "icon": "sn_nowassist_va.source-kb-article.png",
          "header": "KB article",
          "description": "How to Deal with Spam",
          "index": 1,
          "source": "internal",
          "category": "kb",
          "citationLabel": "How to Deal with Spam",
          "table": "kb_knowledge",
          "citationRef": "[2]"
        }
      ],
      "streamId": "cb928c9f53097e10f71a6dc230e5e639",
      "uiType": "OutputText",
      "messageId": "6f92cc9f34097e108001c582b67b2a1f",
      "relatedList": [],
      "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often includes phishing scams, foreign bank scams, pyramid schemes, \"get rich quick\" offers, quack health products, ads for pornographic sites, offers for bulk emailing services, chain letters, and pirated software. To reduce spam:\n\n- Do not reply to spam, as it confirms your address to spammers.\n- Be cautious when sharing your email address online or with companies.\n- Adjust browser security settings to limit personal information exposure.\n- Avoid forwarding chain mail, as most are hoaxes \u200b[1]\u200b\u200b[2]\u200b.\n\n[1] [What is Spam?](http://192.168.29.27:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33)\n[2] [How to Deal with Spam](http://192.168.29.27:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2)",
      "group": "DefaultText"
    }
  ],
  "userId": "admin",
  "clientVariables": {
    "bot": {
      "id": "va-bot-12345"
    },
    "channelId": "postman"
  }
}
    • Habilite a transmissão em Virtual Agent API pela seguinte configuração:
      1. Certifique-se de que Permitir fluxo de resposta está selecionado em Now Assist em Virtual Agent. Para saber mais, consulte Habilite recursos de bate-papo adicionais.
      2. Navegue até Todos e insira sys_now_assist_channel_config.list no filtro de navegação.
      3. Em Now Assist Tabela de configuração de canal [now_assist_channel_config], defina o. Fluxo pronto valor do campo para verdadeiro Para dispositivo de bot para bot.
        Figura 1. Tabela de configurações do canal do Now Assist
        Defina o valor do campo Fluxo pronto como Verdadeiro para Dispositivo de bot para bot.
    Suporte para nova autenticação de saída

    Versão 4.0.0

    • Virtual Agent API atualiza o texto da mensagem e o status de entrega de mensagens entre o atendente e o bot primário.

    • Virtual Agent API Envia o ID de interação e o ID da mensagem (ID do agente para conversas com o atendente) em resposta ao bot primário.

      O registro de interação armazena o. clientSessionIdparâmetro enviado pela aplicação de bate-papo de terceiros compatível (ou pelo bot primário) para cada uma de suas conversas com o usuário final. Para saber mais, consulte Configure o registro de interação para armazenar clientSessionId em Virtual Agent API.

    • O histórico de bate-papo da conversa do bot primário com o usuário final inclui o carimbo de data/hora de mensagens individuais. Os atendentes agora podem ver esse histórico de bate-papo em mensagens individuais ou em um único bloco. Para saber mais, consulte Configure para oferecer suporte ao histórico de bate-papo em Virtual Agent API. Você pode personalizar sua interface de bate-papo do agente definindo um logotipo para o bot primário que aparece no histórico de bate-papo. Para obter mais informações, consulte Logotipo de configuração do bot primário em Virtual Agent API.

    Versão 3,0.x

    Melhorias do bate-papo do agente na versão 3.14.3
    • Quando o bot primário transfere um bate-papo para um atendente, Virtual Agent API Envia 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 do 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.
    Suporte para a experiência do Now Assist
    Suporte para configurar várias aplicações de provedor
    • Virtual Agent API permite a configuração de várias aplicações de provedor para oferecer suporte a casos de uso em que há vários bots primários usando Virtual Agent API e você precisa distinguir entre eles.
    • Para obter mais informações, consulte Configurar várias aplicações do provedor.
    Suporte para transformação de solicitação e resposta da API do Virtual Agent
    • Virtual Agent API compatível com a transformação de cargas de solicitação e resposta de ida e volta Virtual Agent API. Isso é útil nos casos em que o bot primário tem um modelo de resposta comum em todos os bots secundários.
    • Para obter mais informações, consulte Transformação Virtual Agent API solicitação e resposta.
    Carregamentos de arquivos seguros a partir de um URL privado
    • 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 .
      • A autenticação básica ou OAuth é compatível, mas a Autenticação de mensagem não é.
    • 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"
  }
}
    Sinalizador de suporte para silentMessage
    • Uma mensagem silenciosa é uma mensagem que não requer uma resposta. Se Virtual Agent recebe uma solicitação com silentMessage=true, todas as mensagens de bot subsequentes serão suprimidas até Virtual Agent recebe 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.
    Suporte para mensagens de ação
    • Além de passar mensagens para um ServiceNow® Virtual Agent o bot secundário, o bot primário ou o cliente de bate-papo pode passar mensagens para um agente por meio do 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:
      Tabela 1. Tipos de mensagem de ação compatíveis
      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.
      StartSpinner Mensagem de saída que inicia um girador 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 girador que foi enviado anteriormente.
      IndicaçãoIniciarTypingActionMsg 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.
      AssinarPresênciaBate-Bate-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 Agent alterna 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.
    Aprimoramentos de handshake síncrono
    • Virtual Agent API pode transferir para um atendente de forma síncrona. Quando um usuário ou agente termina uma conversa, o transfere de volta para Virtual Agent també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 Agent endpoint de resposta. Bate-papo do agente as mensagens serão entregues ao 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 API envia 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 . Utilitário de ação e o. Pausar bloco de tópicos .
    • Para desabilitar esses recursos e habilitar o suporte síncrono, consulte Habilite o suporte síncrono em Virtual Agent API.
    Erros de troca de tópicos e solução de problemas aprimorados
    • 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 Agent nã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.
    • Se a troca de tópicos falhar, Virtual Agent API responde 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 Framework > Logs do sistema > Erros).
    Tempo de resposta da API do Virtual Agent aprimorado
    • Virtual Agent API As respostas incluem parâmetros como Assumir controle e Pontuação de NLU. Esses parâmetros são processados durante a preparação da resposta.
    • A partir da versão 3,9.0, você pode excluir os parâmetros Assumir controle e/ou Pontuação de NLU do Virtual Agent API resposta para melhorar o tempo de resposta.
    • Para excluir os parâmetros Assumir controle e Pontuação de NLU do Virtual Agent API resposta, conclua as seguintes etapas:
      1. Navegar até Tudo > sys_cs_custom_adapter_property.list.
      2. Pesquisar enable_take_controle. send_nlu_scorepropriedades.
      3. Defina o valor de enable_take_controlPropriedade como falso para excluir a configuração Assumir controle e. send_nlu_scorePropriedade como falso para excluir o cálculo de pontuação de NLU durante o processamento da resposta. Por padrão, essas propriedades são definidas como verdadeiras.
    Encerrando conversas abandonadas do Virtual Agent
    • Se uma conversa estiver incompleta devido a um erro, Virtual Agent pode 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 .
    • 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
}