가상 에이전트 봇 통합 API
Virtual Agent 봇 통합 API는 사용자가 모든 채팅 인터페이스 또는 봇 생태계를 ServiceNow 가상 에이전트 및/또는 Live Agent와 통합할 수 있는 엔드포인트를 제공합니다.
이 API는 네임스페이스에서 가상 에이전트 제공되며 네임스페이스에서 작동하는 대화형 사용자 지정 채팅 통합 프레임워크를 기반으로 합니다 sn_va_as_service .
Bot Integration API 설치 및 구성에 대한 자세한 내용은 Virtual Agent API를 가상 에이전트 참조하세요.
VA 봇 통합 - POST /sn_va_as_service/bot/integration
지정된 메시지, 첨부 파일 또는 URL을 지정된 보조 ServiceNow 가상 에이전트 (VA) 봇으로 보냅니다.
고객의 사이트에는 하나 이상의 보조 ServiceNow 봇이 있을 수 있습니다. VA 보조 봇에 메시지를 전달하는 것 외에도 기본 봇 또는 채팅 클라이언트는 이 엔드포인트를 사용하여 채팅을 통해 Live Agent 에이전트에게 메시지를 ServiceNow 전달할 수 있습니다. 요청 본문에 전달된 action 매개 변수를 사용하여 지정된 콘텐츠를 처리하는 방법을 지정합니다.
주:
이 엔드포인트는 구성 방법에 따라 동기식 또는 비동기식일 수 있습니다. 비동기인 경우 엔드포인트에서 요청을 받으면 요청의 유효성을 검사하고 성공 또는 실패의 호출 상태와 적절한 HTTP 상태 코드로 응답합니다. 그런 다음 VA는 요청을 처리하고 구성된 응답 엔드포인트에 두 번째 응답을 보냅니다. 예를 들어 봇 대 봇 통합의 경우 두 번째 응답은 기본 봇의 URL에 대한 것입니다. 이 두 응답은 모두 아래에 정의되어 있습니다. 이 구성된 응답 엔드포인트에 대한 자세한 내용은 Virtual Agent API에 대한 출력 응답 REST 엔드포인트 및 아웃바운드 인증 구성을 참조하십시오.
주:
이 엔드포인트에 대한 코드 예제의 응답은 VA에서 구성된 응답 엔드포인트로 전송되는 내용을 보여줍니다. 이 엔드포인트에 대한 실제 응답(단순 성공 또는 실패 응답)은 표시하지 않습니다.
URL 형식
기본 URL: / api/sn_va_as_service/bot/integration
지원되는 요청 매개변수
| 이름 | 설명 |
|---|---|
| 없음 |
| 이름 | 설명 |
|---|---|
| 없음 |
| 이름 | 설명 |
|---|---|
| 작업 | VA가 수행해야 하는 작업입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 문자열 기본값: Null |
| 봇투봇 | 봇 간의 대화(예: 기본 봇과 보조 봇 간)를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 기본값: true |
| clientSessionId | 최종 사용자가 봇과 통신하는 데 사용하는 애플리케이션/서비스의 고유한 클라이언트 세션 식별자입니다 ServiceNow . 이 ID는 특정 사용자 대화에 대한 요청/응답 집합을 식별하는 데 도움이 됩니다. 이 매개 변수의 형식은 구현자가 결정합니다. 데이터 유형: 문자열 기본값: Null |
| client변수 | 응답에서 다시 전송되는 통과 JSON 형식의 이름-값 쌍입니다. 이러한 값은 엔드포인트에서 처리되지 않지만 특정 고객 정보를 대화에 첨부하는 데 사용할 수 있습니다. 데이터 유형: 객체 기본값: Null |
| 컨텍스트 변수 | 사용자에 대한 추가 정보를 제공하는 JSON 형식의 이름-값 쌍입니다. 이 정보를 제공하여 대화 환경을 사용자 지정합니다. 컨텍스트 변수에 대한 자세한 내용은 채팅 컨텍스트 변수 정의 및 게시를 참조하십시오. 예: 데이터 유형: 객체 기본값: Null |
| 이메일 ID | 계정 연결을 활성화할 때 필요하며, 그렇지 않으면 모든 사용자가 게스트 사용자로 간주됩니다. 채팅 클라이언트 최종 사용자, 봇이 상호작용하는 사람의 이메일 주소입니다. 계정 연결에 대한 자세한 내용은 Virtual Agent 대화용 메시징 애플리케이션에 ServiceNow 사용자 계정 연결을 참조하십시오. 데이터 유형: 문자열 |
| 역사 | 사용자의 초기 요청으로 시작하는 기본 봇과 사용자의 대화 이력입니다. 데이터 유형: 객체 예: |
| history.displayName | 메시지를 받은 사용자의 이름입니다. 기본 봇인 경우 Bot을 전달합니다. 데이터 유형: 문자열 |
| history.isBotMessage | 기본 봇이 메시지를 보냈는지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 부울 |
| history.type | 보낸 메시지의 유형입니다. 유효한 값은 다음과 같습니다. text 데이터 유형: 문자열 |
| 이력.값 | 정보의 내용입니다. 예를 들면 메시지 텍스트입니다. 데이터 유형: 문자열 |
| 의도 | 대화의 의도를 설명합니다. 매개변수가 SWITCH로 설정될 때 action 이 정보를 제공합니다.데이터 유형: 객체 |
| intent.id | NLU 대화를 전환할 시스템 주제의 의도 ID입니다. CS 주제 언어[sys_cs_topic_language] 테이블에 있습니다. intent.id 채팅 세션에서 전달된 언어에 따라 해결됩니다. 대화를 시작할 때 언어가 전달되지 않으면 사용자의 세션/프로필에서 언어를 가져옵니다. 데이터 유형: 문자열 |
| 메시지 | 필수 봇에 보낼 메시지의 상세 정보입니다 ServiceNow . 데이터 유형: 객체 |
| message.attachment | 첨부 파일을 보내는 경우 필요합니다. 첨부 파일의 상세 정보입니다. 첨부 파일은 URL로만 전달할 수 있으며 호출당 하나의 첨부 파일만 전달할 수 있습니다. 모든 첨부 파일에서 바이러스 검사가 트리거됩니다. 데이터 유형: 객체 |
| message.attachment.clientAttachmentId | 봇에 보낼 첨부 파일의 고유 식별자입니다 ServiceNow . 이 식별자의 형식은 구현자에 의해 결정됩니다. 데이터 유형: 문자열 기본값: Null |
| message.attachment.contentType | 첨부 파일이 지정된 경우 필수입니다. 첨부 파일의 표준 MIME 유형입니다. 유효한 값(대/소문자 구분 안 함):
데이터 유형: 문자열 |
| message.attachment.fileName | 첨부 파일이 지정된 경우 필수입니다. 첨부 파일의 이름입니다. 데이터 유형: 문자열 |
| message.attachment.headers | 첨부 파일이 비공개이고 보호되는 경우 필요한 추가 정보입니다. 데이터 유형: 객체 |
| message.attachment.headers.Authorization | 사용자 이름 및 암호와 같이 첨부 파일에 액세스하기 위한 권한을 얻는 데 필요한 정보입니다. 데이터 유형: 문자열 |
| message.attachment.url | 첨부 파일이 지정된 경우 필수입니다. 첨부 파일이 있는 URL입니다. VA는 이 URL에서 첨부 파일을 가져오고 바이러스 검사를 실행한 다음 파일을 처리합니다. 첨부 파일이 공용 파일이 아닌 경우 첨부 파일에 액세스할 수 있도록 권한 부여 정보가 포함된 개체를 전달 message.attachment.header 해야 합니다. 또한 URL 도메인이 에 보관 sys_cs_provider된 신뢰할 수 있는 도메인에 있는지 확인해야 합니다. 데이터 유형: 문자열 |
| message.clientMessageId | 메시지의 고유한 영숫자 식별자입니다. 이 식별자의 형식은 구현자에 의해 결정됩니다. 데이터 유형: 문자열 기본값: Null |
| message.text | 매개 변수를 지정하지 않은 경우 attachment 필요합니다. 메시지 텍스트입니다. 메시지 언어는 매개 변수에 전달 contextVariables 되어야 합니다. 데이터 유형: 문자열 최대 길이: 무제한 |
| message.typed | 필수 메시지가 입력되었는지 또는 옵션 선택(선택됨)인지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 부울 |
| requestId | 필수 이 요청의 고유한 영숫자 식별자입니다. 이 식별자의 형식은 구현자에 의해 결정됩니다. 데이터 유형: 문자열 |
| 사일런트메시지 | 이 메시지가 무음 메시지인지 여부를 나타내는 플래그입니다. 무음 메시지는 응답이 필요하지 않은 메시지입니다. 유효한 값은 다음과 같습니다.
주: silentMessage = true인 요청이 전송되면 silentMessage = false를 전달하여 자동 모드를 해제하는 요청이 전송될 때까지 모든 후속 봇 메시지가 억제된 상태로 유지됩니다.데이터 유형: 부울 기본값: false |
| 타임스탬프 | 채팅 클라이언트의 최종 사용자가 메시지를 보낸 Unix epoch 시간입니다. 데이터 유형: 숫자 단위: 밀리초 기본값: 현재 시간 |
| 시간대 | 채팅 클라이언트의 최종 사용자의 GMT 시간대입니다. 예: 사용 가능한 표준 시간대 값 목록은 을 참조하십시오 https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. 데이터 유형: 문자열 기본값: 인스턴스의 GMT 시간대입니다 ServiceNow . |
| 주제 | 사용자가 주제 이름을 지정하여 특정 주제로 전환하려는 경우 필요합니다. 전환할 주제의 이름-값 쌍입니다. 주제 이름 또는 주제 sys_id 지정할 수 있습니다. 주:
객체에 하나의 토픽 이름 또는 ID만 지정할 수 있습니다. 데이터 유형: 객체 예: |
| topic.name | 전환할 주제의 이름입니다. Virtual Agent 주제 [sys_cs_topic] 테이블의 이름 필드에 있습니다. 데이터 유형: 문자열 |
| topic.id | 전환할 주제의 Sys_id입니다. Virtual Agent 주제 [sys_cs_topic] 테이블의 sys_id 필드에 있습니다. 데이터 유형: 문자열 |
| userID | 필수 고유 사용자 식별자입니다. 봇과 상호 작용하는 최종 사용자의 식별자입니다. 데이터 유형: 문자열 |
머리글
다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에서 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.
| 헤더 | 설명 |
|---|---|
| 수용 | 응답 본문의 데이터 형식입니다. application/json만 지원합니다. |
| 컨텐츠-형식 | 요청 본문의 데이터 형식입니다. application/json만 지원합니다. |
| 토큰 | 토큰 기반 인증을 사용하는 경우 필요합니다. 기본 또는 OAuth 인증의 경우 선택 사항입니다. 이 엔드포인트에 대해 토큰 인증을 설정한 경우 사용할 인증 토큰입니다. 데이터 유형: 문자열 |
| 헤더 | 설명 |
|---|---|
| 없음 |
상태 코드
다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.
| 상태 코드 | 설명 |
|---|---|
| 200 | 성공입니다. 요청이 성공적으로 처리되었습니다. 200 상태 코드를 받았지만 응답을 받지 못한 경우 다음 사항을 확인하세요.
|
| 400 | 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다. |
| 401 | 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다. |
| 405 | 잘못된 메서드입니다. 기능이 비활성화되었습니다. |
| 500 | 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다. |
응답 본문 매개변수
엔드포인트 호출의 상태입니다. 초기 호출 요청이 수신될 때 응답으로 전송됩니다. 요청이 아직 처리되지 않았습니다.
| 이름 | 설명 |
|---|---|
| 오류 | 탐지된 오류에 대한 설명입니다. 오류가 발생한 경우에만 반환됩니다. 데이터 유형: 객체 |
| 오류.상세 정보 | 발생한 오류에 대한 상세 정보입니다. 데이터 유형: 문자열 |
| error.message | 오류 메시지가 발생했습니다. 데이터 유형: 문자열 |
| 상태 | 엔드포인트 호출의 상태입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 문자열 |
VA 응답 본문 매개변수
VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
| 이름 | 설명 |
|---|---|
| agentChat | 대화 ServiceNow Live Agent가 . 가능한 값:
데이터 유형: 부울 |
| 본문 | 응답 메시지 본문의 요소를 설명하는 객체 목록입니다. 데이터 유형: 배열 |
| body.actionType | 보조 봇이 기본 봇에 디스패치한 작업 메시지의 유형입니다. 예를 들어 표시기 또는 에이전트 대기 시간을 입력합니다. 유효한 값은 다음과 같습니다.
예: 입력 표시기가 활성화된 경우 전송할 Live Agent 때 데이터 유형: 문자열 |
| body.agentInfo | 에이전트 채팅 설정에서 활성화된 경우, 연결된 에이전트의 이름과 아바타입니다. 데이터 유형: 객체 예: |
| body.agentInfo.agentAvatar | 에이전트와 연결된 아바타 파일의 URL입니다. 예: "https://instance.servicenow.com/ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" 데이터 유형: 문자열 |
| body.agentInfo.agentName | 에이전트의 표시 이름입니다. 데이터 유형: 문자열 |
| body.agentInfo.sentFromAgent | Live Agent가 메시지를 보냈는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| body.data | 카드 내의 데이터를 정의하는 JSON 문자열입니다. 데이터 유형: 문자열 |
| body.group | 본문 요소가 속한 리치 통제 그룹입니다. 아웃바운드 변환 스크립트를 작성하여 이러한 기본 통제를 추가로 변환할 수 있습니다. 이러한 스크립트에 대한 자세한 내용은 Virtual Agent 작업 스크립트의 내용을 참조하십시오. 가능한 값:
데이터 유형: 문자열 |
| 본문.헤더 | 링크 헤더입니다. 데이터 유형: 문자열 |
| body.height | HTML 요소의 높이입니다. 데이터 유형: 숫자 단위: 픽셀 |
| body.itemType | 본문 요소의 유형입니다. 가능한 값: (대/소문자 구분)
데이터 유형: 문자열 |
| body.label | 연결된 요소에 대해 표시할 레이블입니다. 데이터 유형: 문자열 |
| body.maskType | 연결된 데이터의 민감도를 나타냅니다. 가능한 값:
데이터 유형: 문자열 |
| body.maxCount | FileUpload인 경우에만 uiType 반환됩니다. 한 번에 업로드할 수 있는 최대 첨부 파일 수입니다.데이터 유형: 숫자(정수) |
| body.maxSize | FileUpload인 경우에만 uiType 반환됩니다. 업로드할 수 있는 첨부 파일의 최대 크기입니다.데이터 유형: 숫자(정수) 단위: 메가바이트 |
| body.message | StartSpinner인 경우에만 actionType 반환됩니다. 사용자에게 표시할 메시지입니다.데이터 유형: 문자열 |
| body.multi선택 | 사용자가 여러 옵션을 선택할 수 있는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| body.nluTextEnabled | 사용자 채팅 클라이언트가 NLU(Natural Language Understanding) 텍스트 메시지를 받을 수 있는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| body.options | 선택기 컨트롤에 사용할 수 있는 옵션을 설명하는 개체 목록입니다. 데이터 유형: 배열 |
| body.options.attachment | 검색할 캐러셀에 있는 이미지의 URL입니다. 데이터 유형: 문자열 |
| body.options.description | 캐러셀 항목에 대한 설명입니다. 데이터 유형: 문자열 |
| body.options.enabled | 최종 사용자의 채팅 클라이언트에서 선택기 컨트롤을 사용할 수 있는지 여부를 나타내는 플래그입니다. 봇 대 봇 구현에서 기본 봇은 선택기 컨트롤이 비활성화되었는지 확인해야 합니다. 가능한 값:
데이터 유형: 부울 |
| body.options.label | 연결된 body.options.value 매개변수에 대해 표시할 레이블입니다. 데이터 유형: 문자열 |
| body.options.renderStyle | 연결된 요소를 렌더링할 때 사용할 스타일입니다. 가능한 값: data 데이터 유형: 문자열 |
| body.options.value | 연결된 body.options.label 매개변수에 대해 표시할 값입니다. 데이터 유형: 문자열 |
| 본문.promptMsg | 선택기 컨트롤과 함께 표시할 프롬프트 메시지입니다. 데이터 유형: 문자열 |
| body.required | 최종 사용자가 body 요소의 쿼리에 응답해야 하는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| body.spinnerType | StartSpinner인 경우에만 actionType 반환됩니다. 채팅 사용자에게 표시되는 스피너 유형입니다.가능한 값: wait_time: Live Agent로 전송되기 전의 지연 시간을 나타내는 메시지입니다. 데이터 유형: 문자열 |
| body.style | 본문 요소의 스타일입니다. 가능한 값:
데이터 유형: 문자열 |
| body.templateName | 연결된 카드를 표시하는 데 사용할 템플릿의 이름입니다. 데이터 유형: 문자열 |
| body.type | DefaultOutputLink에 대해서만 반환됩니다. 반환 데이터의 유형입니다. 가능한 값: link 데이터 유형: 문자열 |
| body.uiType | 본문 요소의 유형입니다. 가능한 값은 매개변수의 값에 body.group 따라 달라집니다. 이러한 값은 가상 에이전트 디자이너에 정의된 컨트롤에 다시 매핑됩니다. 자세한 내용은 가상 에이전트 디자이너 시작을 참조하세요. 가능한 값:
데이터 유형: 문자열 |
| body.value | body 요소를 처리하는 데 사용할 데이터입니다. 다시 전달되는 정보의 형식은 본문 요소의 형식에 따라 달라집니다. OutputLink: 개체입니다. OutputImage: 문자열입니다. 이미지 URL입니다. OutputHtml: 문자열입니다. 클라이언트가 렌더링해야 하는 HTML입니다. 데이터 유형: 문자열 또는 객체 |
| body.value.action | DefaultOutputLink에 대해서만 반환됩니다. 반환된 링크의 URL입니다. 데이터 유형: 문자열 |
| body.waitTime | 사용자가 라이브 에이전트에 연결되기 전에 기다려야 하는 시간입니다. 데이터 유형: 문자열 |
| body.width | 연결된 HTML 요소의 너비입니다. 데이터 유형: 숫자 단위: 픽셀 |
| clientSessionId | 최종 사용자가 봇과 통신하는 데 사용하는 채팅 애플리케이션/서비스의 고유한 클라이언트 세션 식별자입니다 ServiceNow . 데이터 유형: 문자열 |
| client변수 | 요청 본문의 파라미터에 clientVariables 전달된 내용에서 복사되는 JSON 형식의 이름-값 쌍입니다. 이러한 값은 엔드포인트에서 처리되지 않지만 특정 고객 정보를 대화에 첨부하는 데 사용할 수 있습니다. 데이터 유형: 객체 |
| 완료됨 | 대화가 ServiceNow 가상 에이전트 성공적으로 완료되었는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| 엔터프라이즈 ID | 현재 사용되지 않습니다. |
| 메시지 | VA로 보낸 메시지의 상세 정보입니다 ServiceNow . 이는 전달된 메시지 개체와 동일합니다. 데이터 유형: 객체 |
| message.attachment | 첨부 파일의 상세 정보입니다. 첨부 파일은 파일 또는 URL일 수 있습니다. 데이터 유형: 객체 |
| message.attachment.clientAttachmentId | VA로 전송된 첨부 파일의 고유 식별자입니다 ServiceNow . 이 식별자의 형식은 구현자에 의해 결정됩니다. 데이터 유형: 문자열 |
| message.attachment.contentType | 첨부 파일의 표준 MIME 유형입니다. 가능한 값(대/소문자 구분 안 함):
데이터 유형: 문자열 |
| message.attachment.fileName | 첨부 파일의 이름입니다. 데이터 유형: 문자열 |
| message.attachment.url | 첨부 파일이 있는 URL입니다. 데이터 유형: 문자열 |
| message.clientMessageId | 메시지의 고유한 영숫자 식별자입니다. 데이터 유형: 문자열 |
| message.text | 메시지 텍스트입니다. 데이터 유형: 문자열 최대 길이: 무제한 |
| message.typed | 메시지가 입력되었는지 또는 옵션 선택(선택됨)인지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 부울 |
| nowBotId | 현재 사용되지 않습니다. |
| now세션 ID | 현재 사용되지 않습니다. |
| requestId | 이 요청의 고유 식별자입니다. 데이터 유형: 문자열 |
| 점수 | 모델의 의도 신뢰도 점수 ServiceNow NLU 로, 87.3%와 같이 백분율로 지정됩니다. 이 점수를 사용하면 기본 봇이 기본 봇 NLU 모델의 신뢰도 임계치에 따라 연결된 의도를 표시할지 여부를 결정할 수 있습니다. ServiceNow NLU 모델의 신뢰도 임계치는 인스턴스에서 무시 ServiceNow 되므로 기본 봇 모델의 신뢰도 임계치를 모든 보조 봇 NLU 에 일관되게 적용할 수 있습니다. 데이터 유형: 숫자 |
| takeControl | 기본 봇에게 제어권을 다시 넘기려 함을 ServiceNow 가상 에이전트 나타내는 플래그입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 부울 기본값: false |
| userID | 봇과 상호작용하는 최종 사용자의 식별자입니다. 데이터 유형: 문자열 |
START_CONVERSATION 작업을 사용하여 대화를 시작합니다
다음 예제에서는 START_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": "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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
} 발화 사용으로 Live Agent 대화 전송
다음 예제에서는 인사말 주제를 무시하고 매개 변수에 agent를 발언 message.text 으로 전달하여 대화를 Live Agent로 전송하는 방법을 보여 줍니다. 가능한 발언 값은 sys_cs_contextual_action 테이블에 정의되어 있습니다. 상황별 작업에 대한 자세한 내용은 사용자 지정 채팅 통합을 위한 상황별 작업을 참조하십시오.
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"
}"다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
}사용자의 선택에 따라 Live Agent 지원으로 대화 전송
다음 예는 이전 상호작용에서 사용자의 선택에 따라 대화를 Live Agent 지원으로 전송하는 방법을 보여줍니다.
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"
} "다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
}작업 매개변수를 설정하여 대화를 종료합니다 가상 에이전트
다음 예제에서는 매개 변수를 END_CONVERSATION로 설정하여 action 대화를 종료 가상 에이전트 하는 방법을 보여 줍니다.
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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문으로, 대화 종료를 표시합니다.
{
"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
}작업 매개변수를 설정하여 대화를 종료합니다 Live Agent
다음 예제에서는 매개 변수를 END_CONVERSATION로 설정하여 action 대화를 종료 Live Agent 하는 방법을 보여 줍니다.
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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문으로, 대화 종료를 표시합니다.
{
"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
}sys_cs_contextual_action 테이블에 정의된 명령을 대화를 시작할 발언으로 사용합니다. 가상 에이전트
다음 예제에서는 이전 예제와 같이 매개변수를 START_CONVERSATION로 설정하는 action 대신 sys_cs_contextual_action 테이블에 정의된 명령을 대화를 가상 에이전트 시작하는 발언으로 사용하는 Hi 방법을 보여줍니다. 이 예제에서는 명령의 언어 변형 중 하나인 "hola"를 Hi 사용하는 방법을 보여 줍니다.
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"
}"다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
} sys_cs_contextual_action 테이블에 정의된 명령을 발언으로 사용하여 대화를 종료합니다.
다음 예제에서는 이전 예제와 같이 END_CONVERSATION로 설정하는 action 대신 sys_cs_contextual_action 테이블에 정의된 명령을 대화를 가상 에이전트 종료하는 발언으로 사용하는 Bye 방법을 보여 줍니다. 이 예제에서는 명령의 언어 변형 중 하나인 "choa"를 Bye 사용하는 방법을 보여 줍니다.
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"
}"다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
}SWITCH 작업 매개변수를 사용하여 진행 중인 대화 변경
다음 예에서는 SWITCH action 매개 변수를 사용하여 진행 중인 대화를 매개 변수에 지정된 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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문으로, 새 주제로 전환된 VA를 보여줍니다.
{
"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
}발언에 자연어 이해 대한 (NLU) 신뢰도 점수 구하기
다음 예는 VA에서 활성화된 경우 NLU 발언에 대한 신뢰도 점수를 얻는 NLU 방법을 보여줍니다.
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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문으로, 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"
}특정 큐의 Live Agent로 대화 전송
다음 예는 특정 큐에 있는 Live Agent로 대화를 전송하는 방법을 보여줍니다. 먼저 특정 조건으로 큐를 설정해야 합니다. 그런 다음 요청 본문에서와 같이 contextVariables 해당 조건을 전달합니다. 작업 항목 큐 만들기에 대한 자세한 내용은 작업 항목 큐 만들기를 참조하세요.
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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
}공용 응용 프로그램/PDF 첨부 파일 전송
이 예제에서는 공용 응용 프로그램/PDF 첨부 파일을 전송하는 방법을 보여 줍니다.
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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
}비디오/MPEG 첨부 파일 전송
이 예제에서는 비디오/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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
}이미지/jpeg 첨부 파일 전송
이 예제에서는 image/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"
다음은 VA에서 구성된 응답 엔드포인트로 전송된 응답 본문입니다.
{
"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
}