가상 에이전트 봇 통합 API
가상 에이전트 봇 통합 API는 사용자가 모든 채팅 인터페이스 또는 봇 생태계 ServiceNow 가상 에이전트 를 및/또는 라이브 에이전트.
이 API는 sn_va_as_service 네임스페이스와 함께 제공되는 대화형 사용자 지정 채팅 통합 프레임워크를 가상 에이전트 기반으로 하며 작동합니다.
봇 통합 API 설치 및 구성에 대한 자세한 내용은 가상 에이전트 API를 가상 에이전트 참조하세요.
VA 봇 통합 - POST /sn_va_as_service/bot/integration
지정된 메시지, 첨부 파일 또는 URL을 지정된 보조 ServiceNow 가상 에이전트 (VA) 봇으로 보냅니다.
고객의 사이트에는 하나 이상의 보조 ServiceNow 봇이 있을 수 있습니다. VA 보조 봇에 ServiceNow 메시지를 전달하는 것 외에도 기본 봇 또는 채팅 클라이언트는 이 엔드포인트를 사용하여 채팅을 통해 라이브 에이전트 에이전트에게 메시지를 전달할 수 있습니다. 요청 본문에 전달된 action 매개 변수를 사용하여 지정된 콘텐츠를 처리하는 방법을 지정합니다.
주:
이 엔드포인트는 구성 방법에 따라 동기식 또는 비동기식일 수 있습니다. 비동기적인 경우 엔드포인트에서 요청을 수신하면 요청의 유효성을 검사하고 성공 또는 실패의 호출 상태와 적절한 HTTP 상태 코드로 응답합니다. 그런 다음 VA는 요청을 처리하고 구성된 응답 엔드포인트에 두 번째 응답을 보냅니다. 예를 들어 봇 대 봇 통합의 경우 두 번째 응답은 기본 봇의 URL에 대한 응답입니다. 이 두 응답은 모두 아래에 정의되어 있습니다. 이 구성된 응답 엔드포인트에 대한 자세한 내용은 가상 에이전트 API에 대한 출력 응답 REST 엔드포인트 및 아웃바운드 인증 구성을 참조하십시오.
주:
이 엔드포인트에 대한 코드 예제의 응답은 VA에서 구성된 응답 엔드포인트로 전송되는 내용을 보여 줍니다. 이 엔드포인트에 대한 실제 응답(단순 성공 또는 실패 응답)은 표시되지 않습니다.
URL 형식
기본 URL: /api/sn_va_as_service/bot/integration
지원되는 요청 매개변수
| 이름 | 설명 |
|---|---|
| 없음 |
| 이름 | 설명 |
|---|---|
| 없음 |
| 이름 | 설명 |
|---|---|
| 작업 | VA가 수행해야 하는 작업입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 문자열 기본값: Null |
| 봇투봇 | 대화가 봇 사이(예: 기본 봇과 보조 봇 사이)인지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 기본값: true |
| clientSessionId (영문) | 최종 사용자가 봇과 통신하는 데 사용하는 애플리케이션/서비스의 고유한 클라이언트 세션 식별자입니다 ServiceNow . 이 ID는 특정 사용자 대화에 대한 요청/응답 집합을 식별하는 데 도움이 됩니다. 이 매개변수의 형식은 구현자에 의해 결정됩니다. 데이터 유형: 문자열 기본값: Null |
| 클라이언트 변수 | 응답으로 다시 전송되는 JSON 형식의 이름-값 쌍을 통과합니다. 이러한 값은 엔드포인트에서 처리되지 않지만 대화에 연결된 특정 고객 정보를 유지하는 데 사용할 수 있습니다. 데이터 유형: 객체 기본값: Null |
| 컨텍스트 변수 | 사용자에 대한 추가 정보를 제공하는 JSON 형식의 이름-값 쌍입니다. 이 정보를 제공하여 대화 환경을 사용자 지정합니다. 컨텍스트 변수에 대한 자세한 내용은 채팅 컨텍스트 변수 정의 및 게시를 참조하십시오. 예: 데이터 유형: 객체 기본값: Null |
| 이메일ID | 계정 연결을 활성화할 때 필요하며, 그렇지 않으면 모든 사용자가 게스트 사용자로 간주됩니다. 채팅 클라이언트 최종 사용자의 이메일 주소, 봇이 상호작용하는 사람입니다. 계정 연결에 대한 자세한 내용은 가상 에이전트 대화를 위해 ServiceNow 사용자 계정을 메시징 애플리케이션에 연결을 참조하십시오. 데이터 유형: 문자열 |
| 역사 | 사용자의 초기 요청으로 시작하는 기본 봇과 사용자 간의 대화 이력입니다. 데이터 유형: 객체 예: |
| history.displayName | 메시지를 받은 사용자의 이름입니다. 기본 봇인 경우 봇을 전달합니다. 데이터 유형: 문자열 |
| history.isBotMessage | 기본 봇이 메시지를 보냈는지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 부울 |
| history.type | 보낸 메시지의 유형입니다. 유효한 값: text 데이터 유형: 문자열 |
| 역사.값 | 정보의 컨텐츠입니다. 예를 들어, 메시지 텍스트입니다. 데이터 유형: 문자열 |
| 의도 | 대화의 의도를 설명합니다. 매개변수가 actionSWITCH로 설정된 경우 이 정보를 제공합니다.데이터 유형: 객체 |
| 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. 데이터 유형: 문자열 기본값: 인스턴스의 ServiceNow GMT 시간대 |
| 주제 | 사용자가 항목 이름을 지정하여 특정 항목으로 전환하려는 경우 필요합니다. 전환할 주제의 이름-값 쌍입니다. 주제 이름 또는 주제 sys_id 지정할 수 있습니다. 주: 개체에 하나의 토픽 이름 또는 ID만 지정할 수 있습니다. 데이터 유형: 객체 예: |
| topic.name | 전환할 주제의 이름입니다. 가상 에이전트 주제 [sys_cs_topic] 테이블의 이름 필드에 있습니다. 데이터 유형: 문자열 |
| topic.id | 전환할 주제의 Sys_id입니다. 가상 에이전트 주제 [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 | 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다. |
응답 본문 매개변수
엔드포인트 호출의 상태입니다. 초기 호출 요청이 수신될 때 응답으로 전송됩니다. 요청이 아직 처리되지 않았습니다.
| 이름 | 설명 |
|---|---|
| 오류 | 감지된 오류에 대한 설명입니다. 오류가 발생한 경우에만 반환됩니다. 데이터 유형: 객체 |
| 오류.상세 정보 | 발생한 오류에 대한 상세 정보입니다. 데이터 유형: 문자열 |
| 오류.메시지 | 오류 메시지가 발생했습니다. 데이터 유형: 문자열 |
| 상태 | 엔드포인트 호출의 상태입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 문자열 |
VA 응답 본문 매개변수
VA에서 구성된 응답 엔드포인트로 전송되는 응답 본문입니다.
| 이름 | 설명 |
|---|---|
| agentChat | 대화 ServiceNow 라이브 에이전트가 . 가능한 값:
데이터 유형: 부울 |
| 본문 | 응답 메시지 본문의 요소를 설명하는 객체 목록입니다. 데이터 유형: 배열 |
| body.actionType | 보조 봇이 기본 봇에 디스패치한 작업 메시지의 유형입니다. 예를 들어 표시기 또는 에이전트 대기 시간을 입력합니다. 유효한 값은 다음과 같습니다.
예: 입력 표시기가 활성화된 경우 최종 사용자에게 대기 시간을 표시하기 라이브 에이전트 위해 전송할 때 데이터 유형: 문자열 |
| body.agentInfo | 에이전트 채팅 설정에서 활성화된 경우 연결된 에이전트의 이름과 아바타입니다. 데이터 유형: 객체 예: |
| body.agentInfo.agent아바타 | 에이전트와 연결된 아바타 파일의 URL입니다. 예: "https://instance.servicenow.com/ee4eebf30a0004d963b5c5ac0d734dc4.iix?t=small" 데이터 유형: 문자열 |
| body.agentInfo.agentName | 에이전트의 표시 이름입니다. 데이터 유형: 문자열 |
| body.agentInfo.sentFromAgent | 메시지를 라이브 에이전트에 의해 전송되었는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| body.data (영문) | 카드 내의 데이터를 정의하는 JSON 문자열입니다. 데이터 유형: 문자열 |
| body.group | 본문 요소가 속한 리치 컨트롤 그룹입니다. 아웃바운드 변환 스크립트를 작성하여 이러한 기본 통제를 추가로 변환할 수 있습니다. 이러한 스크립트에 대한 자세한 내용은 가상 에이전트 작업 스크립트를 참조하십시오. 가능한 값:
데이터 유형: 문자열 |
| body.header | 링크 헤더입니다. 데이터 유형: 문자열 |
| body.height | HTML 요소의 높이입니다. 데이터 유형: 숫자 단위: 픽셀 |
| body.itemType | 본문 요소의 유형입니다. 가능한 값: (대/소문자 구분)
데이터 유형: 문자열 |
| body.label | 연결된 요소에 대해 표시할 레이블입니다. 데이터 유형: 문자열 |
| body.maskType | 연결된 데이터의 민감도를 나타냅니다. 가능한 값:
데이터 유형: 문자열 |
| body.maxCount (영문) | is FileUpload인 경우에만 uiType 반환됩니다. 한 번에 업로드할 수 있는 최대 첨부 파일 수입니다.데이터 형식: 숫자(정수) |
| body.maxSize | is FileUpload인 경우에만 uiType 반환됩니다. 업로드할 수 있는 첨부 파일의 최대 크기입니다.데이터 형식: 숫자(정수) 단위: 메가바이트 |
| body.message | startSpinner인 경우에만 actionType 반환됩니다. 사용자에게 표시할 메시지입니다.데이터 유형: 문자열 |
| body.multiSelect | 사용자가 여러 옵션을 선택할 수 있는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| body.nluTextEnabled | 사용자 채팅 클라이언트가 NLU(자연어 이해) 문자 메시지를 수신할 수 있는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| 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 매개변수에 표시할 값입니다. 데이터 유형: 문자열 |
| body.promptMsg | 선택기 컨트롤과 함께 표시할 프롬프트 메시지입니다. 데이터 유형: 문자열 |
| body.required입니다. | 최종 사용자가 body 요소의 쿼리에 응답해야 하는지 여부를 나타내는 플래그입니다. 가능한 값:
데이터 유형: 부울 |
| body.spinnerType | startSpinner인 경우에만 actionType 반환됩니다. 채팅 사용자에게 표시되는 스피너 유형입니다.가능한 값: wait_time: 라이브 에이전트로 전송되기 전의 지연 시간을 나타내는 메시지입니다. 데이터 유형: 문자열 |
| body.style | 본문 요소의 스타일입니다. 가능한 값:
데이터 유형: 문자열 |
| body.templateName | 연결된 카드를 표시하는 데 사용할 템플릿의 이름입니다. 데이터 유형: 문자열 |
| body.type | DefaultOutputLink에 대해서만 반환됩니다. 반환 데이터의 유형입니다. 가능한 값: link 데이터 유형: 문자열 |
| body.uiType | 본문 요소의 유형입니다. 가능한 값은 매개변수의 값에 body.group 따라 다릅니다. 이러한 값은 가상 에이전트 디자이너에서 정의된 컨트롤에 다시 매핑됩니다. 자세한 내용은 가상 에이전트 디자이너 시작하기를 참조하십시오. 가능한 값:
데이터 유형: 문자열 |
| body.value | 본문 요소를 처리하는 데 사용할 데이터입니다. 다시 전달되는 정보의 형식은 본문 요소의 형식에 따라 달라집니다. OutputLink: 개체입니다. OutputImage: 문자열입니다. 이미지 URL입니다. OutputHtml: 문자열입니다. 클라이언트가 렌더링해야 하는 HTML. 데이터 형식: 문자열 또는 개체 |
| body.value.action | DefaultOutputLink에 대해서만 반환됩니다. 반환된 링크의 URL입니다. 데이터 유형: 문자열 |
| body.대기 시간 | 사용자가 라이브 에이전트에 연결되기 전에 기다려야 하는 시간입니다. 데이터 유형: 문자열 |
| body.width | 연결된 HTML 요소의 너비입니다. 데이터 유형: 숫자 단위: 픽셀 |
| clientSessionId (영문) | 최종 사용자가 봇과 통신하는 데 사용하는 채팅 애플리케이션/서비스의 고유 클라이언트 세션 식별자입니다 ServiceNow . 데이터 유형: 문자열 |
| 클라이언트 변수 | 요청 본문의 매개변수에 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 님 | 현재 사용되지 않습니다. |
| nowSessionId입니다. | 현재 사용되지 않습니다. |
| requestId | 이 요청에 대한 고유 식별자입니다. 데이터 유형: 문자열 |
| 점수 | 모델의 의도 신뢰도 점수 ServiceNow NLU 로, 백분율로 지정됩니다(예: 87.3%). 이 점수를 통해 기본 봇은 기본 봇 NLU 모델의 신뢰도 임계치에 따라 연결된 의도를 표시할지 여부를 결정할 수 있습니다. ServiceNow NLU 모델의 신뢰도 임계치는 인스턴스에서 ServiceNow 무시되므로 기본 봇 NLU 의 모델의 신뢰도 임계치가 모든 보조 봇에 일관되게 적용될 수 있습니다. 데이터 유형: 숫자 |
| 테이크컨트롤 | 기본 봇에 제어를 다시 넘겨주려고 함을 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
} 대화를 발화 사용으로 라이브 에이전트 전환
다음 예제에서는 매개 변수에서 message.textagent를 말로 전달하여 인사말 항목을 무시하고 대화를 라이브 에이전트로 전송하는 방법을 보여 줍니다. 가능한 발언 값은 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 지원으로 전송하는 것을 보여줍니다.
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
}작업 매개변수를 설정하여 대화를 종료합니다.라이브 에이전트
다음 예제에서는 매개 변수를 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": "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로 대화를 전송하는 방법을 보여줍니다. 먼저 특정 조건으로 대기열을 설정해야 합니다. 그런 다음 요청 본문에서와 같이 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 첨부 파일 전송
이 예는 public application/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
}