Erros comuns em Virtual Agent API

  • Versão de lançamento: Australia
  • Atualizado 2 de fev. de 2026
  • 4 min. de leitura

    • Esta seção descreve alguns erros comuns em Virtual Agent API e como eles podem ser resolvidos.

    Virtual Agent API validação da estrutura

    Estrutura da solicitação:

    Virtual Agent API Espera a seguinte estrutura JSON:
    {
  "requestId": "any-unique-request-id",
  "clientSessionId": "any-unique-session-id",
  "userId": "any-unique-user-id",
  "emailId": "user@example.com",
  "action": "",
  "message": {
    "text": "User message text",
    "typed": true
  },
  "contextVariables": {},
  "history": [
    {
      "isBotMessage": true,
      "value": "How can I help you?",
      "displayName": "Bot",
      "type": "text"
    }
  ],
  "clientVariables": {
    "id": "va-bot-12345",
    "timestamp": "1687527831786"
  }
}
    Tabela 1. Definições de campo
    Campo Obrigatório Descrição
    requestId Não Variável de passagem retornada nas respostas
    ClientSessionId Não Identificador da sessão de passagem
    userId Sim Identificador de usuário exclusivo (obrigatório)
    E-mail Não* E-mail do usuário para vinculação (*Obrigatório para vinculação do usuário)
    ação Não Parâmetro de ação opcional
    texto.mensagem Sim Conteúdo da mensagem do usuário (obrigatório)
    mensagem.digitada Não verdadeiro para texto de pesquisa, falso para seleção de valor
    ContextVariables Não Dados de contexto opcionais
    histórico Não Histórico de conversas de bot (somente primeira solicitação)
    ClientVariables Não Variáveis de cliente de passagem
    Nota:
    Apenas userIde. message.textsão campos obrigatórios na solicitação.

    Problemas de carregamento de arquivo

    Virtual Agent API Compatível com dois modos de carregamento de arquivo, como síncrono e assíncrono.

    Estrutura da solicitação de carregamento de arquivo:

    {
    "userId": "{{user_id}}",
    "message": {
        "attachment": {
                "clientAttachmentId": "{{request_id}}",
                "contentType": "video/mp4",
                "fileName": "sample.mp4",
                "url": "https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4",
                "headers": {
                    "header 1": "value 1"
                }
            },
        "text": "along with text",
        "typed": true
    }
}
    Tabela 2. Definições de campo
    Campo Obrigatório Descrição
    contentType Sim Tipo de MIME (por exemplo, vídeo/mp4 , imagem/png )
    nomeArquivo Sim Nome do arquivo com a extensão
    URL Sim URL acessível para baixar o arquivo
    ClientAttachmentId Não Identificador exclusivo para acompanhamento
    cabeçalhos Não Cabeçalhos de autenticação para download de arquivo

    Carregamento de arquivo no modo síncrono:

    Para carregar um arquivo no modo síncrono, siga as etapas abaixo:
    1. Carregue o arquivo usando a API de mídia. Para obter mais informações, consulte CCCIF Media Resource API.
      A API de mídia retorna um url. Um exemplo da resposta é:
      {
  "result": {
    "mediaUrl": "<instance>/api/now/v1/cs/media/JOBBfkqSq6kDiFzxyinvHhke73O4TZ0j",
    "name": "image.png",
    "state": "available",
    "attachmentId": "e8671b9193209210a755b8e86cba104b"
  }
}
    2. Use o url de mídia em Virtual Agent API solicitação. Um exemplo de JSON é:
      {
  "userId": "user123",
  "message": {
    "attachment": {
      "contentType": "image/png",
      "fileName": "image.png",
      "url": "<instance>/api/now/v1/cs/media/JOBBfkqSq6kDiFzxyinvHhke73O4TZ0j"
    },
    "text": "Here is the image",
    "typed": true
  }
}

    Carregamento de arquivo no modo assíncrono:

    Você pode carregar um arquivo no modo assíncrono de duas maneiras:
    1. Use a url do arquivo no Virtual Agent API solicitação.
      • url do arquivo direto:
        {
  "userId": "user123",
  "message": {
    "attachment": {
      "contentType": "application/pdf",
      "fileName": "report.pdf",
      "url": "https://publicserver.com/files/report.pdf"
    },
    "text": "Document attached",
    "typed": true
  }
}
      • url do arquivo protegido:
        {
  "userId": "user123",
  "message": {
    "attachment": {
      "contentType": "application/pdf",
      "fileName": "confidential.pdf",
      "url": "https://secureserver.com/files/confidential.pdf",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "X-Custom-Header": "custom-value"
      }
    },
    "text": "Secure document attached",
    "typed": true
  }
}
    2. Usando a API de mídia (conforme seguido no modo síncrono).

    Problemas de vinculação do usuário

    Virtual Agent API compatível somente com vinculação automática de usuário pronta para uso. A vinculação manual não está habilitada por padrão em Virtual Agent API.

    Pré-requisitos para vinculação de usuário:
    1. A autenticação de mensagem é obrigatória.
      • Sem autenticação de mensagem em sys_cs_provider_application , o link do usuário não funciona.
      • Você deve configurar a Autenticação de mensagem corretamente. (Consulte a seção Autenticação.)
    2. Campos de solicitação obrigatórios.
      • UserId deve estar presente e exclusivo.
      • E-mail deve estar presente e ser válido.

    Requisitos de registro do usuário:

    . E-mail deve corresponder a sys_user registro que atende a todas as condições abaixo:
    • O registro existe em sys_user tabela.
    • O campo E-mail corresponde exatamente.
    • O usuário está ativo. ( verdadeiro )
    • O usuário não está bloqueado. ( "locked_out": falso )
    • Apenas um registro de usuário corresponde a essas condições.
    Nota:
    Se vários usuários tiverem o mesmo e-mail, a vinculação falhará.
    Configuração de vinculação automática:
    1. Verifique a configuração do provedor.
      • Navegue até sys_cs_provider e abra o. "Bot do VA para provedor de bot" registro.
      • Tabela 3. Configuração obrigatória
        Campo Valor esperado
        automatic_link_enabled verdadeiro
        automatic_link_action sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account
        link_account_enabled verdadeiro
    2. Verifique o mapa de usuários do provedor.
      • Navegue até provider_user_map tabela.
      • Filtrar por: falso E. User_id: UserId da solicitação .
      • Problema: Se existir registro com falso , o usuário não pode ser vinculado automaticamente.
      • Solução: O administrador deve excluir manualmente o registro inativo e repetir a solicitação de vinculação.
    3. Verifique se há personalizações.
      • Revise as personalizações executando o. sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account script.
      • Verifique os problemas comuns de personalização:
        • Lógica que impede a vinculação automática
        • Verificações de validação adicionais
        • Mapeamentos de campo modificados

    Verificação de solução de problemas de vinculação de usuário:

    • Configuração:
      • A autenticação de mensagem existe e está ativa.
      • UserId está presente na solicitação.
      • E-mail está presente na solicitação.
      • "automatic_link_enabled" é verdadeiro
      • automatic_link_action pontos para corrigir o script.
      • link_account_enabled: verdadeiro
    • Registro de usuário:
      • O usuário existe em sys_user .
      • O e-mail corresponde exatamente (diferencia maiúsculas de minúsculas).
      • O usuário está ativo.
      • O usuário não está bloqueado.
      • Apenas um usuário corresponde ao e-mail.
    • Mapa de usuários do provedor:
      • Não há registros inativos para isso UserId .
      • Verifique se há mapeamentos duplicados.
    • Personalizações:
      • Revise o script de link automático para modificações.
      • Teste com script OOB, se personalizado.