Omichannel 콜백 API

릴리스 버전: Australia

업데이트 날짜 2026년 03월 12일

소요 시간: 70분

옴니채널 콜백 API는 라이브 에이전트 대화에 대한 콜백 요청을 생성, 업데이트 및 시작하는 메서드를 제공합니다.

옴니채널 콜백 API를 사용하면 에이전트가 사용 가능한 에이전트를 큐에서 기다리지 않고 프로그래밍 방식으로 사용자를 다시 호출할 수 있습니다. 예를 들어 에이전트는 콜백 기능을 사용하여 에이전트 대기 시간이 길거나 사용 가능한 에이전트가 없을 때 사용자에게 다시 전화를 걸 수 있습니다. 이 API를 사용하여 다음 작업을 수행할 수 있습니다.

즉각적인 새 콜백 요청을 생성하거나 새 요청을 예약합니다.
초기 상호작용 및 후속 상호작용 재시도를 생성합니다.
기존 콜백을 업데이트합니다.

이 API는 sn_omni_callback 네임스페이스에 속하며 콜백 API [sn_omni_callback.callback_api] 역할을 가진 관리자가 필요합니다.

AI 플랫폼으로서의 ServiceNow 애플리케이션에 대한 옴니채널 콜백 자세한 내용은 다음 문서를 참조하십시오Omnichannel Callback.

옴니채널 콜백 - POST api/sn_omni_callback/actions

타사 CCaaS(연락처 센터 서비스형) 플랫폼을 의 옴니채널 콜백 시스템과 ServiceNow®통합하기 위한 작업을 제공합니다. 이 API는 구성 가능한 워크플로우 스튜디오 하위 플로우를 통해 콜백 작업(생성, 업데이트, 취소, 닫기)을 외부 CCaaS 제공자에게 라우팅하는 브리지 역할을 합니다.

주:

이 엔드포인트는 및 와 옴니채널 콜백 - PATCH /api/sn_omni_callback/callback/update유사 옴니채널 콜백 - POST /api/sn_omni_callback/callback/create 하게 작동하지만 라우팅 컨텍스트와 타사 통합에서 콜백을 업데이트하거나 생성하는 데 사용됩니다.

지능형 라우팅

/actions 엔드포인트는 매개변수를 기반으로 콜백 요청을 지능적으로 라우팅합니다routingContext. 라우팅 규칙이 구성되면 API는 모든 작업에 대해 통합된 단일 페이로드 구조를 사용하고 routingContext를 사용하여 요청을 CCaaS 하위 플로우로 라우팅합니다. 라우팅이 구성되면 요청의 컨텐츠는 변경되지 않습니다. 최상위 action 값만 다릅니다.

주:

API는 매개변수를 기반으로 콜백 라우팅 구성 [sys_cs_callback_routing_config] 테이블에서 라우팅 규칙을 routingContext 확인합니다. 일치하는 규칙이 발견되면 요청이 구성된 사용자 지정 하위 플로우로 전달됩니다. 하위 플로우는 외부 CCaaS 플랫폼과 통합하거나 사용자 지정 비즈니스 논리를 구현할 수 있습니다. 하위 플로우가 요청을 처리하고 응답을 반환합니다.

이 누락되거나 라우팅 규칙과 일치하지 않는 경우 routingContext API는 기본 ServiceNow 동작으로 대체되고 해당 POST /create, PATCH /update 또는 PATCH /cancel 엔드포인트의 표준 페이로드 형식을 예상합니다.

URL 형식

버전이 지정된 URL: /api/sn_omni_callback/v1/actions

기본 URL: /api/sn_omni_callback/actions

지원되는 요청 매개변수

표 1. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오. 데이터 유형: 문자열

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

표 3. 요청 본문 매개변수
이름	설명
객체	운영 및 상세 정보를 포함하는 객체입니다. 데이터 유형: 객체 `{ "action": "String", "payload": {Object}, "routingContext": {Object} }`
작업	필수 콜백에서 수행할 작업을 정의합니다. 허용되는 값: `create`: 새 콜백 기록을 작성합니다. `update`: 콜백 번호를 기준으로 기존 콜백 기록을 업데이트합니다. `close`: 콜백 요청이 이행되었기 때문에 콜백 기록을 종결합니다. 콜백을 시작하지 않습니다. 콜백 [sys_cs_callback] 테이블에서 이유 필드를 업데이트합니다. `취소`: 고객이 요청을 취소했으며 에이전트와 연결할 필요가 없으므로 콜백 기록을 취소합니다. 콜백 [sys_cs_callback] 테이블에서 이유 필드를 업데이트합니다. 데이터 유형: 문자열
페이로드	필수 객체가 전달될 때 routingContext 지정된 작업에 필요한 특정 데이터를 포함하는 객체입니다. 닫기 및 취소 작업 callbackID 의 경우 페이로드에만 필요합니다. 주: 생성 및 업데이트 작업의 경우 전달되지 않은 경우 routingContext 각각 및 옴니채널 콜백 - PATCH /api/sn_omni_callback/callback/update 작업에 문서화된 옴니채널 콜백 - POST /api/sn_omni_callback/callback/create 객체 구조를 사용합니다payload. '예시' 섹션에서는 라우팅 시나리오와 비라우팅 시나리오를 모두 보여줍니다. 데이터 유형: 객체 payload 생성 및 업데이트 작업의 구조입니다. `{ "callbackContext": {Object}, "callbackDetails": {Object}, "callbackId": "String", "phoneNumber": "String", "type": "String" }` payload 닫기 및 취소 작업에 대한 구조입니다. `"payload": { "callbackId": "String" }`
payload.callbackContext	옵션입니다. 콜백 요청에 대한 컨텍스트 상세 정보를 포함하는 객체입니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context] 데이터 유형: 객체 `"callbackContext": { "customer_timezone": "String", "ivr_path": "String", "queue": "String" }`
payload.callbackContext.customer_timezone	콜백을 요청한 고객의 시간대입니다. 시간대는 다음 형식으로 제공할 수 있습니다. `국가/도시`: `예: 미국/Los_Angeles`. `국가/시간대`: 예: `미국/태평양`. `시간대 약어`: 예: `PST` 유효한 시간대의 전체 목록은 사용자 [sys_user] 테이블의 시간대 필드를 참조하십시오. 시간대에 대한 자세한 내용은 다음 문서를 참조하십시오 Time zones. 데이터 유형: 문자열
payload.callbackContext.ivr_path	고객이 실제 에이전트로 전송되기 전에 따르는 IVR(대화형 음성 응답) 경로입니다. 일반적으로 고객이 IVR 시스템에서 탐색한 큐 또는 메뉴 옵션 목록을 포함합니다. 이 문자열은 CCaaS(Contact Center as a Service)에 의해 전달됩니다. 예: `"ivr_path": "기술 지원 > 계정 관리"` 데이터 유형: 문자열
payload.callbackContext.queue	큐의 번호 할당입니다. 데이터 유형: 문자열
payload.callbackDetails	옵션입니다. 콜백 요청에 대한 상세 정보를 포함하는 객체입니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 객체 `"callbackDetails": { "description": "String", "end_time": "String", "expire_time": "String", "first_name": "String", "last_name": "String", "opened_by": "String", "phone_number": "String", "next_retry": "String", "reason": "String", "scheduled_start_time": "String", "short_description": "String", "state": "String", "type": "String" }`
payload.callbackDetails.description	콜백 요청에 대한 자세한 설명입니다. 특정 고객 우려 사항, 컨텍스트 또는 에이전트의 메모를 포함할 수 있습니다. 데이터 유형: 문자열
payload.callbackDetails.end_time	콜백 요청이 완료될 것으로 예상되는 기간입니다. 이 타임스탬프가 지나면 일정이 조정되지 않는 한 콜백은 기한이 지났거나 만료된 것으로 간주됩니다. `예약된` 콜백 유형에만 적용 가능합니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
payload.callbackDetails.expire_time	콜백 요청을 더 이상 시도해서는 안 되는 최종 마감 시간입니다. 이는 부실 요청을 자동으로 닫거나 취소하는 데 자주 사용됩니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
payload.callbackDetails.first_name	콜백을 요청하는 고객의 이름입니다. 데이터 유형: 문자열
payload.callbackDetails.last_name	콜백을 요청하는 고객의 성입니다. 데이터 유형: 문자열
payload.callbackDetails.opened_by	콜백 요청을 생성하거나 시작한 사용자 또는 에이전트의 Sys_id입니다. 테이블: 사용자 [sys_user]
payload.callbackDetails.phone_number	다시 전화할 고객의 전화 번호입니다. 데이터 유형: 문자열
payload.callbackDetails.next_retry	이전 콜백 시도가 실패한 경우, 예약된 다음 시도 시간입니다. 자동 또는 수동 재시도 논리에 유용합니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
payload.callbackDetails.reason	콜백 요청의 이유입니다. 표준화된 이유로 콜백에 태그를 지정하여 라우팅, 분석 및 보고를 지원합니다. 유효한 값은 다음과 같습니다. `기타 문제` 구현에서 정의한 사용자 지정 값입니다. 예: `"청구 문의"`, `"기술 지원"` 테이블: 콜백 [sys_cs_callback], 필드: reason_type 데이터 유형: 문자열
payload.callbackDetails.scheduled_start_time	콜백 기간이 시작되는 날짜 및 시간 값입니다. `예약된` 콜백 유형에만 적용 가능합니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
payload.callbackDetails.short_description	일반적으로 목록이나 대시보드에서 사용되는 콜백 요청에 대한 간략한 요약입니다. 데이터 유형: 문자열
payload.callbackDetails.state	콜백 요청의 현재 워크플로우 상태입니다. 유효한 값은 다음과 같습니다. `승인 보류 중` `진행 중` `완료됨` `취소됨` 데이터 유형: 문자열
payload.callbackDetails.type	요청의 범주입니다. 값은 항상 `콜백`입니다.
payload.callbackId	필수 콜백의 Sys_id 또는 external_id입니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열
페이로드.전화 번호	필수 콜백을 요청하는 사용자의 전화 번호입니다. 데이터 유형: 문자열
페이로드.유형	필수 콜백 유형입니다. 유효한 값: `callback_request` 데이터 유형: 문자열
routingContext	라우팅 구성에 필요합니다. 통과되지 않거나 라우팅 규칙이 일치하지 않는 경우 작업 엔드포인트는 CCaaS 하위 플로우를 호출하지 않고 기본 ServiceNow 처리 사용으로 대체됩니다. 사용자 지정 하위 플로우 또는 라우팅 규칙을 찾는 데 사용되는 상황별 정보입니다. 이 매개변수가 생략되면 API는 기본 콜백 처리를 사용합니다. 데이터 유형: 객체 `"routingContext": { "sourceTable": "String", "sourceId": "String", "userId": "String" }`
routingContext.sourceId	콜백을 시작하는 소스 기록의 Sys_id입니다. 의 값 sourceTable에 해당합니다. 데이터 유형: 문자열
routingContext.sourceTable	요청이 시작된 테이블 이름입니다. 허용되는 값: `sp_portal` `sn_csm_ec_engmnt_center_module` `sn_embeddable_core_module` 데이터 유형: 문자열
routingContext.userId	요청을 시작하는 사용자(주로 에이전트 또는 시스템 사용자)입니다. 테이블: 사용자 [sys_user] 데이터 유형: 문자열

헤더

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

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

표 5. 응답 헤더
머리글	설명
안 함

상태 코드

이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

표 6. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.

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


이름	설명
본문	요청에 대한 성공 또는 실패 정보를 포함하는 객체입니다. 데이터 유형: 객체 `{ "status": 200, "body": { "message": "String", "number": "String" } }`
본문.메시지	작업의 성공 또는 실패에 대한 간략한 세부 정보가 포함된 메시지입니다. 데이터 유형: 문자열
본문.번호	콜백 참조 번호입니다. 예: `"CAL0010012"`. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열
상태	요청의 해당 상태 코드입니다. 데이터 유형: 문자열

예제 작성(라우팅 사용)

이 작업은 라우팅 컨텍스트가 구성된 새 콜백 기록을 작성합니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "create",
  "routingContext": {
    "sourceTable": "sn_csm_ec_engmnt_center_module",
    "sourceId": "a1b2c3d4e5f6a7b8",
    "userId": "beth.anglin"
  },
  "payload": {
    "callbackId": "cb-98765",
    "callbackDetails": {
      "first_name": "Alice",
      "last_name": "Smith",
      "state": "Pending Approval",
      "reason": "Request updated by user",
      "end_time": "2025-12-17T23:00:00Z",
      "scheduled_start_time": "2025-12-17T22:00:00Z",
      "next_retry": "2025-12-18T10:00:00Z",
      "expiry_time": "2025-12-18T12:00:00Z",
      "phone_number": "+14155552671",
      "short_description": "Callback request for customer support",
      "description": "Customer requested a callback regarding their recent order.",
      "opened_by": "user_sys_id_12345",
      "type": "callback"
    },
    "type": "callback_request",
    "phoneNumber": "+14155552671",
    "callbackContext": {
      "queue": "Customer Support",
      "ivr_path": "support/ivr-path",
      "customer_timezone": "GMT-5"
    }
  },
  "additional_parameters": {}
}

생성(라우팅 컨텍스트 없음)

다음 예제에서는 라우팅 컨텍스트 없이 새 콜백 기록을 생성하는 방법을 보여줍니다.

주:

라우팅 컨텍스트 없이 작업을 생성하고, 문서화된 요청 구조를 따르십시오.옴니채널 콜백 - POST /api/sn_omni_callback/callback/create

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "create",
  "payload": {
  "type": "asap",
  "callbackDetails": {
    "appointment": "68cc0a5a9314521060320dd548373cbd",
    "description": "Customer reported issue with order #12345",
    "short_description": "Order issue",
    "reason_type": "product_issue",
    "expire_time": "2025-09-01 17:00",
    "messaging_channel": "web_channel_sys_id",
    "channel_to_callback": "genesys_channel_sys_id",
    "scheduled_start_time": "2025-09-01 1:00",
    "end_time": "2025-09-01 17:00",
    "user_document": "abel.tuter",
    "user_table": "sys_user"
},
  },
  "callbackContext": {
    "queue": "sample queue",
    "ivr_path": "sample ivr path"
  },
  "inboundId": "ServiceNowVoice",
  "isExternal": true,
  "phoneNumber": "+123454768",
  "externalCallbackId": "new-external-id",
  "interactionDetails": {
    "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z",
    "userId": "32423424",
    "callerPhoneNumber": "+14089178877"
  }
}

업데이트 작업(라우팅 사용)

이 예제 작업은 기존 콜백 기록을 라우팅 컨텍스트로 업데이트합니다. callbackNumber 이 값은 업데이트할 기록을 식별합니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "update",
  "payload": {
    "callbackDetails": {
      "appointment": "68cc0a5a9314521060320dd548373cbd",
      "description": "Customer reported issue with order #12345",
      "short_description": "Order issue",
      "reason_type": "product_issue",
      "expire_time": "2025-09-01 17:00",
      "messaging_channel": "web_channel_sys_id",
      "channel_to_callback": "genesys_channel_sys_id",
      "scheduled_start_time": "2025-09-01 1:00",
      "end_time": "2025-09-01 17:00",
      "user_document": "abel.tuter",
      "user_table": "sys_user"
    },
    "callbackContext": {
      "queue": "5 value changed via api",
      "ivr_path": "5 some-ivr-path changed via api"
    },
    "inboundId": "AmazonConnect",
    "phoneNumber": "+14089178877",
    "callbackId": "a16ead53fff0621088c6ffffffffffce"
  }
}

업데이트(라우팅 컨텍스트 없음)

다음 예제는 라우팅 컨텍스트 없이 콜백 기록을 업데이트하는 방법을 보여줍니다.

주:

라우팅 컨텍스트가 없는 업데이트 작업은 에 문서화된 요청 구조를 따릅니다.옴니채널 콜백 - PATCH /api/sn_omni_callback/callback/update

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "update",
  "payload": {
    "callbackDetails": {
      "appointment": "68cc0a5a9314521060320dd548373cbd",
      "description": "Customer reported issue with order #12345",
      "short_description": "Order issue",
      "reason_type": "product_issue",
      "expire_time": "2025-09-01 17:00",
      "messaging_channel": "web_channel_sys_id",
      "channel_to_callback": "genesys_channel_sys_id",
      "scheduled_start_time": "2025-09-01 1:00",
      "end_time": "2025-09-01 17:00",
      "user_document": "abel.tuter",
      "user_table": "sys_user"
    },
    "callbackContext": {
      "queue": "5 value changed via api",
      "ivr_path": "5 some-ivr-path changed via api"
    },
    "inboundId": "AmazonConnect",
    "phoneNumber": "+14089178877",
    "callbackId": "a16ead53fff0621088c6ffffffffffce"
  }
}

작업 취소

이 예시 작업은 라우팅 컨텍스트로 지정된 콜백 기록을 취소하고 콜백 [sys_cs_callback] 테이블의 이유 필드를 업데이트합니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
    "action": "cancel",
    "routingContext": {
        "sourceTable": "sn_csm_ec_engmnt_center_module",
        "sourceId": "a1b2c3d4e5f6a7b8",
        "userId": "beth.anglin"
    },
     "payload": {
        "callbackId": "CAL0001234"
    }
}

취소(라우팅 컨텍스트 없음)

다음 예제는 라우팅 컨텍스트 없이 콜백 기록을 취소하는 방법을 보여줍니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "cancel",
  "payload": {
    "callbackId": "cb-98765"
  }
}

작업 닫기(라우팅 사용)

이 예에서는 라우팅 컨텍스트로 콜백 기록을 닫고 콜백 [sys_cs_callback] 테이블의 이유 필드를 업데이트합니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
    "action": "close",
    "routingContext": {
        "sourceTable": "sn_csm_ec_engmnt_center_module",
        "sourceId": "a1b2c3d4e5f6a7b8",
        "userId": "beth.anglin"
    },
    "payload": {
        "callbackId": "CAL0001234"
    }
}

닫기(라우팅 컨텍스트 없음)

다음 예제는 라우팅 컨텍스트 없이 콜백 기록을 종결하는 방법을 보여줍니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/actions \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "action": "close",
  "payload": {
    "callbackId": "cb-98765"
  }
}

옴니채널 콜백 - POST /api/sn_omni_callback/callback/attempt

재시도를 포함하여 기존 콜백에 대한 상호작용을 시작합니다.

URL 형식

기본 URL: /api/sn_omni_callback/callback/attempt

지원되는 요청 매개변수

표 7. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오. 데이터 유형: 문자열

표 8. 쿼리 매개변수
이름	설명
안 함

표 9. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
callbackId	필수 콜백의 Sys_id 또는 external_id입니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열
상호작용 상세 정보	옵션입니다. 상호작용에 대한 상세 정보입니다. 상호작용 상세 정보가 대기 없이 에이전트에 직접 라우팅되도록 '빨리'(즉시) 콜백 유형을 위한 것입니다. 모든 상호작용 상세 정보는 의 음성 상호작용 자원 - POST /cs/voice-interactions페이로드에 전달됩니다. 데이터 유형: 객체 `"interactionDetails": { "callerPhoneNumber": "String", "clientSessionId": "String", "userId": "String" }`
interactionDetails.callerPhoneNumber	호출자의 콜백 전화 번호입니다. 이 번호는 콜이 끊어지는 경우 에이전트가 발신자에게 연락하는 데 사용하는 번호입니다. 데이터 유형: 문자열 형식: E.164 표준 준수 기본값: 없음
interactionDetails.clientSessionId	이 전화 통화를 추적하는 데 사용되는 외부 시스템의 기록 고유 식별자입니다. 이 정보는 두 시스템 간의 기록을 연결합니다. 데이터 유형: 문자열 형식: 일반적으로 외부 시스템에서 작성된 UUID 또는 고유한 세션 토큰 기본값: 없음
interactionDetails.userId	콜백할 사용자의 Sys_id입니다. 테이블: 사용자 [sys_user] 데이터 유형: 문자열

헤더

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

표 11. 응답 헤더
머리글	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

상태 코드

이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

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

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


이름	설명
오류	필요한 요청 ID 누락 등 콜백 생성 실패에 대한 상세 정보가 포함된 메시지입니다. 데이터 유형: 문자열 배열 `"errors": ["String", "String"]`
메시지	콜백 생성의 성공에 대한 세부 정보가 포함된 메시지입니다. 데이터 유형: 문자열 배열 `"messages": ["String", "String"]`
결과	요청의 결과입니다. 데이터 유형: 객체 `"result": { "status": "String", "response": {Object}, "errors": [Array], "messages": [Array] }`
결과.응답	콜백 요청의 콜백 및 상호작용 ID를 포함하는 객체입니다. 데이터 유형: 객체 `"response": { "callback_created": Boolean "callback_id": "String", "interaction_id": "String" }`
result.response.interaction_id	새로 생성된 상호작용의 Sys_id입니다. 테이블: 상호작용 [interaction] 데이터 유형: 문자열
결과.상태	요청의 성공 또는 실패 상태입니다. 유효한 값은 다음과 같습니다. 성공 실패 데이터 유형: 문자열

cURL 요청

다음 예제에서는 초기 상호 작용 및 후속 재시도 상호 작용에 대한 세부 정보와 함께 POST 시도 요청을 보여 줍니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/attempt' \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "callbackId": "<ID#>",
  "interactionDetails": {
    "clientSessionId": "<ID#>",
    "userId": "<ID#>",
    "callerPhoneNumber": "+112345678901"
  }
}

유효한 callback_Id 제공되고 콜백에 대한 새 상호작용이 성공적으로 만들어진 경우의 응답 본문입니다.

{
  "result": {
    "status": "success",
    "response": {
      "interaction_id": "<Interaction ID#>"
    }
  }
}

요청에 잘못된 callback_Id 제공된 경우의 응답 본문입니다.

{
  "result": {
    "status": "failure",
    "response": {
      "interactionId": null
    },
    "errors": [
      "Callback not found for callback ID: <ID#>"
    ]
  }
}

지정된 콜백에 대한 상호작용이 이미 존재하는 경우의 응답 본문(메시지는 기존 상호작용에 대한 상세 정보를 반환함):

{
  "result": {
    "status": "success",
    "response": {
      "interaction_id": "<Interaction ID#>"
    },
    "messages": [
      "Active Interaction <Interaction ID#> already exists for callback <ID#>"
    ]
  }
}

옴니채널 콜백 - POST /api/sn_omni_callback/callback/create

요청 본문에 입력한 상세 정보에 따라 즉시 또는 예약된 새 콜백 요청을 시작합니다. 즉각적인 콜백의 경우 이 API는 콜백과 상호작용을 모두 생성합니다. 예약된 콜백의 경우 약속 ID로 콜백을 생성합니다.

URL 형식

버전이 지정된 URL: /api/sn_omni_callback/v1/callback/create

기본 URL: /api/sn_omni_callback/callback/create

지원되는 요청 매개변수

표 13. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오. 데이터 유형: 문자열

표 14. 쿼리 매개변수
이름	설명
안 함

표 15. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
콜백컨텍스트	콜백 요청에 대한 컨텍스트 상세 정보를 포함하는 객체입니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context] 데이터 유형: 객체 `"callbackContext": { "customer_timezone": "String", "ivr_path": "String", "source_channel": "String", "queue": "String", "voicemail_duration": "String", "voicemail_recorded_at": "String", "voicemail_transcript": "String", "voicemail_url": "String" }`
callbackContext.customer_timezone	콜백을 요청한 고객의 시간대입니다. 시간대는 다음 형식으로 제공할 수 있습니다. `국가/도시` 예: `아메리카/Los_Angeles`. `국가/시간대` 예: `미국/태평양`. `시간대 약어입니다`. 예: `PST` 유효한 시간대의 전체 목록은 사용자 [sys_user] 테이블의 시간 대 필드를 참조하십시오. 시간대에 대한 자세한 내용은 다음 문서를 참조하십시오 Time zones. 데이터 유형: 문자열
callbackContext.ivr_path	고객이 실제 에이전트로 전송되기 전에 따르는 IVR(대화형 음성 응답) 경로입니다. 일반적으로 고객이 IVR 시스템에서 탐색한 큐 또는 메뉴 옵션 목록을 포함합니다. 이 문자열은 CCaaS(Contact Center as a Service)에 의해 전달됩니다. 예: `"ivr_path": "기술 지원 > 계정 관리"` 데이터 유형: 문자열
콜백컨텍스트.queue	큐의 번호 할당입니다. 데이터 유형: 문자열
callbackContext.source_channel	콜백의 소스입니다. 예를 들어 IVR, 웹 또는 VA를 사용할 수 있습니다. 데이터 유형: 문자열
callbackContext.voicemail_duration	음성 메일의 길이(시간, 분 또는 초)입니다. 필드: 음성 메일 기간 데이터 유형: 숫자
callbackContext.voicemail_recorded_at	음성 메일이 녹음된 타임 스탬프입니다. 필드: 음성 메일 녹음 시간 데이터 유형: 문자열
callbackContext.voicemail_transcript	음성 메일의 변환된 텍스트입니다. 필드: 음성 메일 기록 데이터 유형: 문자열
callbackContext.voicemail_url	음성 메일이 포함된 콜백 기록의 상대 링크입니다. 필드: 음성 메일 URL 데이터 유형: 문자열
콜백상세 정보	콜백 요청에 대한 상세 정보를 포함하는 객체입니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 객체 `"callbackDetails": { "appointment": "String", "channel_to_callback": "String", "description": "String", "end_time": "String", "expire_time": "String", "messaging_channel": "String", "reason_type": "String" "scheduled_start_time": "String", "short_description": "String", "user_document": "String", "user_table": "String" }`
callbackDetails.약속	약속의 Sys_id입니다. `예약된` 콜백 유형에만 적용 가능합니다. 테이블: 약속 예약 [sn_apptmnt_booking_appointment_booking] 데이터 유형: 문자열
callbackDetails.channel_to_callback	콜백을 라우팅할 대상 메시징 채널입니다. 테이블: 메시징 채널 [sys_cs_channel], 필드: sys_id 데이터 유형: 문자열
callbackDetails.description	필요한 경우 콜백 이유를 설명하는 전체 설명입니다. 데이터 유형: 문자열
callbackDetails.end_time	콜백 시도를 중지할 날짜 및 시간 값입니다. `예약된` 콜백 유형에만 적용 가능합니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
callbackDetails.expire_time	콜백 요청을 종결할 날짜 및 시간입니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
callbackDetails.messaging_channel	콜백의 소스입니다. 콜백 요청을 시작한 클라이언트 인터페이스(예: 웹 클라이언트, 모바일 앱 또는 포함된 메신저)를 식별합니다. 테이블: 메시징 채널 [sys_cs_channel], 필드: sys_id 데이터 유형: 문자열
callbackDetails.reason_type	콜백 요청의 이유입니다. 표준화된 이유로 콜백에 태그를 지정하여 라우팅, 분석 및 보고를 지원합니다. 유효한 값은 다음과 같습니다. `기타 문제` 구현에서 정의한 사용자 지정 값입니다. 예: `"청구 문의"`, `"기술 지원"` 테이블: 콜백 [sys_cs_callback], 필드: reason_type 데이터 유형: 문자열
callbackDetails.scheduled_start_time	콜백을 시작하는 날짜 및 시간 값입니다. `예약된` 콜백 유형에만 적용 가능합니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
callbackDetails.short_description	콜백 요청에 대한 자세한 설명을 제공합니다. 특정 고객 우려 사항, 컨텍스트 또는 에이전트의 메모를 포함할 수 있습니다. 데이터 유형: 문자열
callbackDetails.user_document	콜백을 요청한 사용자의 Sys_id입니다. 콜백을 요청하는 사용자를 식별하는 데 사용됩니다 callbackDetails.user_table . 테이블: 사용자 [sys_user], 필드: sys_id 데이터 유형: 문자열
callbackDetails.user_table	사용자 기록이 있는 테이블입니다. 콜백을 요청하는 사용자를 식별하는 데 사용됩니다 callbackDetails.user_document . 값은 항상 `sys_user`입니다. 데이터 유형: 문자열
외부 콜백 ID	외부 공급업체 벤더에서 생성된 콜백의 외부 식별자입니다. 데이터 유형: 문자열
inboundId	콜백과 연결된 인바운드 호출의 Sys_id입니다. 콜백 요청을 외부 공급업체 제공자 또는 CCaaS 플랫폼에서 시작될 수 있는 특정 인바운드 통화 기록에 연결하는 추적 기능을 제공합니다. 테이블: 콜백 [sys_cs_callback], 필드: provider_application_id 데이터 유형: 문자열
상호작용 상세 정보	옵션입니다. 상호작용에 대한 상세 정보입니다. 상호작용 상세 정보가 대기 없이 에이전트에 직접 라우팅되도록 '빨리'(즉시) 콜백 유형을 위한 것입니다. 모든 상호작용 상세 정보는 의 음성 상호작용 자원 - POST /cs/voice-interactions페이로드에 전달됩니다. 데이터 유형: 객체 `"interactionDetails": { "callerPhoneNumber": "String", "clientSessionId": "String", "userId": "String" }`
interactionDetails.callerPhoneNumber	호출자의 콜백 전화 번호입니다. 이 번호는 콜이 끊어지는 경우 에이전트가 발신자에게 연락하는 데 사용하는 번호입니다. 데이터 유형: 문자열 형식: E.164 표준 준수 기본값: 없음
interactionDetails.clientSessionId	이 전화 통화를 추적하는 데 사용되는 외부 시스템의 기록 고유 식별자입니다. 이 정보는 두 시스템 간의 기록을 연결합니다. 데이터 유형: 문자열 형식: 일반적으로 외부 시스템에서 작성된 UUID 또는 고유한 세션 토큰 기본값: 없음
interactionDetails.userId	콜백할 사용자의 Sys_id입니다. 테이블: 사용자 [sys_user] 데이터 유형: 문자열
isExternal	콜백이 외부인지 여부와 다른 외부 공급업체 벤더에서 요청되었는지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다. true: 외부 콜백입니다. false: 콜백이 외부가 아닙니다. 기본값: false
유형	필수 콜백 유형입니다. 유효한 값은 다음과 같습니다. `최대한 빨리`: 콜백 상호작용이 즉시 생성됩니다. `예약됨`: 콜백 상호작용이 생성되고 고객이 선택한 나중 시간으로 예약됩니다. 데이터 유형: 문자열

헤더

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

표 17. 응답 헤더
머리글	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

상태 코드

이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

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

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


이름	설명
결과	요청의 결과입니다. 데이터 유형: 객체 `"result": { "status": "String", "response": {Object}, "errors": [Array], "messages": [Array] }`
결과.오류	필요한 요청 ID 누락 등 콜백 생성 실패에 대한 상세 정보가 포함된 메시지입니다. 데이터 유형: 문자열 배열 `"errors": ["String", "String"]`
결과.메시지	콜백 생성의 성공에 대한 세부 정보가 포함된 메시지입니다. 데이터 유형: 문자열 배열 `"messages": ["String", "String"]`
결과.응답	콜백 요청의 콜백 및 상호작용 ID를 포함하는 객체입니다. 데이터 유형: 객체 `"response": { "callback_created": Boolean "callback_id": "String", "interaction_id": "String" }`
result.response.callback_created	새 콜백 요청이 생성 되었는지 여부를 나타내는 플래그입니다. 가능한 값: true: 콜백이 성공적으로 작성되었습니다. false: 콜백이 생성되지 않았습니다. 예를 들어, 지정된 callback_id와 함께 콜백이 이미 존재합니다. 데이터 유형: 부울
result.response.callback_id	새 콜백의 Sys_id입니다(해당하는 경우). 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열
result.response.interaction_id	새로 생성된 상호작용의 Sys_id입니다. 테이블: 상호작용 [interaction] 데이터 유형: 문자열
결과.상태	요청의 성공 또는 실패 상태입니다. 유효한 값은 다음과 같습니다. 성공 실패 데이터 유형: 문자열

cURL 요청

다음 예제에서는 에이전트가 요청 본문에 제공하는 세부 정보에 따라 간단한 콜백 요청을 만듭니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/create' \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "type": "asap",
  "callbackDetails": {
    "appointment": "68cc0a5a9314521060320dd548373cbd",
    "description": "Customer reported issue with order #12345",
    "short_description": "Order issue",
    "reason_type": "product_issue",
    "expire_time": "2025-09-01 17:00",
    "messaging_channel": "web_channel_sys_id",
    "channel_to_callback": "genesys_channel_sys_id",
    "scheduled_start_time": "2025-09-01 1:00",
    "end_time": "2025-09-01 17:00",
    "user_document": "abel.tuter",
    "user_table": "sys_user"
},
  },
  "callbackContext": {
    "queue": "sample queue",
    "ivr_path": "sample ivr path"
  },
  "inboundId": "ServiceNowVoice",
  "isExternal": true,
  "phoneNumber": "+123454768",
  "externalCallbackId": "new-external-id",
  "interactionDetails": {
    "clientSessionId": "f8453abb-a33d-45b7-bf01-52b7a821e99z",
    "userId": "32423424",
    "callerPhoneNumber": "+14089178877"
  }
}

응답 본문은 새로 생성된 콜백 요청에 대한 콜백 및 상호작용 ID와 함께 성공 응답을 반환합니다.

{
  "status": "success",
  "response": {
    "callback_id": "a16ead53fff0621088c6ffffffffffce",
    "interaction_id": "696e6d57fff0621088c6ffffffffff7d"
  }
}

상호작용 상세 정보가 제공되지 않은 경우의 응답 본문:

{
  "status": "success",
  "response": {
    "callback_created": true,
    "callback_id": "7df2059ffffc221088c6ffffffffff0c"
  }
}

콜백 ID가 이미 있지만 새 상호작용 상세 정보가 제공된 경우의 응답 본문:

{
  "result": {
    "status": "success",
    "response": {
      "interaction_id": "84054fff53786210011eddeeff7b12d6",
      "callback_id": "8b43c3fb53786210011eddeeff7b12a6",
      “callback_created”: false
    },
    "messages": [
      "Successfully updated the callback 8b43c3fb53786210011eddeeff7b12a6",
      "Successfully created the interaction 84054fff53786210011eddeeff7b12d6"
    ]
  }
}

콜백 ID가 이미 있지만 새 상호작용 상세 정보가 제공되지 않은 경우의 응답 본문:

{
  "result": {
    "status": "success",
    "response": {
      "callback_id": "8b43c3fb53786210011eddeeff7b12a6"
    },
    "messages": [
      "Successfully updated the callback 8b43c3fb53786210011eddeeff7b12a6"
    ]
  }
}

요청에 필수 필드가 누락된 경우의 응답 본문:

{
  "result": {
    "status": "failure",
    "response": {
      "callbackId": null
    },
    "errors": [
      "Parameter 'type' is required in request"
    ]
  }
}

옴니채널 콜백 - POST api/sn_omni_callback/callback/get

쿼리 매개변수를 기반으로 콜백 정보를 가져옵니다.

URL 형식

버전이 지정된 URL: /api/sn_omni_callback/v1/callback/get

기본 URL: /api/sn_omni_callback/callback/get

지원되는 요청 매개변수

표 19. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오. 데이터 유형: 문자열

표 20. 쿼리 매개변수
이름	설명
안 함

표 21. 요청 본문 매개변수 (XML 또는 JSON)
이름	설명
query매개변수	결과를 필터링할 쿼리 매개변수의 키-값 쌍을 포함하는 객체입니다. 데이터 유형: 객체 `"queryParameters": { "number": "String", "state": "String", "opened_by": "String", "sys_id", "String", "callback_type": "String", "external_callback_id": "String", "callback_number": "String" }`
queryParameters를 사용합니다.번호	조회할 콜백 참조 번호입니다. 예: `"CAL0010012"`. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열
queryParameters.state	콜백의 현재 상태를 나타내는 숫자입니다. 가능한 값: `1`: 오픈 `2`: 진행 중 `3`: 완료 종결 `4`: 포기 종결 `7`: 취소됨 데이터 유형: 숫자
queryParameters.opened_by	콜백을 요청하는 사용자의 사용자 ID입니다. 테이블: 사용자 [sys_user] 데이터 유형: 문자열
queryParameters.sys_id	콜백 기록의 Sys_id입니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열
queryParameters.callback_type	콜백 유형입니다. 유효한 값은 다음과 같습니다. `최대한 빨리`: 콜백 상호작용이 즉시 생성됩니다. `예약됨`: 콜백 상호작용이 생성되고 고객이 선택한 나중 시간으로 예약됩니다. 데이터 유형: 문자열
queryParameters.external_callback_id	외부 공급업체 시스템에서 생성된 콜백의 외부 식별자입니다. 데이터 유형: 문자열
queryParameters.callback_number	다시 콜할 호출자의 전화 번호입니다. 데이터 유형: 문자열
응답 매개변수	옵션입니다. 응답에서 반환할 필드를 지정합니다. 이를 생략하면 엔드포인트는 기본 필드를 반환합니다. 데이터 유형: 객체 `"responseParameters": { "callback": [Array], "context": [Array] }`
responseParameters.callback	옵션입니다. 콜백 기록에서 필드(예: `숫자`, `phone_number`)를 반환합니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 객체 `"callback": [String, String]` 유효한 값은 다음과 같습니다. `number`: 해당 콜백의 고유 참조 번호입니다(예: `"CAL0010012"`). `phone_number`: 발신자의 전화 번호입니다.
responseParameters.context	옵션입니다. 큐, 할당 또는 관련 메타데이터와 같은 콜백의 상황별 정보를 키:값 쌍의 형태로 반환합니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context] 데이터 유형: 문자열 배열 `"callbackContext": { "customer_timezone": "String", "ivr_path": "String", "source_channel": "String", "queue": "String", "voicemail_duration": "String", "voicemail_recorded_at": "String", "voicemail_transcript": "String", "voicemail_url": "String" }`
responseParameters.context.customer_timezone	콜백을 요청하는 사용자의 시간대입니다. 문자열
responseParameters.context.ivr_path	고객이 실제 에이전트로 전송되기 전에 따르는 IVR(대화형 음성 응답) 경로입니다. 일반적으로 고객이 IVR 시스템에서 탐색한 큐 또는 메뉴 옵션 목록을 포함합니다. 이 문자열은 CCaaS(연락처 센터 서비스형)에서 전달됩니다. 예: `"ivr_path": "기술 지원 > 계정 관리"` 데이터 유형: 문자열
responseParameters.context.source_channel	콜백의 소스입니다. 예를 들어 IVR, 웹 또는 VA를 사용할 수 있습니다. 문자열
responseParameters.context.queue	콜백이 할당된 큐의 이름 또는 ID입니다. 문자열
responseParameters.context.voicemail_duration	음성 메일의 길이(시간, 분 또는 초)입니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context], 필드: 음성 메일 기간 문자열
responseParameters.context.voicemail_recorded_at	음성 메일이 녹음된 타임 스탬프입니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context], 필드: 음성 메일 녹음 시간 데이터 유형: 문자열
responseParameters.context.voicemail_transcript	음성 메일의 변환된 텍스트입니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context], 필드: 음성 메일 기록 데이터 유형: 문자열
responseParameters.context.voicemail_url	음성 메일이 포함된 콜백 기록의 상대 링크입니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context], 필드: 음성 메일 URL 데이터 유형: 문자열

헤더

표 22. 요청 헤더
머리글	설명
없음

표 23. 응답 헤더
머리글	설명
안 함

상태 코드

이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

표 24. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.

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


이름	설명
결과	지정된 검색 기준과 일치하는 콜백 기록 또는 콜백 정보를 포함하는 객체입니다. 날짜 유형: 객체 `"result": { "response": {Object}, "status": "String" }`
결과.응답	콜백 정보입니다. 데이터 유형: 객체 `"response": { "callbacks": [Array], "count": "Number" }`
결과.응답.콜백	키:값 쌍의 형식으로 콜백 기록에 대한 상세 정보를 포함하는 객체입니다. 주: 요청에 지정되지 않은 경우 responseParameters 모든 기본 필드를 표시합니다. 데이터 유형: 문자열 배열 `"callbacks": [ { "number": "String", "state": "String", "first_name": "Virtual", "last_name": "Agent", "user_table": "sys_user", "opened_by": "Virtual Agent", "assigned_to": "" } ]`
result.response.callbacks.assigned_to	요청에 할당된 에이전트의 ID입니다. 데이터 유형: 문자열
result.response.callbacks.context	콜백 기록의 상황별 정보입니다. 요청 입력에 따라 달라집니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context] 데이터 유형: 문자열 배열 `"callbackContext": { "customer_timezone": "String", "ivr_path": "String", "source_channel": "String", "queue": "String", "voicemail_duration": "String", "voicemail_recorded_at": "String", "voicemail_transcript": "String", "voicemail_url": "String" }`
result.response.callbacks.context.customer_timezone	콜백을 요청하는 사용자의 시간대입니다. 문자열
result.response.callbacks.context.ivr_path	고객이 실제 에이전트로 전송되기 전에 따르는 IVR(대화형 음성 응답) 경로입니다. 일반적으로 고객이 IVR 시스템에서 탐색한 큐 또는 메뉴 옵션 목록을 포함합니다. 이 문자열은 CCaaS(Contact Center as a Service)에 의해 전달됩니다. 예: `"ivr_path": "기술 지원 > 계정 관리"` 데이터 유형: 문자열
result.response.callbacks.context.source_channel	콜백의 소스입니다. 예를 들어 IVR, 웹 또는 VA를 사용할 수 있습니다. 문자열
result.response.callbacks.context.queue	콜백이 할당된 큐의 이름 또는 ID입니다. 문자열
result.response.callbacks.context.voicemail_duration	음성 메일의 길이(시간, 분 또는 초)입니다. 문자열
result.response.callbacks.context.voicemail_recorded_at	음성 메일이 녹음된 타임 스탬프 입니다. 데이터 유형: 문자열
result.response.callbacks.context.voicemail_transcript	음성 메일의 변환된 텍스트입니다. 데이터 유형: 문자열
result.response.callbacks.context.voicemail_url	음성 메일이 포함된 콜백 기록의 상대 링크입니다. 데이터 유형: 문자열
result.response.callbacks.created_on	콜백이 작성되었을 때의 타임 스탬프입니다. 데이터 유형: 문자열
result.response.callbacks.first_name	콜백을 시작했거나 콜백과 연결된 사용자의 이름입니다. 데이터 유형: 문자열
result.response.callbacks.last_name	연결된 사용자의 성입니다. 로깅, 라우팅 및 표시를 위한 사용자의 전체 이름을 완성합니다. 데이터 유형: 문자열
result.response.callbacks.number	고유 콜백 참조 번호입니다. 예: `"CAL0010012"`. 데이터 유형: 문자열
result.response.callbacks.opened_by	콜백을 요청하는 사용자의 사용자 ID입니다. 테이블: 사용자 [sys_user] 데이터 유형: 문자열
result.response.callbacks.phone_number	호출자의 전화 번호입니다. 데이터 유형: 문자열
result.response.callbacks.status	콜백의 현재 상태입니다. 가능한 값: `1`: 오픈 `2`: 진행 중 `3`: 완료 종결 `4`: 포기 종결 `7`: 취소됨 데이터 유형: 문자열
result.response.callbacks.user_table	콜백 사용자 상세 정보를 조회할 때 참조할 테이블입니다. 예를 들면 sys_user입니다. 데이터 유형: 문자열
결과.응답.카운트	검색 기준에 따라 일치하는 기록 수입니다. 데이터 유형: 숫자
결과.상태	요청의 성공 또는 오류 상태입니다. 가능한 값: 오류: 데이터베이스 연결 오류, 서버 예외 또는 포착되지 않은 런타임 오류와 같은 내부 또는 예기치 않은 오류입니다. 실패: 작업을 완료할 수 없습니다. 예: 기록을 찾을 수 없음, 확인에 실패했거나 매개변수가 지원되지 않습니다. not_found: 쿼리된 엔터티가 없습니다. 권한 없음: 호출자에게 권한, 자격 증명 또는 액세스가 없습니다. invalid_request: 잘못된 형식의 매개변수, 잘못된 유형 또는 누락된 필수 필드의 경우. 시간 초과: 업스트림 시스템 또는 데이터베이스가 제시간에 반환되지 않았습니다. partial_success: 일부 기록이 성공적으로 처리되었거나 일부 기록이 실패했습니다. 데이터 유형: 문자열

cURL 요청

다음 POST 예시에서는 가상 에이전트("opened_by": "virtual.agent")가 특별히 연 콜백 기록을 쿼리하고 닫힌 상태(4)에 있으며, 큐 컨텍스트("context": "context": ) 내에서 콜백 기록의 참조 번호와 전화번호("callback": ["number", "callback_number"])만 반환하도록 API에 지시합니다. ["큐"]).

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/get' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u 'username':'password' \ 
  -d {
  "queryParameters": {
    "opened_by": "virtual.agent",
    "state": 4,
  },
  "responseParameters": {
    "callback": ["number", "callback_number"],
    "context": ["queue"]
  }
}

응답 본문.

{
  "result": {
    "status": "success",
    "response": {
      "callbacks": [
        {
          "number": "CAL0010036",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010037",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010001",
          "callback_number": "+918008509174",
          "context": {
            "queue": "queue"
          }
        },
        {
          "number": "CAL0010033",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010003",
          "callback_number": "+918008509174",
          "context": {
            "queue": "Soumya queue"
          }
        },
        {
          "number": "CAL0010035",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010038",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        },
        {
          "number": "CAL0010034",
          "callback_number": "+14089178878",
          "context": {
            "queue": "21 value changed via api"
          }
        }
      ],
      "count": 8
    }
  }
}

다음 예제에서는 일치하는 외부 ID new-external-2325를 기반으로 콜백 정보를 검색합니다. 호출이 요청에서 제공 responseParameters 되지 않기 때문에 응답은 전체 기본 기록을 반환합니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/get' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u 'username':'password' \ 
  -d {
  "queryParameters": {
    "external_callback_id": "new-external-2325"
  }
}

응답 본문:

{
  "result": {
    "status": "success",
    "response": {
      "callbacks": [
        {
          "number": "CAL0010038",
          "state": "Closed Abandoned",
          "first_name": "Virtual",
          "last_name": "Agent",
          "user_table": "sys_user",
          "opened_by": "Virtual Agent",
          "assigned_to": ""
        }
      ]
    }
  }
}

옴니채널 콜백 - PATCH /api/sn_omni_callback/callback/update

요청에 제공된 상세 정보에 따라 기존 콜백을 업데이트합니다.

업데이트하려는 요청 본문에 요청 매개변수만 제공합니다.

URL 형식

기본 URL: /api/sn_omni_callback/callback/update

지원되는 요청 매개변수

표 25. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오. 데이터 유형: 문자열

표 26. 쿼리 매개변수
이름	설명
안 함

표 27. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
콜백컨텍스트	콜백 요청에 대한 컨텍스트 상세 정보를 포함하는 객체입니다. 테이블: 콜백 컨텍스트 [sys_cs_callback_context] 데이터 유형: 객체 `"callbackContext": { "customer_timezone": "String", "ivr_path": "String", "source_channel": "String", "queue": "String", "voicemail_duration": "String", "voicemail_recorded_at": "String", "voicemail_transcript": "String", "voicemail_url": "String" }`
callbackContext.customer_timezone	콜백을 요청한 고객의 시간대입니다. 시간대는 다음 형식으로 제공할 수 있습니다. `국가/도시` 예: `아메리카/Los_Angeles`. `국가/시간대` 예: `미국/태평양`. `시간대 약어입니다`. 예: `PST` 유효한 시간대의 전체 목록은 사용자 [sys_user] 테이블의 시간 대 필드를 참조하십시오. 시간대에 대한 자세한 내용은 다음 문서를 참조하십시오 Time zones. 데이터 유형: 문자열
callbackContext.ivr_path	고객이 실제 에이전트로 전송되기 전에 따르는 IVR(대화형 음성 응답) 경로입니다. 일반적으로 고객이 IVR 시스템에서 탐색한 큐 또는 메뉴 옵션 목록을 포함합니다. 이 문자열은 CCaaS(Contact Center as a Service)에 의해 전달됩니다. 예: `"ivr_path": "기술 지원 > 계정 관리"` 데이터 유형: 문자열
콜백컨텍스트.queue	큐의 번호 할당입니다. 데이터 유형: 문자열
callbackContext.source_channel	콜백의 소스입니다. 예를 들어 IVR, 웹 또는 VA를 사용할 수 있습니다. 데이터 유형: 문자열
callbackContext.voicemail_duration	음성 메일의 길이(시간, 분 또는 초)입니다. 필드: 음성 메일 기간 데이터 유형: 숫자
callbackContext.voicemail_recorded_at	음성 메일이 녹음된 타임 스탬프입니다. 필드: 음성 메일 녹음 시간 데이터 유형: 문자열
callbackContext.voicemail_transcript	음성 메일의 변환된 텍스트입니다. 필드: 음성 메일 기록 데이터 유형: 문자열
callbackContext.voicemail_url	음성 메일이 포함된 콜백 기록의 상대 링크입니다. 필드: 음성 메일 URL 데이터 유형: 문자열
콜백상세 정보	콜백 요청에 대한 상세 정보를 포함하는 객체입니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 객체 `"callbackDetails": { "appointment": "String", "channel_to_callback": "String", "description": "String", "end_time": "String", "expire_time": "String", "messaging_channel": "String", "reason_type": "String" "scheduled_start_time": "String", "short_description": "String", "user_document": "String", "user_table": "String" }`
callbackDetails.약속	약속의 Sys_id입니다. `예약된` 콜백 유형에만 적용 가능합니다. 테이블: 약속 예약 [sn_apptmnt_booking_appointment_booking] 데이터 유형: 문자열
callbackDetails.channel_to_callback	콜백을 라우팅할 대상 메시징 채널입니다. 테이블: 메시징 채널 [sys_cs_channel], 필드: sys_id 데이터 유형: 문자열
callbackDetails.description	필요한 경우 콜백 이유를 설명하는 전체 설명입니다. 데이터 유형: 문자열
callbackDetails.end_time	콜백 시도를 중지할 날짜 및 시간 값입니다. `예약된` 콜백 유형에만 적용 가능합니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
callbackDetails.expire_time	콜백 요청을 종결할 날짜 및 시간입니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
callbackDetails.messaging_channel	콜백의 소스입니다. 콜백 요청을 시작한 클라이언트 인터페이스(예: 웹 클라이언트, 모바일 앱 또는 포함된 메신저)를 식별합니다. 테이블: 메시징 채널 [sys_cs_channel], 필드: sys_id 데이터 유형: 문자열
callbackDetails.reason_type	콜백 요청의 이유입니다. 표준화된 이유로 콜백에 태그를 지정하여 라우팅, 분석 및 보고를 지원합니다. 유효한 값은 다음과 같습니다. `기타 문제` 구현에서 정의한 사용자 지정 값입니다. 예: `"청구 문의"`, `"기술 지원"` 테이블: 콜백 [sys_cs_callback], 필드: reason_type 데이터 유형: 문자열
callbackDetails.scheduled_start_time	콜백을 시작하는 날짜 및 시간 값입니다. `예약된` 콜백 유형에만 적용 가능합니다. 형식: glide_date_time 값(예: `yyyy-MM-dd HH:mm:ss)` 데이터 유형: 문자열
callbackDetails.short_description	콜백 요청에 대한 자세한 설명을 제공합니다. 특정 고객 우려 사항, 컨텍스트 또는 에이전트의 메모를 포함할 수 있습니다. 데이터 유형: 문자열
callbackDetails.user_document	콜백을 요청한 사용자의 Sys_id입니다. 콜백을 요청하는 사용자를 식별하는 데 사용됩니다 callbackDetails.user_table . 테이블: 사용자 [sys_user], 필드: sys_id 데이터 유형: 문자열
callbackDetails.user_table	사용자 기록이 있는 테이블입니다. 콜백을 요청하는 사용자를 식별하는 데 사용됩니다 callbackDetails.user_document . 값은 항상 `sys_user`입니다. 데이터 유형: 문자열
callbackId	필수 콜백의 Sys_id 또는 external_id입니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열
inboundId	콜백과 연결된 인바운드 호출의 Sys_id입니다. 콜백 요청을 외부 공급업체 제공자 또는 CCaaS 플랫폼에서 시작될 수 있는 특정 인바운드 통화 기록에 연결하는 추적 기능을 제공합니다. 테이블: 콜백 [sys_cs_callback], 필드: provider_application_id 데이터 유형: 문자열
phoneNumber	호출자의 전화 번호입니다. 데이터 유형: 숫자 문자열 형식: E.164 표준 준수

헤더

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

표 29. 응답 헤더
머리글	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

상태 코드

이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

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

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


이름	설명
오류	필요한 요청 ID 누락 등 콜백 생성 실패에 대한 상세 정보가 포함된 메시지입니다. 데이터 유형: 문자열 배열 `"errors": ["String", "String"]`
메시지	콜백 생성의 성공에 대한 세부 정보가 포함된 메시지입니다. 데이터 유형: 문자열 배열 `"messages": ["String", "String"]`
결과	요청의 결과입니다. 데이터 유형: 객체 `"result": { "status": "String", "response": {Object}, "errors": [Array], "messages": [Array] }`
결과.응답	콜백 요청의 콜백 및 상호작용 ID를 포함하는 객체입니다. 데이터 유형: 객체 `"response": { "callback_created": Boolean "callback_id": "String", "interaction_id": "String" }`
result.response.callback_created	새 콜백 요청이 생성 되었는지 여부를 나타내는 플래그입니다. 가능한 값: true: 콜백이 성공적으로 작성되었습니다. false: 콜백이 생성되지 않았습니다. 예를 들어, 지정된 callback_id와 함께 콜백이 이미 존재합니다. 데이터 유형: 부울
result.response.callback_id	새 콜백의 Sys_id입니다(해당하는 경우). 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열
result.response.interaction_id	새로 생성된 상호작용의 Sys_id입니다. 테이블: 상호작용 [interaction] 데이터 유형: 문자열
결과.상태	요청의 성공 또는 실패 상태입니다. 유효한 값은 다음과 같습니다. 성공 실패 데이터 유형: 문자열

cURL 요청

다음 예제에서는 연결된 콜백 요청에서 일부 콜백 세부 정보를 업데이트합니다.

curl -X POST 'https://instance.servicenow.com/api/sn_omni_callback/callback/update' \ 
  -H 'Accept: application/json' \ 
  -H 'Content-Type: application/json' \ 
  -u 'username':'password' \ 
  -d ' {
  "callbackDetails": {
    "appointment": "68cc0a5a9314521060320dd548373cbd",
    "description": "Customer reported issue with order #12345",
    "short_description": "Order issue",
    "reason_type": "product_issue",
    "expire_time": "2025-09-01 17:00",
    "messaging_channel": "web_channel_sys_id",
    "channel_to_callback": "genesys_channel_sys_id",
    "scheduled_start_time": "2025-09-01 1:00",
    "end_time": "2025-09-01 17:00",
    "user_document": "abel.tuter",
    "user_table": "sys_user"
},
  "callbackContext": {
    "queue": "5 value changed via api",
    "ivr_path": "5 some-ivr-path changed via api"
  },
  "inboundId": "AmazonConnect",
  "phoneNumber": "+14089178877",
  "callbackId": "a16ead53fff0621088c6ffffffffffce"
}

유효한 기존 콜백 ID에 대한 성공적인 업데이트 응답입니다.

{
  "result": {
    "status": "success",
    "response": {
      "callback_id": "952f763b53786210011eddeeff7b1297"
    },
    "messages": [
      "Successfully updated the callback 952f763b53786210011eddeeff7b1297"
    ]
  }
}

요청에 잘못된 콜백 ID가 제공된 경우의 응답:


  "result": {
    "status": "failure",
    "response": {
      "callbackId": null
    },
    "errors": [
      "Callback not found for callback ID: 952f763b53786210011eddeef7b1297"
    ]
  }
}

요청에 콜백 ID가 누락된 경우의 응답:


  "result": {
    "status": "failure",
    "response": {
      "callbackId": null
    },
    "errors": [
      "Parameter 'callbackId' is required in request"
    ]
  }
}

옴니채널 콜백 - PATCH /api/sn_omni_callback/callback/close/{callback_number}

지정된 콜백 요청을 취소 합니다.

URL 형식

버전이 지정된 URL: /api/{api_version}/sn_omni_callback/callback/close/{callback_number}

기본 URL: /api/sn_omni_callback/callback/close/{callback_number}

지원되는 요청 매개변수

표 31. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오. 데이터 유형: 문자열
callback_number	취소할 콜백의 Sys_id 또는 external_id입니다. 테이블: 콜백 [sys_cs_callback] 데이터 유형: 문자열

표 32. 쿼리 매개변수
이름	설명
안 함

표 33. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
이유	옵션입니다. 지정된 콜백을 취소 하도록 지정합니다. 값은 항상 `취소됨입니다.` reason 통과되지 않으면 요청이 취소되지 않고 종결됩니다. 데이터 유형: 문자열

헤더

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

표 35. 응답 헤더
머리글	설명
안 함

상태 코드

이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

표 36. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.

응답 본문 매개변수


이름	설명
이유	콜백 요청을 업데이트하는 이유입니다. 값은 항상 `취소됨` 또는 `종결입니다.` 테이블: 콜백 [sys_cs_callback], 필드: 이유 데이터 유형: 문자열 `{ "reason": "Cancelled" }`

cURL 요청

다음 요청은 콜백 ID가 CAL0001234된 콜백 요청을 취소합니다.

curl -X POST "https://instance.servicenow.com/api/sn_omni_callback/callback/close/CAL0001234" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u "username:password" \
  -d '{
    "reason": "Cancelled"
  }'

응답 본문이 취소를 확인합니다.

{
"reason":"Cancelled"
}