Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Disposition codes API

처리 코드 API를 사용하면 통합에서 다음 작업을 할 수 있습니다.

인스턴스, 대기열 또는 세션의 처리 코드 목록을 가져옵니다.
이전에 완료된 통화 또는 채팅 세션의 처리 코드 또는 메모 (또는 둘 다)를 업데이트합니다.

인증 및 기본 URL

이 문서의 모든 엔드포인트는 API 사용자 토큰 (베어러 토큰)을 사용하는 표준 API 토큰 인증을 사용합니다.

기본 URL: https://SUBDOMAIN.REGION_CODE.ccaiplatform.com

처리 코드 목록 가져오기

사용 가능한 처리 코드를 가져옵니다. 인스턴스, 대기열, 세션 수준에서 쿼리할 수 있습니다.

인스턴스별

모든 다단계 처리 코드를 포함하여 인스턴스의 전체 처리 코드 트리를 반환합니다.

요청 예시

다음 요청은 처리 코드의 전체 목록을 가져옵니다.

GET /api/v1/disposition_codes
Authorization: Bearer {token}
Content-Type: application/json

응답 예시

다음 응답 예시는 처리 코드의 전체 목록을 보여줍니다.

{
  "disposition_codes": [
    {
      "id": 1,
      "name": "Issue Resolved",
      "full_path": "/Support/Issue Resolved",
      "children": []
    },
    {
      "id": 2,
      "name": "Escalated",
      "full_path": "/Support/Escalated",
      "children": [
        {
          "id": 3,
          "name": "Tier 2",
          "full_path": "/Support/Escalated/Tier 2",
          "children": []
        }
      ]
    }
  ]
}

큐별

대기열에 할당된 처리 코드를 반환합니다. 대기열별 목록이 구성되지 않은 경우 전역 (인스턴스 수준) 목록이 반환됩니다.

요청 예시

다음 요청은 대기열의 처리 코드를 가져옵니다.

GET /api/v1/disposition_codes?queue_id=QUEUE_ID
Authorization: Bearer TOKEN
Content-Type: application/json

쿼리 매개변수

매개변수	유형	필수	설명
`queue_id`	정수	예	처리 코드를 가져올 대기열의 ID입니다.

세션별

세션이 마지막으로 라우팅된 대기열을 기반으로 지정된 세션 ID에 사용할 수 있는 처리 코드를 반환합니다.

요청 예시

다음 요청은 세션의 처리 코드를 가져옵니다.

GET /api/v1/disposition_codes?session_id=SESSION_ID
Authorization: Bearer TOKEN
Content-Type: application/json

쿼리 매개변수

매개변수	유형	필수	설명
`session_id`	정수	예	세션 ID입니다.

처리 코드 및 메모 업데이트

이전에 완료된 통화 또는 채팅 세션의 업데이트된 처리 코드 또는 메모 (또는 둘 다)를 제출합니다. 이렇게 하면 새 처리 레코드와 CRM 메모가 생성됩니다. 원래 CRM 레코드는 수정되지 않습니다.

요청 예시

다음 요청은 세션의 처리 코드 또는 메모를 업데이트합니다.

POST /api/v1/sessions/SESSION_ID/disposition
Authorization: Bearer TOKEN
Content-Type: application/json

경로 매개변수

매개변수	유형	필수	설명
`session_id`	정수	예	업데이트할 통화 또는 채팅의 세션 ID입니다.

요청 본문 예시

다음 예시는 요청 본문을 보여줍니다.

{
  "disposition_code": {
    "id": 5,
    "full_path": "/Support/Verification/Pending Documents"
  },
  "notes": "Customer must upload documents via portal."
}

요청 본문 매개변수

매개변수	유형	필수	설명
`disposition_code`	객체	조건부	업데이트된 처리 코드입니다. `disposition_code` 또는 `notes` 중 하나 이상이 있어야 합니다.
`disposition_code.id`	정수	예 (`disposition_code`가 지정된 경우)	처리 코드 ID입니다.
`disposition_code.full_path`	문자열	예 (`disposition_code`가 지정된 경우)	처리 코드의 전체 계층적 경로입니다(예: `/Support/Verification/Pending Documents`). 세션의 처리 트리에 대한 유효성 검사에 사용됩니다.
`notes`	문자열	아니요	업데이트된 상담사 메모입니다. 메모 동작 표를 참고하세요.

메모 동작

값	행동
텍스트와 함께 표시 (예: `"notes": "Updated notes"`)	기존 메모를 새 텍스트로 바꿉니다.
빈 문자열로 표시 ("notes": "")	기존 메모를 명시적으로 지웁니다. 세션 메타데이터 파일에 더 이상 메모가 포함되지 않습니다. CRM 기록은 이전 레코드를 보관합니다.
생략됨 (요청에 필드가 없음)	기존 부가 정보를 변경하지 않습니다.

전화 연락 금지 (DNC) 처리

'전화 연락 금지' 처리를 제출하려면 disposition_code.id: -1을 사용하세요. 이는 인스턴스에 전화 연락 금지 기능이 사용 설정되어 있고 DNC 처리가 구성된 경우에만 허용됩니다. 그렇지 않으면 API는 422 Unprocessable Entity라는 메시지와 함께 '이 테넌트에 전화 연락 금지 처리가 사용 설정되지 않았습니다.'를 반환합니다.

상담사 기여 분석

API는 상담사 ID를 전달하지 않습니다. 시스템은 우선순위에 따라 처리를 다음에 기여 분석합니다.

이 세션의 처리를 원래 제출한 상담사입니다.
원래 처리가 없는 경우 통화 또는 채팅에 참여한 가장 최근의 상담사입니다.

둘 다 존재하지 않으면 API는 422 Unprocessable Entity를 반환합니다.

유효성 검사

다음 목록은 유효성 검사 규칙을 설명합니다.

세션의 통화 또는 채팅이 종료되어야 합니다. 활성 세션에서 처리를 업데이트하려고 하면 422 Unprocessable Entity가 반환됩니다.
disposition_code.id 및 disposition_code.full_path 매개변수는 세션이 마지막으로 라우팅된 대기열을 기반으로 세션의 처리 트리에 대해 유효성이 검사됩니다.
allow_disposition_edit 관리자 설정은 UI 전용 컨트롤입니다. 공개 API는 이 설정과 관계없이 항상 처리 데이터를 업데이트할 수 있습니다.

응답 예시

다음 예시는 성공적인 요청에 대한 응답을 보여줍니다.

{
  "session_id": 12345,
  "disposition": {
    "id": 5,
    "name": "Verification Pending",
    "full_path": "/Support/Verification/Pending Documents",
    "notes": "Customer must upload documents via portal.",
    "submitted_at": "2026-03-13T10:15:01Z"
  }
}

참고: name 필드는 지정된 id 및 full_path 값을 기반으로 처리 트리에서 서버에 의해 확인됩니다. 편의를 위해 응답으로 반환됩니다.

세션 메타데이터

이 API를 사용하여 처리가 업데이트되면 다음이 발생합니다.

외부 스토리지: 세션 메타데이터 파일이 재생성되고 기존 메타데이터 파일을 덮어씁니다.
CRM: 감사 추적을 유지하면서 새 메모가 생성됩니다.

오류 처리

이 섹션에서는 오류 처리에 대해 설명합니다.

일반적인 상태 코드

상태	조건	메시지 예
`400 Bad Request`	필수 필드 (`disposition_code` 및 `notes`가 모두 없음)가 누락되었거나 형식이 잘못되었습니다.	'처리 코드 또는 메모 중 하나 이상이 있어야 합니다.'
`401 Unauthorized`	API 토큰이 잘못되었거나 누락되었습니다.	'승인되지 않음'
`403 Forbidden`	API 사용자에게 지정된 세션 또는 테넌트에 대한 액세스 권한이 없습니다.	'액세스 권한 없음'
`404 Not Found`	세션을 찾을 수 없거나 존재하지 않습니다.	'세션을 찾을 수 없습니다.'
`422 Unprocessable Entity`	다양한 유효성 검사 실패. 422 처리할 수 없는 항목 시나리오 표를 참고하세요.	422 처리할 수 없는 항목 시나리오 표를 참고하세요.

422 처리할 수 없는 항목 시나리오

시나리오	오류 메시지
통화 또는 채팅 세션이 아직 활성 상태임	'세션이 종료되지 않았습니다. 처리는 완료된 세션에 대해서만 업데이트할 수 있습니다.'
세션의 트리에서 처리 코드 ID를 찾을 수 없음	'이 세션의 대기열에 처리 코드가 잘못되었습니다.'
DNC 처리가 제출되었지만 기능이 사용 설정되지 않음	'이 테넌트에 전화 연락 금지 처리가 사용 설정되지 않았습니다.'
기여 분석을 위해 확인할 수 있는 상담사 참여자가 없음	'처리 기여 분석을 위한 상담사를 확인할 수 없습니다.'

응답 예시

다음 예시는 오류 응답을 보여줍니다.

{
  "error": {
    "code": "session_not_ended",
    "message": "Session has not ended. Disposition can only be updated for completed sessions.",
    "details": {
      "session_id": 12345
    }
  }
}

일반적인 통합 흐름

일반적인 통합 흐름은 다음과 같습니다.

관련 대기열 또는 세션의 처리 코드를 가져옵니다.
- GET /api/v1/disposition_codes?session_id=SESSION_ID
선택을 위해 처리 트리를 사용자 또는 자동화된 시스템에 표시합니다.
업데이트된 처리를 제출합니다.
- POST /api/v1/sessions/SESSION_ID/disposition
- id 및 full_path가 포함된 선택된 disposition_code와 메모를 포함합니다.
응답을 처리합니다.
- 200 OK: 처리가 업데이트되었습니다. CRM 레코드가 자동으로 업데이트됩니다.
- 오류 발생 시: 오류 메시지를 표시하고 적절하게 재시도하거나 에스컬레이션합니다.

CRM 동작

이 API를 사용하여 처리가 제출되면 다음이 발생합니다.

Salesforce, ServiceNow, Zendesk, Dynamics 또는 HubSpot과 같은 연결된 CRM에 새 CRM 메모가 생성됩니다. 원래 메모는 수정되지 않습니다.
외부 스토리지의 경우 세션 메타데이터 파일이 업데이트된 처리 데이터로 덮어쓰입니다.

제한사항

HubSpot 통화 참여에는 각 처리 업데이트에서 덮어쓰이는 (추가되지 않음) 스칼라 hs_call_disposition 속성이 포함됩니다. 전체 기록은 HubSpot 메모에 보관되지만 참여 속성은 가장 최근의 처리 코드만 반영합니다.

Disposition codes API 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

인증 및 기본 URL

처리 코드 목록 가져오기

인스턴스별

큐별

세션별

처리 코드 및 메모 업데이트

메모 동작

전화 연락 금지 (DNC) 처리

상담사 기여 분석

유효성 검사

세션 메타데이터

오류 처리

일반적인 상태 코드

422 처리할 수 없는 항목 시나리오

일반적인 통합 흐름

CRM 동작

제한사항

Disposition codes API