---
sourceDocument: 호주 대화형 인터페이스
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ko-KR/conversational-interfaces

 Release :

    - australia

ft:locale :

    - ko-KR

ft:publication_title :

    - 호주 대화형 인터페이스

ft:clusterId :

    - convint

bundleId :

    - convint

workflow :

    - Platform


---

# 일반적인 오류

# 가상 에이전트 API의 일반적인 오류 {#ariaid-title1}

* 릴리스 버전: Australia
* 
* 업데이트 날짜 2026년 02월 02일
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 소요 시간: 7분

이 섹션에서는 몇 가지 일반적인 오류 가상 에이전트 API 와 해결 방법에 대해 설명합니다.

## 가상 에이전트 API 구조 확인 {#virtual-agent-common-errors__section_r4n_y1z_m3c}

**요청 구조:**  
가상 에이전트 API 에는 다음과 같은 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"
      }
    }

{#virtual-agent-common-errors__table_okj_mjz_m3c__entry__3}

| 필드 | 필수 | 설명 |
|-|-|-|
| `requestId` | 아니요 | 응답에서 반환된 통과 변수 |
| `clientSessionId` | 아니요 | 통과 세션 식별자 |
| `userID` | 예 | 고유 사용자 식별자(필수) |
| `emailId` | 아니요\* | 연결용 사용자 이메일(\*사용자 연결에 필요) |
| `작업` | 아니요 | 선택적 작업 매개변수 |
| `메시지.텍스트` | 예 | 사용자 메시지 컨텐츠(필수) |
| `message.typed` | 아니요 | 검색 텍스트의 경우 `예`, 값 선택의 경우 `아니오` |
| `context변수` | 아니요 | 선택적 컨텍스트 데이터 |
| `역사` | 아니요 | 봇 대화 이력(첫 번째 요청만) |
| `클라이언트 변수` | 아니요 | 통과 클라이언트 변수 |
[표 1. 필드 정의]

{#virtual-agent-common-errors__table_okj_mjz_m3c}  
주:  
userId 및 message.text 전용 필드는 요청의 필수 필드입니다.

## 파일 업로드 문제 {#virtual-agent-common-errors__section_ggr_ybz_m3c}

가상 에이전트 API 는 동기식 및 비동기식의 두 가지 파일 업로드 모드를 지원합니다.

**파일 업로드 요청 구조:**  

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

{#virtual-agent-common-errors__table_l44_hsz_m3c__entry__3}

| 필드 | 필수 | 설명 |
|-|-|-|
| `contentType` | 예 | MIME 유형(예: `비디오/mp4`, `이미지/png`) |
| `fileName` | 예 | 확장명이 있는 파일의 이름 |
| `URL` | 예 | 파일을 다운로드할 수 있는 접근 가능한 URL |
| `clientAttachmentId` | 아니요 | 추적을 위한 고유 식별자 |
| `헤더` | 아니요 | 파일 다운로드를 위한 인증 헤더 |
[표 2. 필드 정의]

{#virtual-agent-common-errors__table_l44_hsz_m3c}  
**동기 모드에서 파일 업로드:**  
동기 모드에서 파일을 업로드하려면 다음 단계를 따르십시오.

1. 미디어 API를 사용하여 파일을 업로드합니다. 자세한 내용은 [CCCIF Media Resource API](https://www.servicenow.com/docs/access?context=cccif-api&version=australia&pubname=australia-api-reference&ft:locale=en-US) 문서를 참조하십시오.  
   미디어 API는 URL을 반환합니다. 응답의 예는 다음과 같습니다.

       {
         "result": {
           "mediaUrl": "<instance>/api/now/v1/cs/media/JOBBfkqSq6kDiFzxyinvHhke73O4TZ0j",
           "name": "image.png",
           "state": "available",
           "attachmentId": "e8671b9193209210a755b8e86cba104b"
         }
       }

2. 요청에 미디어 URL을 가상 에이전트 API 사용합니다. 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
         }
       }

{#virtual-agent-common-errors__ol_pbz_svz_m3c}  
**비동기 모드로 파일 업로드:**  
비동기 모드에서는 두 가지 방법으로 파일을 업로드할 수 있습니다.

1. 요청에 파일 URL을 가상 에이전트 API 사용합니다.
   * 직접 파일 URL:

         {
           "userId": "user123",
           "message": {
             "attachment": {
               "contentType": "application/pdf",
               "fileName": "report.pdf",
               "url": "https://publicserver.com/files/report.pdf"
             },
             "text": "Document attached",
             "typed": true
           }
         }

   * 보호된 파일 URL:

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

   {#virtual-agent-common-errors__ul_sln_jb1_n3c}
2. 미디어 API 사용(동기 모드에서 따름).
{#virtual-agent-common-errors__ol_lwv_jzz_m3c}

## 사용자 연결 문제 {#virtual-agent-common-errors__section_qry_grx_d3c}

가상 에이전트 API 는 바로 사용 가능한 자동 사용자 링크만 지원합니다. 에서는 수동 연결이 기본적으로 활성화되어 있지 않습니다.가상 에이전트 API  
**사용자 연결의 전제 조건:**

1. 메시지 인증은 필수입니다.
   * `sys_cs_provider_application`에 메시지 인증이 없으면 사용자 연결이 작동하지 않습니다.
   * 메시지 인증을 올바르게 구성해야 합니다. (인증 섹션을 참조하십시오.)
   {#virtual-agent-common-errors__ul_w4q_qc1_n3c}
2. 필수 요청 필드입니다.
   * `userId` 가 존재하고 고유해야 합니다.
   * `emailId` 가 존재하고 유효해야 합니다.
   {#virtual-agent-common-errors__ul_t1h_fd1_n3c}
{#virtual-agent-common-errors__ol_a1g_pc1_n3c}  
**사용자 기록 요구 사항:**  
`emailId`는 아래 조건을 모두 충족하는 `sys_user` 기록과 일치해야 합니다.

* 기록이 `sys_user` 테이블에 있습니다.
* 이메일 필드가 정확히 일치합니다.
* 사용자가 활성 상태입니다. (`활성=true`)
* 사용자가 잠기지 않았습니다. (`locked_out=아니오`)
* 단 하나의 사용자 기록만이 이 조건과 일치합니다.

{#virtual-agent-common-errors__ul_j44_sd1_n3c}  
주:  
여러 사용자가 동일한 이메일을 사용하는 경우 연결에 실패합니다.  
**자동 연결 구성:**

1. 제공자 구성을 확인합니다.
   * `sys_cs_provider` 테이블로 이동하여 **"VA 봇에서 봇 제공자로"** 기록을 엽니다.
   * {#virtual-agent-common-errors__table_s5q_ck1_n3c__entry__2}

     | 필드 | 예상 값 |
     |-|-|
     | `automatic_link_enabled` | `예` |
     | `automatic_link_action` | `sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account` |
     | `link_account_enabled` | `예` |
     [표 3. 필수 설정]

     {#virtual-agent-common-errors__table_s5q_ck1_n3c}
   {#virtual-agent-common-errors__ul_q4g_xj1_n3c}
2. 제공자 사용자 맵을 확인합니다.
   * `provider_user_map` 테이블로 이동합니다.
   * 필터 기준: `활성=아니오` 및 `channel_user_id={요청의 userId}`.
   * 문제: `활성=아니오`인 기록이 있으면 사용자를 자동으로 연결할 수 없습니다.
   * 해결 방법: 관리자는 비활성 기록을 수동으로 삭제하고 연결 요청을 다시 시도해야 합니다.
   {#virtual-agent-common-errors__ul_mdx_dj1_n3c}
3. 사용자 지정을 확인합니다.
   * `sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account` 스크립트를 실행하여 사용자 지정을 검토합니다.
   * 일반적인 커스터마이제이션 문제를 확인합니다.
     * 자동 연결을 방지하는 논리
     * 추가 유효성 확인 검사
     * 수정된 필드 매핑
     {#virtual-agent-common-errors__ul_brc_bj1_n3c}
   {#virtual-agent-common-errors__ul_vt2_y31_n3c}
{#virtual-agent-common-errors__ol_lrk_4h1_n3c}  
**사용자 연결 문제 해결 검사 목록:**  
* 구성:
  * 메시지 인증이 존재하며 활성 상태입니다.
  * `userId` 가 요청에 있습니다.
  * `emailId` 가 요청에 있습니다.
  * `automatic_link_enabled = 예`
  * `automatic_link_action` 올바른 스크립트를 가리킵니다.
  * `link_account_enabled = 예`
  {#virtual-agent-common-errors__ul_xsz_gh1_n3c}
* 사용자 기록:
  * 사용자가 `sys_user`에 있습니다.
  * 이메일이 정확히 일치합니다(대/소문자 구분).
  * 사용자가 활성 상태입니다.
  * 사용자가 잠기지 않았습니다.
  * 한 명의 사용자만 이메일과 일치합니다.
  {#virtual-agent-common-errors__ul_q5g_231_n3c}
* 제공자 사용자 맵:
  * 이 `userId`에 대한 비활성 기록이 없습니다.
  * 중복 매핑을 검사합니다.
  {#virtual-agent-common-errors__ul_dt4_k31_n3c}
* 사용자 지정:
  * 자동 링크 스크립트에서 수정 사항을 검토합니다.
  * 사용자 지정된 경우 OOB 스크립트로 테스트합니다.
  {#virtual-agent-common-errors__ul_wls_l31_n3c}
{#virtual-agent-common-errors__ul_xwb_d31_n3c}