API de integração de bots do Virtual Agent
A API de integração de bots do Virtual Agent fornece endpoints que permitem aos usuários integrar qualquer interface de bate-papo ou um ecossistema de bots com ServiceNow Virtual Agent e/ou Atendente.
Esta API foi criada na estrutura de integração de bate-papo personalizada de conversação fornecida com Virtual Agent e opera no namespace sn_va_as_service.
Para obter informações adicionais sobre como instalar e configurar a API de integração de bots Virtual Agent, consulte API do Virtual Agent.
VA Bot Integration - POST /sn_va_as_service/bot/integration
Envia uma mensagem, anexo ou URL especificado para um bot secundário ServiceNow Virtual Agent (VA) especificado.
O site de um cliente pode ter um ou mais bots secundários ServiceNow. Além de passar mensagens para um ServiceNow bot secundário do VA, o bot primário ou o cliente de bate-papo pode usar este endpoint para passar mensagens para um agente por meio do Atendente bate-papo. Use o parâmetro action passado no corpo da solicitação para especificar como o conteúdo especificado deve ser tratado.
Formato de URL
URL padrão: /api/sn_va_as_service/bot/integration
Parâmetros de solicitação compatíveis
| Nome | Descrição |
|---|---|
| Nenhum |
| Nome | Descrição |
|---|---|
| Nenhum |
| Nome | Descrição |
|---|---|
| ação | Ação que o VA deve executar. Valores válidos:
Tipo de dados: cadeia de caracteres Padrão: nulo |
| botToBot | Sinalizador que indica se a conversa é entre bots, como entre um bot primário e um bot secundário. Valores possíveis:
Tipo de dados: booliano Padrão: verdadeiro |
| clientSessionId | Identificador de sessão de cliente exclusivo da aplicação/serviço que o usuário final está usando para se comunicar com o bot ServiceNow. Este ID ajuda a identificar o conjunto de solicitações/respostas para uma conversa de usuário específica. O formato deste parâmetro é determinado pelo implementador. Tipo de dados: cadeia de caracteres Padrão: nulo |
| clientVariables | Passagem de pares de nome-valor no formato JSON que são enviados de volta na resposta. Esses valores não são processados pelo endpoint, mas podem ser usados para manter informações específicas do cliente anexadas à conversa. Tipo de dados: objeto Padrão: nulo |
| Variáveiscontexto | Pares de nome-valor no formato JSON que fornecem informações adicionais sobre o usuário. Forneça essas informações para personalizar a experiência de conversa. Para obter informações adicionais sobre variáveis de contexto, consulte Definir e publicar variáveis de contexto de bate-papo. Por exemplo: Tipo de dados: objeto Padrão: nulo |
| ID de e-mail | Obrigatório ao habilitar a vinculação de conta, caso contrário, todos os usuários serão considerados usuários convidados. Endereço de e-mail do usuário final do cliente de bate-papo, a pessoa com quem o bot está interagindo. Para obter informações adicionais sobre vinculação de conta, consulte Vincular sua conta de usuário da ServiceNow a um aplicativo de mensagens para conversas do Virtual Agent. Tipo de dados: cadeia de caracteres |
| histórico | Histórico da conversa do bot primário com o usuário, começando com a solicitação inicial do usuário. Tipo de dados: objeto Por exemplo: |
| histórico.displayName | Nome do usuário para o qual a mensagem foi enviada. Se for o bot primário, passe Bot. Tipo de dados: cadeia de caracteres |
| histórico.éMensagemDeBot | Sinalizador que indica se a mensagem foi enviada pelo bot primário. Valores válidos:
Tipo de dados: booliano |
| histórico.tipo | Tipo de mensagem enviada. Valores válidos: texto Tipo de dados: cadeia de caracteres |
| histórico.valor | Conteúdo das informações. Por exemplo, o texto da mensagem. Tipo de dados: cadeia de caracteres |
| intenção | Descreve a intenção da conversa. Forneça essas informações quando o parâmetro action estiver definido como SWITCH.Tipo de dados: objeto |
| intent.id | NLU ID da intenção do tópico do sistema para o qual alternar a conversa. Localizado na tabela Idioma do tópico de CS [sys_cs_topic_language]. O intent.id é resolvido com base no idioma informado na sessão de bate-papo. Se nenhum idioma for aprovado ao iniciar uma conversa, ele obterá o idioma da sessão/perfil do usuário. Tipo de dados: cadeia de caracteres |
| message | Obrigatório. Detalhes da mensagem a serem enviados para o bot ServiceNow. Tipo de dados: objeto |
| mensagem.anexo | Obrigatório ao enviar um anexo. Detalhes do anexo. Você só pode passar anexos como um URL e somente um anexo pode ser passado por chamada. Uma verificação de vírus é acionada em todos os anexos. Tipo de dados: objeto |
| message.attachment.clientAttachmentId | Identificador exclusivo do anexo a ser enviado para o bot ServiceNow. O formato deste identificador é determinado pelo implementador. Tipo de dados: cadeia de caracteres Padrão: nulo |
| message.attachment.contentType | Obrigatório se o anexo for especificado. Tipo de mime padrão do anexo. Valores válidos (sem distinção entre maiúsculas e minúsculas):
Tipo de dados: cadeia de caracteres |
| message.attachment.fileName | Obrigatório se o anexo for especificado. Nome do arquivo do anexo. Tipo de dados: cadeia de caracteres |
| cabeçalhos.anexo.mensagem | Informações adicionais necessárias se o arquivo de anexo for privado e protegido. Tipo de dados: objeto |
| message.attachment.headers.Autorização | Informações necessárias para obter autorização para acessar o anexo, como nome de usuário e senha. Tipo de dados: cadeia de caracteres |
| message.attachment.url | Obrigatório se o anexo for especificado. URL onde o anexo está localizado. O VA obtém o anexo deste URL, executa uma verificação de vírus e processa o arquivo. Se o anexo não for um arquivo público, você deverá passar um objeto message.attachment.header que contenha as informações de autorização para que o anexo possa ser acessado. Você também deve garantir que o domínio da URL esteja presente nos domínios confiáveis arquivados em sys_cs_provider. Tipo de dados: cadeia de caracteres |
| message.clientMessageId | Identificador alfanumérico exclusivo da mensagem. O formato deste identificador é determinado pelo implementador. Tipo de dados: cadeia de caracteres Padrão: nulo |
| mensagem.texto | Obrigatório se o parâmetro attachment não for especificado. Texto da mensagem. O idioma da mensagem deve ser passado no parâmetro contextVariables. Tipo de dados: cadeia de caracteres Tamanho máximo: Ilimitado |
| mensagem.digitada | Obrigatório. Sinalizador que indica se a mensagem foi digitada ou foi uma seleção de opção (selecionada). Valores válidos:
Tipo de dados: booliano |
| requestId | Obrigatório. Identificador alfanumérico exclusivo para esta solicitação. O formato deste identificador é determinado pelo implementador. Tipo de dados: cadeia de caracteres |
| SilenciosoMensagem | Sinalizador que indica se esta é uma mensagem silenciosa. Uma mensagem silenciosa é uma mensagem que não requer uma resposta. Valores válidos:
Nota: Se uma solicitação com silenciaMessage = verdadeiro for enviada, todas as mensagens de bot subsequentes permanecerão suprimidas até que uma solicitação para desativar o modo silencioso seja enviada aprovando silenciaMessage = falso.Tipo de dados: booliano Padrão: falso |
| timestamp | Hora da época do Unix em que a mensagem foi enviada pelo usuário final do cliente de bate-papo. Tipo de dados: número Unidade: milissegundos Padrão: hora atual |
| fuso horário | Fuso horário GMT do usuário final do cliente de bate-papo. Por exemplo: Para obter uma lista dos valores de fuso horário disponíveis, consulte https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. Tipo de dados: cadeia de caracteres Padrão: fuso horário GMT da instância ServiceNow. |
| tópico | Obrigatório se o usuário quiser alternar para um tópico específico especificando um nome de tópico. Par de nome-valor do tópico para o qual alternar. Você pode especificar o nome do tópico ou o tópico sys_id. Nota: Você só pode especificar um único nome de tópico ou ID no objeto. Tipo de dados: objeto Por exemplo: |
| topic.name | Nome do tópico para o qual alternar. Localizado no campo de nome da tabela de tópicos do Virtual Agent [sys_cs_topic]. Tipo de dados: cadeia de caracteres |
| topic.id | Sys_id do tópico para o qual alternar. Localizado no campo sys_id da tabela de tópicos do Virtual Agent [sys_cs_topic]. Tipo de dados: cadeia de caracteres |
| userId | Obrigatório. Identificador de usuário exclusivo. Este é o identificador do usuário final que está interagindo com o bot. Tipo de dados: cadeia de caracteres |
Cabeçalhos
Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.
| Cabeçalho | Descrição |
|---|---|
| Aceitar | Formato de dados do corpo da resposta. Oferece suporte somente a application/json. |
| Tipo de conteúdo | Formato de dados do corpo da solicitação. Oferece suporte somente a application/json. |
| token | Obrigatório se estiver usando autenticação baseada em token; opcional para autenticação básica ou OAuth. Token de autenticação a ser usado se a autenticação de token tiver sido configurada para este endpoint. Tipo de dados: cadeia de caracteres |
| Cabeçalho | Descrição |
|---|---|
| Nenhum |
Códigos de status
Os códigos de status a seguir se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP da REST API.
| Código de status | Descrição |
|---|---|
| 200 | Bem-sucedido. A solicitação foi processada com sucesso. Se você receber um código de status 200, mas não receber uma resposta de volta, verifique o seguinte:
|
| 400 | Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada. |
| 401 | Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas. |
| 405 | Método inválido. A funcionalidade está desabilitada. |
| 500 | Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro. |
Parâmetros do corpo da resposta
Status da chamada do endpoint. Isso é enviado em resposta quando a solicitação de chamada inicial é recebida. A solicitação ainda não foi processada.
| Nome | Descrição |
|---|---|
| Erro | Descrição do erro detectado. Retornado somente se ocorrer um erro. Tipo de dados: objeto |
| erro.detalhe | Detalhes sobre o erro encontrado. Tipo de dados: cadeia de caracteres |
| erro.mensagem | Mensagem de erro lançada. Tipo de dados: cadeia de caracteres |
| status | Status da chamada do endpoint. Valores válidos:
Tipo de dados: cadeia de caracteres |
Parâmetros do corpo da resposta do VA
Corpo da resposta enviado do VA para o endpoint de resposta configurado.
| Nome | Descrição |
|---|---|
| Bate-papo do agente | Sinalizador que indica se a conversa está conectada ao ServiceNow Atendente. Valores possíveis:
Tipo de dados: booliano |
| corpo | Lista de objetos que descrevem os elementos do corpo da mensagem de resposta. Tipo de dados: matriz |
| corpo.açãoTipo | Tipo de mensagem de ação expedida pelo bot secundário para o bot primário. Por exemplo, digitar indicador ou tempo de espera do agente. Valores válidos:
Por exemplo: Enviando Enviando Tipo de dados: cadeia de caracteres |
| corpo.Infodoagente | Se habilitado na configuração do bate-papo do agente, o nome e o avatar do agente associado. Tipo de dados: objeto Por exemplo: |
| corpo.agentInfo.agentAvatar | URL do arquivo de avatar associado do agente. Por exemplo: "https://instance.servicenow.com/ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" Tipo de dados: cadeia de caracteres |
| body.agentInfo.agentName | Nome de exibição do agente. Tipo de dados: cadeia de caracteres |
| body.agentInfo.sentFromAgent | Sinalizador que indica se a mensagem foi enviada por um atendente. Valores possíveis:
Tipo de dados: booliano |
| dados.corpo | Cadeia de caracteres JSON que define os dados no cartão. Tipo de dados: cadeia de caracteres |
| grupo.corpo | Grupo de controle avançado ao qual o elemento do corpo pertence. Você pode transformar ainda mais esses controles padrão gravando scripts de transformação de saída. Para obter informações adicionais sobre esses scripts, consulte Scripts de ação do Virtual Agent. Valores possíveis:
Tipo de dados: cadeia de caracteres |
| corpo.cabeçalho | Cabeçalho do link. Tipo de dados: cadeia de caracteres |
| corpo.altura | Altura do elemento HTML. Tipo de dados: número Unidade: pixels |
| corpo.itemTipo | Tipo de elemento do corpo. Valores possíveis: (diferencia maiúsculas de minúsculas)
Tipo de dados: cadeia de caracteres |
| rótulo.corpo | Rótulo a ser exibido para o elemento associado. Tipo de dados: cadeia de caracteres |
| body.maskType | Indica a confidencialidade dos dados associados. Valores possíveis:
Tipo de dados: cadeia de caracteres |
| corpo.maxCount | Retornado somente quando uiType for FileUpload. Número máximo de anexos que podem ser carregados de uma só vez.Tipo de dados: número (inteiro) |
| corpo.maxSize | Retornado somente quando uiType for FileUpload. Tamanho máximo do anexo que pode ser carregado.Tipo de dados: número (inteiro) Unidade: megabytes |
| corpo.mensagem | Retornado somente quando actionType for StartSpinner. Mensagem a ser exibida para o usuário.Tipo de dados: cadeia de caracteres |
| corpo.multiSelect | Sinalizador que indica se o usuário pode selecionar várias opções. Valores possíveis:
Tipo de dados: booliano |
| corpo.nluTextEnabled | Sinalizador que indica se o cliente de bate-papo do usuário pode receber mensagens de texto de NLU (Natural Language Understanding). Valores possíveis:
Tipo de dados: booliano |
| opções.corpo | Lista de objetos que descrevem as opções disponíveis para um controle do seletor. Tipo de dados: matriz |
| corpo.opções.anexo | URL da imagem no carrossel a ser recuperada. Tipo de dados: cadeia de caracteres |
| corpo.opções.descrição | Descrição do item do carrossel. Tipo de dados: cadeia de caracteres |
| opções.corpo.enabled | Sinalizador que indica se o controle do seletor está habilitado no cliente de bate-papo do usuário final. Em implementações de bot para bot, o bot primário é responsável por garantir que o controle do seletor esteja desabilitado. Valores possíveis:
Tipo de dados: booliano |
| rótulo.opções.corpo | Rótulo a ser exibido para o parâmetro body.options.value associado. Tipo de dados: cadeia de caracteres |
| body.options.renderStyle | Estilo a ser usado ao renderizar o elemento associado. Valor possível: dados Tipo de dados: cadeia de caracteres |
| corpo.opções.valor | Valor a ser exibido para o parâmetro body.options.label associado. Tipo de dados: cadeia de caracteres |
| body.promptMsg | Mensagem de aviso a ser exibida com o controle do seletor. Tipo de dados: cadeia de caracteres |
| corpo.necessário | Sinalizador que indica se o usuário final deve responder à consulta no elemento do corpo. Valores possíveis:
Tipo de dados: booliano |
| body.spinnerType | Retornado somente quando actionType for StartSpinner. Tipo de controle giratório mostrado ao usuário do bate-papo.Valores possíveis: espera_hora: mensagem indicando a quantidade de atraso antes de ser transferida para um atendente. Tipo de dados: cadeia de caracteres |
| corpo.estilo | Estilo do elemento do corpo. Valores possíveis:
Tipo de dados: cadeia de caracteres |
| corpo.modelo_do_modelo | Nome do modelo a ser usado para exibir o cartão associado. Tipo de dados: cadeia de caracteres |
| corpo.tipo | Retornado somente para DefaultOutputLink. Tipo de dados de retorno. Valores possíveis: link Tipo de dados: cadeia de caracteres |
| corpo.uiType | Tipo de elemento do corpo. Os valores possíveis dependem do valor no parâmetro body.group. Esses valores são mapeados de volta para os controles definidos no Designer do Virtual Agent. Para obter mais informações, consulte Introdução ao Designer do Virtual Agent. Valores possíveis:
Tipo de dados: cadeia de caracteres |
| corpo.valor | Dados a serem usados para processar o elemento do corpo. O tipo de informação que é passado de volta depende do tipo de elemento do corpo. Link de saída: objeto. Imagem de saída: cadeia de caracteres. URL da imagem. HTML de saída: cadeia de caracteres. HTML que o cliente precisa renderizar. Tipo de dados: cadeia de caracteres ou objeto |
| corpo.valor.ação | Retornado somente para DefaultOutputLink. URL do link retornado. Tipo de dados: cadeia de caracteres |
| corpo.tempoDeEspera | Quantidade de tempo que o usuário tem que esperar antes de ser conectado a um atendente. Tipo de dados: cadeia de caracteres |
| corpo.largura | Largura do elemento HTML associado. Tipo de dados: número Unidade: pixels |
| clientSessionId | Identificador de sessão de cliente exclusivo da aplicação/serviço de bate-papo que o usuário final está usando para se comunicar com o bot ServiceNow. Tipo de dados: cadeia de caracteres |
| clientVariables | Pares de nome-valor no formato JSON que são copiados do que é passado no parâmetro clientVariables no corpo da solicitação. Esses valores não são processados pelo endpoint, mas podem ser usados para manter informações específicas do cliente anexadas à conversa. Tipo de dados: objeto |
| concluída | Sinalizador que indica se o ServiceNow Virtual Agent concluiu a conversa com sucesso. Valores possíveis:
Tipo de dados: booliano |
| EnterpriseId | Não utilizado no momento. |
| message | Detalhes da mensagem enviada para o ServiceNow VA. É o mesmo que o objeto de mensagem passado. Tipo de dados: objeto |
| mensagem.anexo | Detalhes do anexo. Os anexos podem ser um arquivo ou um URL. Tipo de dados: objeto |
| message.attachment.clientAttachmentId | Identificador exclusivo do anexo enviado para o ServiceNow VA. O formato deste identificador é determinado pelo implementador. Tipo de dados: cadeia de caracteres |
| message.attachment.contentType | Tipo de mime padrão do anexo. Valores possíveis (sem distinção entre maiúsculas e minúsculas):
Tipo de dados: cadeia de caracteres |
| message.attachment.fileName | Nome do arquivo do anexo. Tipo de dados: cadeia de caracteres |
| message.attachment.url | URL onde o anexo está localizado. Tipo de dados: cadeia de caracteres |
| message.clientMessageId | Identificador alfanumérico exclusivo da mensagem. Tipo de dados: cadeia de caracteres |
| mensagem.texto | Texto da mensagem. Tipo de dados: cadeia de caracteres Tamanho máximo: Ilimitado |
| mensagem.digitada | Sinalizador que indica se a mensagem foi digitada ou foi uma seleção de opção (selecionada). Valores válidos:
Tipo de dados: booliano |
| nowBotId | Não utilizado no momento. |
| nowSessionId | Não utilizado no momento. |
| requestId | Identificador exclusivo desta solicitação. Tipo de dados: cadeia de caracteres |
| pontuação | Pontuação de confiança da intenção do modelo ServiceNow NLU, especificada como um percentual, como 87,3%. Essa pontuação permite que o bot primário tome a decisão de exibir a intenção associada com base no limite de confiança do modelo do bot primário NLU. O limite de confiança do modelo ServiceNow NLU é ignorado na instância ServiceNow para que o limite de confiança do modelo NLU do bot primário possa ser aplicado de forma consistente em todos os bots secundários. Tipo de dados: número |
| tomarControle | Sinalizador que indica que o ServiceNow Virtual Agent deseja devolver o controle ao bot primário. Valores válidos:
Tipo de dados: booliano Padrão: falso |
| userId | Identificador do usuário final que está interagindo com o bot. Tipo de dados: cadeia de caracteres |
Inicie uma conversa usando a ação START_CONVERSATION para iniciar uma conversa
O exemplo a seguir mostra como usar a ação START_CONVERSATION para iniciar uma conversa com Virtual Agent. Esta chamada direciona o usuário para o tópico de saudação.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "asd2423-sda23-qwe23-we23",
"action": "START_CONVERSATION",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"message":{
"text": "",
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "beth.anglin",
"emailId": "beth.anglin@example.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"asd2423-sda23-qwe23-we23",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"beth.anglin",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Hi, I'm your Virtual Agent. Let me know how I can help you today.",
"maskType":"NONE"
},
{
"uiType":"TopicPickerControl",
"group":"DefaultPicker",
"nluTextEnabled":false,
"promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type help any time when you need help.",
"label":"Show me everything",
"options":[
{
"label":"b2b topic",
"value":"2bb7bd7670de6010f877c7f188266fc7",
"enabled":true
},
{
"label":"Live Agent Support.",
"value":"ce2ee85053130010cf8cddeeff7b12bf",
"enabled":true
}
]
}
],
"score":1
} Transferir uma conversa para Atendente usando enunciado
O exemplo a seguir ilustra como transferir uma conversa para Atendente, ignorando o tópico de saudação, passando o agente como um enunciado no parâmetro message.text. Os possíveis valores de enunciado são definidos na tabela sys_cs_contextual_action. Para obter informações adicionais sobre ações contextuais, consulte Ações contextuais para integrações de bate-papo personalizadas.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: ORANGE" \
--data " {
"requestId": "322bas2be70-sadsa-we32-3eq2-1231ra9",
"botToBot": true,
"clientSessionId": "",
"silentMessage": false,
"message":{
"text": "agent",
"typed": true
},
"userId": "abel.tuter",
"emailId": "abel.tuter@servicenow.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"322bas2be70-sadsa-we32-3eq2-1231ra9",
"clientSessionId":"",
"message":{
"text":"agent",
"typed":true
},
"userId":"abel.tuter",
"body":[
{
"uiType":"Picker",
"group":"DefaultPicker",
"required":true,
"nluTextEnabled":false,
"label":"I want to be sure I got this right. What item best describes what you want to do?",
"itemType":"List",
"style":"list",
"multiSelect":false,
"options":[
{
"label":"Live Agent Support.",
"value":"Live Agent Support.",
"renderStyle":"data",
"enabled":false
},
{
"label":"Virtual Agent Capabilities.",
"value":"Virtual Agent Capabilities.",
"renderStyle":"data",
"enabled":false
},
{
"label":"I want something else",
"value":"-1",
"renderStyle":"data",
"enabled":false
}
],
"scriptedData":null
}
],
"score":1
}Transferir uma conversa para o Suporte do atendente com base na seleção do usuário
O exemplo a seguir mostra a transferência da conversa para o Suporte do atendente com base na seleção do usuário na interação anterior.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: ORANGE" \
--data "{
"requestId": "322bas2be70-sadsa-we32-3eq2-1231ra9",
"botToBot": true,
"clientSessionId": "",
"silentMessage": false,
"message":{
"text": "Live Agent Support.",
"typed": true
},
"userId": "abel.tuter",
"emailId": "abel.tuter@servicenow.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
} "A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"322bas2be70-sadsa-we32-3eq2-1231ra9",
"clientSessionId":"",
"message":{
"text":"Live Agent Support.",
"typed":true
},
"userId":"abel.tuter",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Please stand by while I connect you to a live agent."
}
],
"agentChat":true,
"score":1
}Encerrar uma conversa Virtual Agent definindo o parâmetro de ação
O exemplo a seguir mostra como encerrar uma conversa Virtual Agent definindo o parâmetro action como END_CONVERSATION.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "s345ew-sjg554-qwe23-we23",
"action": "END_CONVERSATION",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"message":{
"text": "b2b topic",
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "beth.anglin",
"emailId": beth.anglin@example.com,
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado mostrando o término da conversa.
{
"requestId":"s345ew-sjg554-qwe23-we23",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"beth.anglin",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE"
}
],
"score":1
}Encerrar uma conversa Atendente definindo o parâmetro de ação
O exemplo a seguir mostra como encerrar uma conversa Atendente definindo o parâmetro action como END_CONVERSATION.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "sad-sjg554-qwe23-we23",
"action": "END_CONVERSATION",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"message":{
"text": "",
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "beth.anglin",
"emailId": "beth.anglin@example.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado mostrando o término da conversa.
{
"requestId":"sad-sjg554-qwe23-we23",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"beth.anglin",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE"
}
],
"completed":true,
"score":1
}Use comandos definidos na tabela sys_cs_contextual_action como um enunciado para iniciar uma conversa com Virtual Agent
O exemplo a seguir mostra como usar o comando Hi definido na tabela sys_cs_contextual_action como um enunciado para iniciar uma conversa com Virtual Agent em vez de definir o parâmetro action como START_CONVERSATION conforme mostrado nos exemplos anteriores. Este exemplo mostra o uso de uma das variantes de idioma do comando Hi, "Hola".
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: ORANGE" \
--data "{
"requestId": "302bas2be70-sadsa-we32-3eq2-1231ra9",
"botToBot": true,
"clientSessionId": "",
"silentMessage": false,
"message":{
"text": "hola",
"typed": true
},
"userId": "fred.ludy",
"emailId": "abel.tuter@servicenow.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"302bas2be70-sadsa-we32-3eq2-1231ra9",
"clientSessionId":"",
"message":{
"text":"hola",
"typed":true
},
"userId":"fred.ludy",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Hi, I'm your Virtual Agent. Let me know how I can help you today.",
"maskType":"NONE"
},
{
"uiType":"TopicPickerControl",
"group":"DefaultPicker",
"nluTextEnabled":false,
"promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type hellllp! any time when you need help.",
"label":"Show me everything",
"options":[
{
"label":"boolean check",
"value":"1b5257a1db712010d3d6d9595e9619f3",
"enabled":true
},
{
"label":"Test_table_datepicker",
"value":"6515f0cadb4220108249f7541d961980",
"enabled":true
},
{
"label":"Test File upload",
"value":"76c1f4b2db7520108249f7541d9619a7",
"enabled":true
},
{
"label":"Test B2B 2",
"value":"8373e55cdb8120108249f7541d96196d",
"enabled":true
},
{
"label":"FAQ Conversation Builder_Global",
"value":"9f3114a3dbc520108249f7541d961981",
"enabled":true
},
{
"label":"Get to know you",
"value":"a443dd6adb812010d3d6d9595e961954",
"enabled":true
},
{
"label":"Get to know you_Global",
"value":"b1a56b87db8120108249f7541d9619b2",
"enabled":true
},
{
"label":"Live Agent Support.",
"value":"ce2ee85053130010cf8cddeeff7b12bf",
"enabled":true
},
{
"label":"Apply for PTO_B2B NLU",
"value":"d948c94cdb052010d3d6d9595e961969",
"enabled":true
}
]
}
],
"score":1
} Use comandos definidos na tabela sys_cs_contextual_action como um enunciado para encerrar uma conversa
O exemplo a seguir mostra como usar o comando Bye definido na tabela sys_cs_contextual_action como um enunciado para encerrar uma conversa com Virtual Agent em vez de definir action como END_CONVERSATION conforme mostrado nos exemplos anteriores. Este exemplo mostra o uso de uma das variantes de idioma do comando Bye, "choa".
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: ORANGE" \
--data "{
"requestId": "302bas2be70-sadsa-we32-3eq2-1231ra9",
"botToBot": true,
"clientSessionId": "",
"silentMessage": false,
"message":{
"text": "choa",
"typed": true
},
"userId": "fred.ludy",
"emailId": "abel.tuter@servicenow.com",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"302bas2be70-sadsa-we32-3eq2-1231ra9",
"clientSessionId":"",
"message":{
"text":"chao",
"typed":true
},
"userId":"fred.ludy",
"body":[
{
"uiType":"Picker",
"group":"DefaultPicker",
"required":true,
"nluTextEnabled":false,
"label":"Please make a selection.",
"itemType":"List",
"style":"list",
"multiSelect":false,
"options":[
{
"label":"End conversation",
"value":"1",
"renderStyle":"data",
"enabled":false
},
{
"label":"Cancel",
"value":"0",
"renderStyle":"data",
"enabled":false
}
],
"scriptedData":null
}
],
"score":1
}Alterar uma conversa em andamento usando o parâmetro de ação SWITCH
O exemplo a seguir mostra como usar o parâmetro SWITCH action para mudar uma conversa em andamento para o tópico que corresponde ao especificado no parâmetro intent.id.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "sdfsfs-hgfhg-34fssd-zxcz-sd43",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"action": "SWITCH",
"intent" : {
"id": "Saloon Vehicle"
},
"message":{
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "Guest",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado mostrando o VA alternado para o novo tópico.
{
"requestId":"sdfsfs-hgfhg-34fssd-zxcz-sd43",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"Guest",
"body":[
{
"uiType":"InputText",
"group":"DefaultText",
"required":true,
"nluTextEnabled":false,
"label":"limo input:",
"maskType":"NONE"
}
],
"score":1
}Obter uma pontuação de confiança Compreensão da linguagem natural (NLU) para um enunciado
O exemplo a seguir mostra como obter uma pontuação de confiança NLU para um enunciado se NLU estiver habilitado no VA.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "sdfsfs-hgfhg-34fssd-zxcz-sd43",
"enterpriseId": "ServiceNow",
"nowBotId": "A85PWLERF",
"clientSessionId": "",
"nowSessionId": "",
"message":{
"text": "most popular choice",
"typed": true,
"clientMessageId": "ABC-123"
},
"userId": "Guest",
"timestamp": 1588824102,
"timezone": "America/New_York"
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado mostrando a pontuação de confiança do NLU.
{
"requestId":"sdfsfs-hgfhg-34fssd-zxcz-sd43",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"most popular choice",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"Guest",
"body":[
{
"uiType":"InputText",
"group":"DefaultText",
"required":true,
"nluTextEnabled":false,
"label":"model input:",
"maskType":"NONE"
}
],
"score":"0.92"
}Transferir uma conversa para um atendente em uma fila específica
O exemplo a seguir mostra como transferir uma conversa para o atendente em uma fila específica. Você deve primeiro configurar suas filas com condições específicas. Em seguida, você passa essas condições como contextVariables no corpo da solicitação. Para obter informações adicionais sobre como criar uma fila de item de trabalho, consulte Criar uma fila de item de trabalho.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
"requestId": "34re-dasd-qwe23-dsds", // Unique value for a message (hash)
"enterpriseId": "ServiceNow", // ServiceNow (Optional
"nowBotId": "A85PWLERF", // In case of multiple ServiceNow secondary bots (one for HR, one for ITSM)
"action":"AGENT", // Actions to close conversation. Other possible value is END_CONVERSATION
"clientSessionId": "", // Client conversation id
"nowSessionId": "", // ServiceNow conversation id
"message":{
"text": "How are you?", // User passed message
"typed": true, // typed or clicked
"clientMessageId": "ABC-123"
},
"userId": "abraham.lincoln", // User’s id in their system
"emailId": "abraham.lincoln@example.com",
"timestamp": 1588824102,
"timezone": "America/New_York",
"contextVariables":{
"b2b_category":"humanresource"
}
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"34re-dasd-qwe23-dsds",
"clientSessionId":"",
"nowSessionId":"",
"message":{
"text":"How are you?",
"typed":true,
"clientMessageId":"ABC-123"
},
"userId":"abraham.lincoln",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"I am sorry but I didn't understand your request.",
"maskType":"NONE"
},
{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Please try giving me your request in a different way. I'm currently better at understanding short sentences.",
"maskType":"NONE"
},
{
"uiType":"TopicPickerControl",
"group":"DefaultPicker",
"nluTextEnabled":false,
"promptMsg":"Hi guest, please enter your request or make a selection of what I can help with. You can type help any time when you need help.",
"label":"Show me everything",
"options":[
{
"label":"Live Agent Support.",
"value":"ce2ee85053130010cf8cddeeff7b12bf",
"enabled":true
}
]
}
],
"score":0
}Transferir uma aplicação pública/arquivo de anexo em PDF
Este exemplo mostra como transferir um anexo de aplicativo/pdf público.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: BOT_Token" \
--data "{
"requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId": "U94CSJLEN",
"message": {
"attachment": {
"clientAttachmentId": "my-unique-identifier",
"contentType": "application/pdf",
"fileName": "MY PDF TEST",
"url": "http://www.africau.edu/images/default/sample.pdf"
}
},
"userId": "U94CSJLEN",
"emailId": "admin@example.com"
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId":"U94CSJLEN",
"message":{
"attachment":{
"clientAttachmentId":"my-unique-identifier",
"contentType":"application/pdf",
"fileName":"MY PDF TEST",
"url":"http://www.africau.edu/images/default/sample.pdf"}
},
"userId":"U94CSJLEN",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"File got",
"maskType":"NONE",
"itemType":"outputtext"
},
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE",
"itemType":"outputtext"
}
],
"completed":true,
"score":1
}Transferir um anexo de vídeo/mpeg
Este exemplo mostra a solicitação/resposta para carregar um anexo de vídeo/mpeg.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: BOT_TOKEN" \
--data "{
"requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId": "U94CSJLEN",
"message": {
"attachment": {
"clientAttachmentId": "my-unique-identifier10",
"contentType": "video/mpeg",
"fileName": "MY TEST10.mp4",
"url": "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4"
}
},
"userId": "U94CSJLEN",
"emailId": "admin@example.com"
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId":"U94CSJLEN",
"message":{
"attachment":{
"headers":{
"Authorization":"Basic amFzbWluZS53YWRod2FuaWE6VGVzdGluZ0AxMjM="
},
"clientAttachmentId":"my-unique-identifier10",
"contentType":"video/mpeg",
"fileName":"MY TEST10.mp4",
"url":"https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4"
}
},
"userId":"U94CSJLEN",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"File got",
"maskType":"NONE",
"itemType":"outputtext"
},
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE","itemType":"outputtext"
}
],
"completed":true,
"score":1
}Transferir um anexo de imagem/jpeg
Este exemplo mostra a solicitação/resposta para carregar um anexo de imagem/jpeg.
curl "https://instance.servicenow.com/api/sn_va_as_service/bot/integration" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--header "token: BOT_TOKEN" \
--data "{
"requestId": "f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId": "U94CSJLEN",
"message": {
"attachment": {
"clientAttachmentId": "my-unique-identifier10",
"contentType": "image/jpeg",
"fileName": "MY TEST10.jpg",
"url": "https://image.imagestock.com/image-photo/pink-butterfly-isolated-on-white-260nw-1218104047.jpg"
}
},
"userId": "U94CSJLEN",
"emailId": "admin@example.com"
}"
--user "username":"password"
A seguir está o corpo da resposta enviado do VA para o endpoint de resposta configurado.
{
"requestId":"f42f3550-5b44-4cde-aa52-9b6756b3131c",
"clientSessionId":"U94CSJLEN",
"message":{
"attachment":{
"headers":{
"Authorization":"Basic amFzbWluZS53YWRod2FuaWE6VGVzdGluZ0AxMjM="
},
"clientAttachmentId":"my-unique-identifier10",
"contentType":"image/jpeg",
"fileName":"MY TEST10.jpg",
"url":"https://image.imagestock.com/image-photo/pink-butterfly-isolated-on-white-260nw-1218104047.jpg"
}
},
"userId":"U94CSJLEN",
"body":[
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"File got",
"maskType":"NONE",
"itemType":"outputtext"
},
{
"uiType":"OutputText",
"group":"DefaultText",
"required":false,
"nluTextEnabled":false,
"label":"The conversation has ended. If you need help again, type hi.",
"maskType":"NONE",
"itemType":"outputtext"
}
],
"completed":true,
"score":1
}