일반적인 오류

호주 대화형 인터페이스

Release

australia

ft:locale

ko-KR

ft:publication_title

호주 대화형 인터페이스

ft:clusterId

convint

bundleId

convint

workflow

Platform

가상 에이전트 API의 일반적인 오류

릴리스 버전: Australia

업데이트 날짜 2026년 02월 02일

소요 시간: 7분

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

가상 에이전트 API 구조 확인

요청 구조:

가상 에이전트 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"
  }
}

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

주:

userId 및 message.text 전용 필드는 요청의 필수 필드입니다.

파일 업로드 문제

가상 에이전트 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
    }
}

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

동기 모드에서 파일 업로드:

동기 모드에서 파일을 업로드하려면 다음 단계를 따르십시오.

미디어 API를 사용하여 파일을 업로드합니다. 자세한 내용은 문서를 참조하십시오.

미디어 API는 URL을 반환합니다. 응답의 예는 다음과 같습니다.

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

요청에 미디어 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
  }
}

비동기 모드로 파일 업로드:

비동기 모드에서는 두 가지 방법으로 파일을 업로드할 수 있습니다.

요청에 파일 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
  }
}

미디어 API 사용(동기 모드에서 따름).

사용자 연결 문제

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

사용자 연결의 전제 조건:

메시지 인증은 필수입니다.
- sys_cs_provider_application에 메시지 인증이 없으면 사용자 연결이 작동하지 않습니다.
- 메시지 인증을 올바르게 구성해야 합니다. (인증 섹션을 참조하십시오.)
필수 요청 필드입니다.
- userId 가 존재하고 고유해야 합니다.
- emailId 가 존재하고 유효해야 합니다.

사용자 기록 요구 사항:

emailId는 아래 조건을 모두 충족하는 sys_user 기록과 일치해야 합니다.

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

주:

여러 사용자가 동일한 이메일을 사용하는 경우 연결에 실패합니다.

자동 연결 구성:

제공자 구성을 확인합니다.

sys_cs_provider 테이블로 이동하여 "VA 봇에서 봇 제공자로" 기록을 엽니다.

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

제공자 사용자 맵을 확인합니다.
- provider_user_map 테이블로 이동합니다.
- 필터 기준: 활성=아니오 및 channel_user_id={요청의 userId}.
- 문제: 활성=아니오인 기록이 있으면 사용자를 자동으로 연결할 수 없습니다.
- 해결 방법: 관리자는 비활성 기록을 수동으로 삭제하고 연결 요청을 다시 시도해야 합니다.
사용자 지정을 확인합니다.
- sn_va_as_service.virtual_agent__bot_to_bot_auto_link_account 스크립트를 실행하여 사용자 지정을 검토합니다.
- 일반적인 커스터마이제이션 문제를 확인합니다.
  - 자동 연결을 방지하는 논리
  - 추가 유효성 확인 검사
  - 수정된 필드 매핑

사용자 연결 문제 해결 검사 목록:

구성:
- 메시지 인증이 존재하며 활성 상태입니다.
- userId 가 요청에 있습니다.
- emailId 가 요청에 있습니다.
- automatic_link_enabled = 예
- automatic_link_action 올바른 스크립트를 가리킵니다.
- link_account_enabled = 예
사용자 기록:
- 사용자가 sys_user에 있습니다.
- 이메일이 정확히 일치합니다(대/소문자 구분).
- 사용자가 활성 상태입니다.
- 사용자가 잠기지 않았습니다.
- 한 명의 사용자만 이메일과 일치합니다.
제공자 사용자 맵:
- 이 userId에 대한 비활성 기록이 없습니다.
- 중복 매핑을 검사합니다.
사용자 지정:
- 자동 링크 스크립트에서 수정 사항을 검토합니다.
- 사용자 지정된 경우 OOB 스크립트로 테스트합니다.