Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

맞춤 CRM의 오류 처리, 재시도, 통화 순서 (일반 API)

이 문서에서는 CRM 엔드포인트가 HTTP 200 "Success." 이외의 응답을 반환할 때 CCAI Platform의 커스텀 CRM(일반 API) 기능의 동작을 설명합니다. API 계정 및 API 레코드 엔드포인트를 구성하는 통합자를 위한 동작 참조로 사용됩니다.

실행 순서 및 관계 개요

상호작용이 커스텀 CRM 통합을 트리거하면 플랫폼은 다음 순서로 엔드포인트를 호출합니다.

계정 수준 작업 (API 계정) - 연락처

예:
- 연락처를 찾습니다.
- 연락처를 만듭니다.
- 연락처를 업데이트합니다.
레코드 수준 작업 (API 레코드) - 티켓 또는 케이스

예:
- 티켓을 찾습니다.
- 티켓을 만듭니다.
- 티켓을 업데이트합니다.
세션 후 작업 (구성된 경우)

예:
- 댓글이나 메모를 추가합니다.
- 첨부파일 또는 스크립트를 업로드합니다.
- 마무리 업데이트를 적용합니다.

이전 단계에서는 일반적으로 이후 단계에서 사용할 수 있는 ID를 생성합니다. 예를 들어 contact_id는 엔드포인트 페이로드 템플릿에 포함된 경우 티켓 생성에 전달될 수 있으며, 일반적인 일반 API 설정에서 세션 후 작업에는 ticket_id가 필요합니다. 모든 엔드포인트가 ID를 추출하도록 구성되지는 않습니다. 중요한 차이점: ID 추출 엔드포인트의 2xx + 누락된 ID를 참조하세요.

중요한 차이점: `2xx` + ID 추출 엔드포인트에 ID 누락

모든 커스텀 CRM 엔드포인트가 수신한 응답에서 ID를 추출하는 것은 아닙니다. 이 동작은 response_data_location 및 (엔드포인트 생성의 경우) custom_id_location로 구성된 엔드포인트에만 적용됩니다. 일반적으로 조회 엔드포인트(기존 레코드의 ID 추출) 및 엔드포인트 생성 (새로 생성된 레코드의 ID 추출)입니다. 댓글, 첨부파일, 업데이트와 같은 엔드포인트는 응답에서 ID를 추출하지 않습니다.

ID 추출 엔드포인트에서 ID 누락의 영향

조회 엔드포인트의 경우 일치하는 레코드가 없는 200 OK 응답 (따라서 추출 가능한 ID가 없음)은 일반적인 '찾을 수 없음' 동작입니다. 인스턴스에 skip_account_creation 또는 skip_record_creation가 사용 설정된 경우 플랫폼은 생성을 시도하는 대신 null contact_id 또는 ticket_id를 사용하여 의도적으로 다운스트림을 진행합니다. 이는 해당 구성에서 예상되는 동작이며 잘못된 구성이 아닙니다.
만들기 엔드포인트의 경우: 구성된 위치에 새로 생성된 ID가 포함되지 않은 200 OK 응답은 구성 또는 응답 계약 문제입니다. HTTP 요청이 성공했으므로 재시도가 트리거되지 않지만 다운스트림 단계는 누락된 데이터로 진행될 수 있습니다.
두 경우 모두 실패 (실패인 경우)는 엔드포인트 오류가 아닌 누락된 데이터로 표시되므로 디버깅 중에 혼동을 일으킬 수 있습니다.

통합자 가이드

만들기 작업의 경우 2xx만 반환하는 것이 아니라 구성된 위치에서 예상 ID를 반환하는 것을 성공 계약의 일부로 만듭니다. 누락된 ID는 조사할 가치가 있는 구성 또는 응답 계약 문제로 취급합니다.
조회 작업의 경우 일치하는 항목이 없는 200 OK를 반환하는 것이 허용됩니다. 인스턴스가 의도적으로 '생성 없이 조회' 패턴(예: skip_account_creation = true)을 사용하는 경우 다운스트림 엔드포인트가 누락된 ID를 원활하게 처리하는 방법을 알 수 있도록 해당 결정을 문서화합니다.
테스트에서 다음을 확인합니다.
- 엔드포인트 생성의 경우 ID는 응답에 안정적으로 존재하며 커스텀 CRM에 구성된 정확한 위치에 있습니다.
- 조회 엔드포인트의 경우 플랫폼의 다운스트림 동작이 인스턴스의 건너뛰기 플래그 구성과 일치합니다.

오류 처리: 개요

엔드포인트가 성공이 아닌 응답(2xx 아님)을 반환하거나 응답하지 않는 경우:

플랫폼에서 요청을 재시도할 수 있습니다.
- 일부 상태의 경우 즉시 한 번
- 재시도할 수 있는 실패의 경우 더 긴 기간 동안
플랫폼이 업스트림 단계를 계속 재시도하는 동안 다운스트림 단계가 지연될 수 있습니다.
일부 실패는 재시도할 수 없는 것으로 처리됩니다 (예: 구성 또는 검증 실패).

자세한 재시도 규칙은 재시도 및 백오프 동작에 설명되어 있습니다. 실패와 다운스트림 호출 간의 관계는 연쇄 및 종속 항목 규칙에 설명되어 있습니다.

연쇄 및 종속 항목 규칙

커스텀 CRM 동작은 인스턴스의 CRM 구성, 특히 CRM 계정 및 레코드 생성 건너뛰기에 설명된 설정에 따라 제어됩니다. 이 문서에서는 다음 JSON 구성 예시에 표시된 대로 백엔드 구성 이름 (skip_account_creation, skip_account_lookup, skip_record_creation)으로 이러한 설정을 참조합니다.

이러한 설정 내에서 플랫폼은 항상 '하드 중지'하는 대신 가능할 때 체인을 계속하는 방향으로 편향됩니다. 예를 들어 조회에 실패하고 계정 생성이 사용 설정된 경우 익명 연락처를 만듭니다.

계정 실패가 레코드 작업에 미치는 영향

계정 단계에서 연락처가 생성되지 않더라도 기록 단계 (티켓/케이스)가 실행될 수 있지만 정확한 동작은 인스턴스 구성에 따라 다릅니다.

구성에 따라 플랫폼은 다음을 수행할 수 있습니다.

익명 연락처를 대체 연락처로 만들고 티켓 생성을 계속 진행합니다.
계정 조회 또는 계정 생성이 건너뛰도록 구성된 경우 contact_id 없이 기록 단계로 진행합니다.

엔드포인트에 미치는 영향

티켓 생성 시 contact_id가 누락되면 일반적으로 계정 조회 또는 계정 생성이 사용 중지된 인스턴스 구성을 나타냅니다.
인스턴스에 계정이 필요한 경우 연락처 없이 티켓을 자동으로 삽입하는 대신 contact_id 누락을 조사할 가치가 있는 신호로 처리합니다.
구성이 의도적으로 연락처 없이 티켓 생성을 허용하는 경우 티켓 엔드포인트가 해당 케이스를 명시적이고 예측 가능하게 처리하는지 확인하세요.

녹화 실패가 세션 후 작업에 미치는 영향

티켓 조회가 구성된 일반 API 설정의 경우 플랫폼은 ticket_id가 있을 때까지 세션 후 호출(예: call_finished, chat_finished, email_finished, save_call_recording, save_chat_history, update_ticket, done_ticket)을 전달하지 않습니다.

ticket_id 없이 세션 후 엔드포인트가 호출되면 일반적으로 다음 조건 중 하나를 나타냅니다.

인스턴스 구성에서 티켓 조회가 사용 중지되어 있으며, 이는 일반적인 API 설정에서는 흔하지 않습니다.
페이로드 템플릿에서 ticket_id 변수가 생략되었으며, 이는 조사할 가치가 있는 구성 문제입니다.

엔드포인트에 미치는 영향

세션 후 호출에서 ticket_id가 누락된 경우, 이를 조사할 가치가 있는 구성 신호로 취급해야 하며, 조용히 넘어갈 수 있는 예상된 동작으로 간주해서는 안 됩니다.
구성에 티켓 조회가 의도적으로 필요하지 않은 경우 누락된 ticket_id를 원활하게 처리하도록 세션 후 엔드포인트를 구성합니다. 예를 들어 문제를 로깅하고 작업을 실행하지 않거나, 비정상 종료하는 대신 명확하고 잘 구조화된 오류 메시지를 반환합니다.

재시도 및 백오프 동작

재시도는 다음 세 가지 레이어에서 발생합니다.

HTTP 수준 즉시 재시도 (빠른 두 번째 시도)
어댑터 수준 재시도 (네트워크 오류 및 특정 일시적인 응답에 대한 빠른 복구)
명령어 수준 재시도 (며칠에 걸친 롱테일 재시도)

HTTP 수준 즉시 재시도 (빠른 재시도)

특정 일시적인 상태의 경우 플랫폼은 최대 2회 (초기 시도 1회 + 즉시 재시도 1회) 시도합니다. 이는 일반적으로 다음 오류 상태에 적용됩니다.

408, 413, 429, 500, 502, 503, 504, 521, 522, 524

참고: 400, 401, 403, 404와 같은 상태는 이 즉각적인 HTTP 레이어에서 재시도되지 않습니다.

어댑터 수준 재시도 (빠른 네트워크 복구)

HTTP 호출과 명령어 수준 일정 간에 CRM 어댑터 (command_runner.js)의 중간 재시도 레이어는 HTTP 응답을 전혀 생성하지 않거나 특정 일시적인 메시지와 일치하는 실패를 처리합니다.

즉시 다시 큐에 추가: TCP/소켓 수준 오류로 인해 트리거됨 - ECONNRESET, ENOTFOUND, ESOCKETTIMEDOUT, ETIMEDOUT, ECONNREFUSED, EHOSTUNREACH, EPIPE, EAI_AGAIN HTTP 응답을 수신하기 전에 발생하는 네트워크 오류입니다.
30초 지연 재시도: 오류 메시지가 "Too Early"(HTTP 425), "Service Unavailable" 또는 "Unordered Collection"인 경우 트리거됩니다.
이 레이어에서 재시도할 수 없음: 다른 모든 항목은 명령어 수준 재시도 일정 (레이어 3)으로 넘어갑니다.

통합 담당자에게 중요한 이유

이러한 오류는 플랫폼이 엔드포인트에 대한 TCP 연결을 설정하거나 유지할 수 없을 때 발생합니다. 즉, 내부 인프라뿐만 아니라 서버 (서버 다운, 연결 거부, 요청 중간에 연결 끊김)에 문제가 있음을 나타내는 경우가 많습니다. 실제 효과는 일부 네트워크 장애가 7일 명령 수준 일정보다 훨씬 빠르게, 종종 몇 초 이내에 복구된다는 것입니다.

명령어 수준 재시도 (약 7일, 14회 시도)

작업이 실패하고 재시도할 수 있는 경우 플랫폼은 다음 일정을 사용하여 약 7일 동안 최대 14회까지 재시도할 수 있습니다.

  10s → 1m → 5m → 30m → 1h → 6h → 6h → 12h → 1d → 1d → 1d → 1d → 1d → 1d

이 롱테일 재시도 동작은 다음에 적용될 수 있습니다.

계정 운영
레코드 작업
세션 후 작업

재시도할 수 없는 실패

일부 실패는 재시도할 수 없는 것으로 처리됩니다. 예를 들면 다음과 같습니다.

구성 또는 검증 실패 (예: 필수 엔드포인트가 구성되지 않았거나 잘못 구성됨)
플랫폼에서 감지한 특정 내부 오류 카테고리입니다.

실패가 영구적인 것으로 처리되도록 해야 하는 경우 (재시도 없음) 지원팀 또는 구현팀에 문의하여 특정 설정에서 재시도할 수 없는 실패를 나타내는 올바른 방법을 확인하세요.

시간 제한 및 네트워크 오류

플랫폼은 두 가지 경로를 처리합니다.

애플리케이션 수준 제한 시간: 구성된 HTTP 제한 시간을 초과하면(요청이 전송되었지만 응답이 수신되지 않음) 플랫폼에서 명령어 수준 (레이어 3)에서 재시도할 수 있는 내부 오류가 발생합니다. 즉, 요청은 표준 백오프 일정 (최대 14회 재시도, 약 7일)을 따릅니다.
TCP/소켓 수준 오류: HTTP 응답이 수신되기 전에 네트워크 수준에서 연결이 실패하면 (예: ETIMEDOUT, ESOCKETTIMEDOUT, ECONNREFUSED) 어댑터 레이어 (레이어 2)가 이를 포착하고 즉시 명령어를 다시 큐에 추가합니다. 이러한 실패로부터의 복구는 일반적으로 훨씬 빠르며, 7일 일정을 따르지 않고 몇 초 이내에 복구되는 경우가 많습니다.

구분이 중요한 이유

애플리케이션 제한 시간 (서버가 연결을 수락했지만 제때 응답하지 않음)은 더 느리게 재시도합니다.
네트워크 수준 오류 (서버에 전혀 연결할 수 없음)는 훨씬 더 빠르게 재시도합니다.
두 경우 모두 요청이 부분적으로 처리되었을 수 있으므로 엔드포인트는 멱등성이어야 합니다. 복원력이 우수한 엔드포인트 빌드 (멱등성 및 설계 도움말)를 참조하세요.

상태 코드 및 제한 시간 동작 매트릭스 (예시 포함)

다음 표와 예시에서는 CCAI Platform이 다양한 HTTP 상태 코드, 제한 시간, 네트워크 오류를 처리하는 방법을 설명합니다.

결과 요약 표

다음 표의 ID 관련 행은 조회 또는 만들기 엔드포인트와 같이 응답에서 ID를 추출하도록 구성된 엔드포인트에만 적용됩니다. 대부분의 다른 엔드포인트는 응답 ID 추출을 수행하지 않습니다.

결과	예시	즉시 HTTP 재시도?	롱테일 재시도 (~7일)?	하방 영향
ID 추출 엔드포인트의 성공	`2xx` + 구성된 응답 위치에 있는 예상 ID	없음	없음	다운스트림은 추출된 ID로 진행됩니다.
일치하는 항목이 없는 조회	`2xx`(으)로 구성되었지만 구성된 위치에서 레코드를 찾을 수 없습니다.	없음	없음	일반적인 '찾을 수 없음' 동작입니다. `skip_account_creation` 또는 `skip_record_creation`가 사용 설정된 경우 다운스트림은 의도적으로 null ID로 진행됩니다.
ID 없이 반환 `2xx` 만들기	생성 엔드포인트에서 `2xx`을(를) 수신했지만 구성된 위치에 새 레코드의 ID가 누락되었습니다.	없음	없음	다운스트림은 누락된 데이터로 진행될 수 있습니다. 구성 또는 응답 계약 문제로 처리합니다.
ID를 추출하지 않는 엔드포인트에서 성공	ID를 추출하지 않는 메모, 업데이트, 첨부파일 작업과 같은 엔드포인트의 `2xx`	없음	없음	명령어 체인 및 인스턴스 구성에 따라 다운스트림이 진행됩니다.
일시적인 오류	`408`, `413`, `429`, `500`, `502`, `503`, `504`, `521`, `522`, `524`	예 (총 2회 시도)	자주 있음	재시도가 발생하는 동안 다운스트림 단계가 지연될 수 있습니다.
기타 오류	`400`, `401`, `403`, `404`, 기타 `4xx`/`5xx`.	없음	자주 있음	재시도가 발생하는 동안 다운스트림 단계가 지연될 수 있습니다.
구성/검증 실패	잘못된 구성, 누락된 엔드포인트가 있습니다.	해당 사항 없음	없음	구성에 따라 체인이 중지되거나 부분적으로 완료될 수 있습니다.
네트워크 수준 오류 (TCP/소켓)	`ECONNRESET`, `ENOTFOUND`, `ESOCKETTIMEDOUT`, `ETIMEDOUT`, `ECONNREFUSED`, `EHOSTUNREACH`, `EPIPE`, `EAI_AGAIN`	해당 사항 없음	아니요 (어댑터 레이어 2에서 처리됨)	어댑터가 즉시 다시 큐에 추가되며 복구는 일반적으로 빠릅니다 (초 단위). 다운스트림 단계가 잠시 지연될 수 있습니다.
애플리케이션 수준 제한 시간	`HTTP timeout exceeded` (수신된 응답 없음)	해당 사항 없음	종종 있음 (계층 3)	명령어 수준 재시도가 발생하는 동안 다운스트림 단계가 지연될 수 있습니다.

최소한의 일반 API 구성이 포함된 작업 예시

체인에서 실행하는 세 가지 엔드포인트(연락처 찾기 또는 만들기, 티켓 찾기 또는 만들기, 세션 후 댓글)가 있는 기준 커스텀 CRM 일반 API 설정 이 내용을 시작점으로 삼아 CRM 세부정보에 맞게 조정하세요.

인스턴스 수준 설정

{
  "lookup_method": "genericApi",
  "auth_method": "basic",
  "basic_auth_username": "ccai-integration",
  "basic_auth_password": "<secret>",
  "api_request_timeout": 10,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}",
  "contact_lookup_url": "https://crm.example.com/api/contacts/{ACCOUNT_ID}",
  "skip_account_lookup": false,
  "skip_account_creation": false,
  "skip_record_creation": false
}

응답 형태

CRM의 응답 형태는 고객별로 다릅니다. response_data_location은 파싱된 응답 본문 내의 관련 객체에 도달하는 lodash 스타일 경로입니다. 최상위 data 필드에 응답을 래핑할 필요는 없습니다. 다음 예시에서는 기본적으로 현실적인 플랫 형태를 보여줍니다.

예를 들어 data.contact 아래에 리소스를 중첩하는 CRM은 response_data_location: "data.contact" 및 { "contact": { "id": "c_99812" } }의 응답 본문을 설정합니다. 나머지 구성은 변경되지 않습니다.

엔드포인트 1 - `contact_find_endpoint`

전화번호 또는 이메일로 연락처를 조회합니다.

{
  "request_url": "https://crm.example.com/api/contacts/search?phone={PHONE_NUMBER}&email={EMAIL}",
  "request_method": "GET",
  "request_parameters": {},
  "response_data_location": "data"
}

성공: 연락처를 찾음

200 OK
Content-Type: application/json
{ "id": "c_42018", "first_name": "Jane", "last_name": "Doe" }

연락처를 찾을 수 없음

404 Not Found

플랫폼은 404를 '찾을 수 없음' (오류 아님)으로 처리합니다. skip_account_creation가 false이면 흐름이 contact_create_endpoint로 진행됩니다.

찾을 수 없음 대체 패턴: 유효함

200 OK
{}

일부 CRM은 일치하는 레코드가 없는 경우 404 대신 빈 데이터가 있는 200 OK를 반환합니다. 플랫폼은 두 가지를 동일하게 처리합니다. 둘 다 다음 단계(사용 설정된 경우 생성)를 트리거합니다.

일시적인 실패

503 Service Unavailable
}

레이어 1 즉시 HTTP 재시도를 트리거합니다 (총 2회 시도). 그래도 실패하면 레이어 3 명령어 수준 재시도로 넘어갑니다.

엔드포인트 2 - `contact_create_endpoint`

연락처를 만듭니다. custom_id_location 필드는 응답 내에서 새 연락처의 ID를 찾을 위치를 플랫폼에 알려줍니다.

{
  "request_url": "https://crm.example.com/api/contacts",
  "request_method": "POST",
  "request_parameters": {
    "first_name": "{FIRST_NAME}",
    "last_name": "{LAST_NAME}",
    "email": "{EMAIL}",
    "phone": "{PHONE_NUMBER}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

생성 완료

201 Created
{ "id": "c_99812", "first_name": "John", "last_name": "Doe" }

2xx이지만 구성된 위치에 ID가 누락됨

200 OK
{}

엔드포인트가 구성된 위치에 id 없이 200 OK를 반환했습니다. 플랫폼은 경고를 로깅하고 null contact_id를 다운스트림으로 전달합니다 (예외가 발생하지 않고 재시도하지 않음). 이를 구성 스멜로 간주합니다. response_data_location 및 custom_id_location는 엔드포인트가 이 경로에서 반환하는 모든 2xx의 ID를 안정적으로 생성해야 합니다.

엔드포인트 3 - `case_create_endpoint`

티켓을 만듭니다. 이전 단계의 contact_id는 {ACCOUNT_ID}로 사용할 수 있습니다.

{
  "request_url": "https://crm.example.com/api/cases",
  "request_method": "POST",
  "request_parameters": {
    "subject": "{TICKET_SUBJECT}",
    "description": "{TICKET_DESCRIPTION}",
    "contact_id": "{ACCOUNT_ID}",
    "channel": "{CHANNEL}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  },
  "response_data_location": "data",
  "custom_id_location": "id"
}

생성 완료

201 Created
{ "id": "case_77103", "status": "new" }

response_data_location: "data"를 사용하면 플랫폼이 파싱된 응답 본문으로 경로를 확인합니다. 그런 후 custom_id_location: "id" → ticket_id = "case_77103"에서 필드를 읽고 세션 후로 이동합니다.

엔드포인트 4 - `case_comment_endpoint`

이 엔드포인트는 통화 또는 채팅이 종료된 후 티켓에 세션 요약 댓글을 추가합니다. RECORD_ID 변수는 3단계에서 생성된 ticket_id를 전달합니다.

{
  "request_url": "https://crm.example.com/api/cases/{RECORD_ID}/comments",
  "request_method": "POST",
  "request_parameters": {
    "body": "{COMMENT_BODY}",
    "agent_email": "{AGENT_EMAIL}",
    "channel": "{CHANNEL}",
    "duration": "{CALL_DURATION}",
    "external_session_id": "{SESSION_TYPE}-{SESSION_ID}"
  }
}

case_lookup_url가 구성된 일반 API 인스턴스의 경우 플랫폼은 티켓 생성 단계가 성공적으로 완료될 때까지 이 엔드포인트를 전달하지 않습니다. 따라서 여기서 RECORD_ID가 누락되면 일시적인 상태가 아니라 구성 문제가 있는 것입니다.

변형: 계정 생성 사용 중지됨

이 예시는 최소 일반 API 구성에 대해 제공된 이전 예시와 매우 유사하지만, 여기서는 인스턴스가 CRM에서 연락처를 만드는 것을 허용하지 않습니다. 계정 조회는 실행되지만 계정 생성은 실행되지 않습니다.

인스턴스 설정 변경

{
  "skip_account_creation": true,
  "skip_account_lookup": false
}

인스턴스 설정 변경에는 다음 동작이 포함됩니다.

계정 단계는 contact_find_endpoint만 호출합니다. 연락처를 찾을 수 없으면 contact_create_endpoint를 호출하지 않습니다.
기록 단계에서 null contact_id를 수신합니다. 플랫폼은 contact_id 없이 티켓 생성을 진행합니다. {ACCOUNT_ID}는 비어 있는 것으로 확인되고 contact_id 필드는 case_create_endpoint 페이로드에서 완전히 삭제됩니다.
즉, 티켓 생성 엔드포인트는 이 구성에서 contact_id 없이 티켓을 만들 수 있어야 합니다. CRM에서 모든 티켓에 연결된 연락처가 필요한 경우 이 구성은 호환되지 않습니다.

`case_create_endpoint`의 방어 패턴

contact_id가 없으면 CRM에 발신자에 대한 컨텍스트가 평소보다 적습니다. =DEFAULT_VALUE 도우미를 사용하여 요청에서 사용 가능한 모든 식별 정보를 캡처하고 이를 대체 신호로 전달할 수 있습니다.

"request_parameters": {
  "subject": "{TICKET_SUBJECT}",
  "contact_id": "{ACCOUNT_ID}",
  "contact_origin": "=DEFAULT_VALUE(\"{EMAIL}\", \"{PHONE_NUMBER}\", \"anonymous\")"
}

=DEFAULT_VALUE 도우미는 비어 있지 않은 첫 번째 값을 선택하므로 CRM은 이메일 또는 전화번호가 있는 경우 이를 수신하고, 둘 다 없는 경우에만 리터럴 문자열 "anonymous"를 수신합니다. 이는 식별 연락처 정보가 첨부되지 않은 티켓에 플래그를 지정하는 데 유용합니다.

변형: 조회 전용 티켓 흐름 (기록 생성 없음)

계정 작업은 정상적으로 실행되지만 티켓 생성은 사용 중지됩니다. 통합은 조회를 통해 표시되는 기존 티켓에만 댓글을 첨부합니다.

인스턴스 설정 변경

{
  "skip_record_creation": true,
  "case_lookup_url": "https://crm.example.com/api/cases/{RECORD_ID}"
}

변경사항에는 다음 동작이 포함됩니다.

기록 단계에서는 case_find_endpoint를 호출하고 반환된 티켓을 사용합니다. 티켓을 찾을 수 없으면 체인이 기록 단계에서 중지되고 case_create_endpoint가 호출되지 않습니다.
세션 후 엔드포인트 (case_comment_endpoint, case_update_endpoint 등)는 티켓이 성공적으로 조회된 경우에만 전달됩니다. ticket_id가 구체화되지 않으면 Rails 측 ready? 가드가 이러한 명령어를 큐에 추가된 상태로 유지하고 결국 만료되도록 합니다.
실제 영향: 이 구성에서는 세션 후 엔드포인트가 알려진 티켓에 연결된 세션만 수신합니다. "missing ticket_id" 브랜치를 처리할 필요가 없습니다.

실제 권장 멱등성 키

플랫폼은 SESSION_TYPE 및 SESSION_ID를 모두 템플릿 변수로 노출합니다. 복합 키 패턴을 적용하는 가장 깔끔한 방법은 모든 관련 요청 본문에 직접 적용하는 것입니다. 그러면 엔드포인트에 추가 로직 없이 작업할 수 있는 표준 키가 있습니다.

"request_parameters": {
  "...your fields...": "...",
  "ccai_session_key": "{SESSION_TYPE}-{SESSION_ID}"
}

동일한 호출의 경우 체인의 모든 엔드포인트 (계정 > 레코드 > 세션 후)를 재시도할 때마다 동일한 ccai_session_key가 생성됩니다. CRM의 생성 또는 upsert 로직에서 중복 삭제 앵커로 사용합니다. 예를 들어 (ccai_session_key, endpoint_kind)에 대한 upsert는 중복 레코드를 생성하지 않고 재시도를 안전하게 흡수합니다.

복원력이 우수한 엔드포인트 빌드 (멱등성 및 설계 팁)

요청이 반복될 수 있으므로 (즉시 재시도 + 며칠에 걸친 재시도) 엔드포인트는 멱등성을 가져야 합니다.

안정적인 복합 상호작용 식별자를 멱등 키로 사용합니다.
- 세션 유형을 세션 ID와 결합합니다(예: call-12345 또는 chat-12345).
- call_id 또는 chat_id에만 의존하지 마세요. 각 시퀀스는 1에서 시작할 수 있으므로 음성 및 채팅 ID가 중복될 수 있습니다.
중복 요청으로 보이는 요청을 받은 경우 다음 단계를 따르세요.
- 페이로드를 검사하여 실제로 중복인지 확인합니다. 댓글 또는 메모 엔드포인트와 같은 일부 공유 엔드포인트는 여러 명령어 유형에서 사용할 수 있습니다.
- 생성 작업의 경우 정상적인 성공 조건에서는 중복 요청이 발생하지 않지만, CRM에서 요청을 처리한 후 플랫폼에서 성공 응답을 받기 전에 오류를 반환하거나 시간이 초과되면 중복 요청이 발생할 수 있습니다.
- 중복 생성 요청이 확인되면 다른 레코드 대신 이전에 생성된 레코드 ID를 반환합니다.
누락된 ID를 명시적으로 처리합니다.
- 티켓 생성 시 contact_id가 누락되면 일반적으로 계정 조회 또는 계정 생성이 사용 중지된 구성임을 나타냅니다. 인스턴스에 계정이 필요한 경우 연락처 없이 자동으로 티켓을 생성하는 대신 조사하세요.
- 티켓 조회가 구성된 일반적인 API 설정에서는 세션 후 호출에 ticket_id가 누락되는 경우가 없습니다. 요청을 일반적인 노옵으로 처리하기 전에 티켓 조회 구성 및 페이로드 템플릿을 확인하세요.
업데이트의 경우 카운터를 증가시키는 대신 필드를 특정 값으로 설정하여 반복 호출이 안전하도록 합니다.

문제 해결 및 모니터링 가능성

커스텀 CRM 통합을 디버깅할 때는 다음 패턴에 유의하세요.

동일한 엔드포인트에 대한 반복 호출:
- 명령어 수준 재시도(~7일, 14회 시도)의 재시도 일정과 타임스탬프를 비교합니다.
- 세션 유형 + 통화 또는 채팅 세션 ID와 같은 복합 세션 식별자를 사용하여 이벤트를 상호 연결합니다.
- CCAI Platform에서 내보낸 로그는 추적 가능성을 위해 API 이벤트와 함께 통화 또는 채팅 세션 ID를 표시하는 데 도움이 될 수 있습니다.
- 엔드포인트가 재시도할 수 없는 구성 실패 대신 재시도할 수 있는 오류 (예: 500)를 지속적으로 반환하는지 확인합니다.
'중지되지 않는' 재시도:
- 엔드포인트에서 반환하는 오류 응답을 검사합니다.
- 영구적인 실패를 의도한 경우 지원팀에 문의하여 구성에 재시도할 수 없는 오류를 표시하는 방법을 안내받으세요.
엔드포인트가 호출되지 않음:
- 확인되는 사항:
  - 업스트림 단계 (계정/레코드)가 성공적으로 완료되고 필요한 ID가 생성되었습니다.
  - 엔드포인트가 커스텀 CRM 설정에서 올바르게 구성되고 사용 설정되어 있습니다.
- 엔드포인트가 잘못 구성되거나 사용 중지되었거나 체인 초기에 오류가 발생하면 특정 단계가 실행되지 않을 수 있습니다.
로그 상관관계 지정:
- 상호작용 ID (call_id/chat_id)를 포함하여 전체 요청 및 응답을 기록합니다.
- 이 ID를 사용하여 CRM 로그를 시간 경과에 따른 플랫폼 동작 (특히 재시도 중)과 연결합니다.

맞춤 CRM의 오류 처리, 재시도, 통화 순서 (일반 API) 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

실행 순서 및 관계 개요

중요한 차이점: 2xx + ID 추출 엔드포인트에 ID 누락

ID 추출 엔드포인트에서 ID 누락의 영향

통합자 가이드

오류 처리: 개요

연쇄 및 종속 항목 규칙

계정 실패가 레코드 작업에 미치는 영향

엔드포인트에 미치는 영향

녹화 실패가 세션 후 작업에 미치는 영향

엔드포인트에 미치는 영향

재시도 및 백오프 동작

HTTP 수준 즉시 재시도 (빠른 재시도)

어댑터 수준 재시도 (빠른 네트워크 복구)

통합 담당자에게 중요한 이유

명령어 수준 재시도 (약 7일, 14회 시도)

재시도할 수 없는 실패

시간 제한 및 네트워크 오류

구분이 중요한 이유

상태 코드 및 제한 시간 동작 매트릭스 (예시 포함)

결과 요약 표

최소한의 일반 API 구성이 포함된 작업 예시

인스턴스 수준 설정

응답 형태

엔드포인트 1 - contact_find_endpoint

성공: 연락처를 찾음

연락처를 찾을 수 없음

찾을 수 없음 대체 패턴: 유효함

일시적인 실패

엔드포인트 2 - contact_create_endpoint

생성 완료

2xx이지만 구성된 위치에 ID가 누락됨

엔드포인트 3 - case_create_endpoint

생성 완료

엔드포인트 4 - case_comment_endpoint

변형: 계정 생성 사용 중지됨

인스턴스 설정 변경

case_create_endpoint의 방어 패턴

변형: 조회 전용 티켓 흐름 (기록 생성 없음)

인스턴스 설정 변경

실제 권장 멱등성 키

복원력이 우수한 엔드포인트 빌드 (멱등성 및 설계 팁)

문제 해결 및 모니터링 가능성

맞춤 CRM의 오류 처리, 재시도, 통화 순서 (일반 API)

중요한 차이점: `2xx` + ID 추출 엔드포인트에 ID 누락

엔드포인트 1 - `contact_find_endpoint`

엔드포인트 2 - `contact_create_endpoint`

엔드포인트 3 - `case_create_endpoint`

엔드포인트 4 - `case_comment_endpoint`

`case_create_endpoint`의 방어 패턴