OpenFrame API

Zurich API 참조

Release

zurich

ft:locale

ko-KR

ft:publication_title

Zurich API 참조

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

OpenFrame API

릴리스 버전: Zurich

업데이트 날짜 2025년 07월 31일

소요 시간: 15분

OpenFrame API는 CCaaS(Contact Center as a Service)에 운영 핸들러를 사용하지 않고 상호작용 기록을 생성하고 업데이트할 수 있는 기능을 제공하는 엔드포인트를 제공합니다.

이 API를 사용하여 에이전트 전화 통화를 추적하기 위한 상호작용 기록을 생성합니다. 상호작용 기록이 생성되면 에이전트가 전화를 받을 때 상호작용이 자동으로 표시될 CSM 구성 가능 작업 공간 수 있습니다.

이 API에 액세스하려면 인스턴스에 com.sn_openframe_store 플러그인이 설치되어 있어야 하며 호출하는 사용자에게 sn_openframe_api_user 또는 sn_openframe_user 역할이 있어야 합니다. OpenFrame API는 sn_openframe 네임스페이스에서 실행됩니다.

CSM 음성 상호작용 기록에 대한 자세한 내용은 다음 문서를 참조하십시오 CSM voice interaction record page.

openframe - PATCH /openframe/voice-interaction/{interactionSysId}

상호작용 [interaction] 테이블에 지정된 상호작용 기록을 업데이트합니다. 그런 다음 CCaaS(서비스형 컨택 센터) 제공업체는 이러한 레코드를 사용하여 전화 통화를 추적할 수 있습니다.

URL 형식

버전이 지정된 URL: /api/now/openframe/{api_version}/voice-interaction/{interactionSysId}

기본 URL: /api/now/openframe/voice-interaction/{interactionSysId}

주:

사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

지원되는 요청 매개변수

표 1. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열
interactionSysId	업데이트할 상호작용 기록의 Sys_id입니다. 이 값은 음성 상호 작용 만들기/POST 엔드포인트에서 반환됩니다. 데이터 유형: 문자열 테이블: 상호작용 [interaction]

표 2. 쿼리 매개변수
이름	설명
없음

표 3. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
상호작용	필수 음성 상호작용에 대한 상세 정보입니다. 하나 이상의 매개변수를 전달해야 합니다. 데이터 유형: 객체 `"interaction": { "additionalParams": {Object}, "callbackPhoneNumber": "String", "clientSessionId": "String", "inboundId": "String", "userPhoneNumber": "String" }`
interaction.additionalParams	연결된 상호작용 기록 필드와 해당 값의 이름-값 쌍입니다. 예: `"additionalParams": { "direction": "inbound", "short_description": "New outbound call", "assigned_to": "a8f98bb0eb32010045e1a5115206fe3a" }` 데이터 유형: 객체 기본값: 없음
interaction.callbackPhoneNumber	호출자의 콜백 전화 번호입니다. 통화가 끊어지는 경우 에이전트가 발신자에게 연락하는 데 사용하는 번호입니다. 데이터 유형: 문자열 형식: E.164 기본값: 없음
interaction.clientSessionId	이 전화 통화를 추적하는 데 사용되는 외부 시스템 기록의 고유 식별자입니다. 이 정보는 두 시스템 간의 기록을 연결합니다. 데이터 유형: 문자열 기본값: 없음
interaction.inboundId	음성 서비스에 대한 애플리케이션 제공자의 고유 식별자입니다. 테이블: 제공자 채널 애플리케이션 [sys_cs_provider_application] 테이블의 인바운드 ID 필드입니다. 기본값: 없음
interaction.userPhoneNumber	음성 상호작용과 관련된 전화를 건 사용자의 전화 번호입니다. 데이터 유형: 문자열 형식: E.164
interactionContext	설정할 상호작용 컨텍스트 변수입니다. 상호작용 기록에 저장할 상호작용 컨텍스트 변수의 이름-값 쌍입니다. 이러한 값은 CCaaS에 의해 결정됩니다. 예: `"interactionContext":{ "devicetype": "genesys", "requester_session_language": "en-US" }` 데이터 유형: 객체 기본값: 없음
phoneLogs	통화를 생성하고 연결할 전화 로그의 이름-값 쌍입니다. 전화 로그 [sn_open_frame_phone_log] 테이블에서 원하는 필드를 지정할 수 있습니다. 예: `"phoneLogs":[ { "agent": "String", "call_id": "String", "start_time": "String" } ]` 데이터 유형: 객체 배열 기본값: 없음
관련 기록	호출과 관련된 레코드입니다. 데이터 유형: 객체 배열 `"relatedRecords":[ { "documentId": "String", "documentTable": "String" } ]` 기본값: 없음
relatedRecords.documentId	관련 기록의 Sys_id입니다. 데이터 유형: 문자열 테이블: 매개변수에 relatedRecords.documentTable 지정됩니다.
relatedRecords.documentTable	관련 기록이 들어 있는 테이블의 이름입니다. 데이터 유형: 문자열

헤더

다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

표 4. 요청 헤더
헤더	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json
콘텐츠-형식	요청 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

표 5. 응답 헤더
헤더	설명
없음

상태 코드

다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

표 6. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.
400	잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
500	내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

응답 본문 매개변수(JSON 또는 XML)


이름	설명
상태	기록 업데이트의 상태입니다. 가능한 값: 성공: 상호작용 기록이 성공적으로 업데이트되었습니다. 실패: 상호작용 기록이 업데이트되지 않았습니다.

cURL 요청

다음 코드 예제에서는 상호작용 기록을 sys_id 12961fff7fb2d2102d0cd3cf8c86652b로 업데이트하는 방법을 보여줍니다.

curl "http://instance.service-now.com/api/now/openframe/voice-interaction/12961fff7fb2d2102d0cd3cf8c86652b" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"interaction\":{
      \"additionalParams\":{
         \"direction\":\"inbound\",
         \"short_description\":\"New Poonam outbound call\",
         \"assigned_to\":\"a8f98bb0eb32010045e1a5115206fe3a\"
      }
   },
   \"interactionContext\":{
      \"devicetype\":\"genesys\",
      \"requester_session_language\":\"en-US\"
   },
   \"phoneLogs\":[
      {
         \"call_id\":\"2323223\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"33535353\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"1997654\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      }
   ],
   \"relatedRecords\":[
      {
         \"documentTable\":\"csm_consumer\",
         \"documentId\":\"59e788fbdb1b1200b6075200cf9619d2\"
      },
      {
         \"documentTable\":\"sys_user\",
         \"documentId\":\"62826bf03710200044e0bfc8bcbe5df1\"
      }
   ]
}" \
--user 'username':'pasword'

응답:

{
  "result": {
    "status": "SUCCESS"
  }
}

openframe - POST /openframe/voice-interaction

에이전트가 통화를 수락하면 상호작용 [interaction] 테이블에 상호작용 기록이 만들어집니다. 그런 다음 CCaaS(서비스형 컨택 센터) 제공업체는 이러한 레코드를 사용하여 전화 통화를 추적할 수 있습니다.

이 엔드포인트를 사용하여 전화 통화를 수락할 때 채팅 및 케이스와 같은 다른 네이티브 채널과 마찬가지로 에이전트에게 일관된 환경을 제공합니다.