채팅 플랫폼 API 통합 가이드

이 가이드를 참고하여 Apps API를 사용해 서버 측 채팅 통합을 빌드하세요. 완료되면 통합에서 다음을 수행할 수 있습니다.

  • Apps API에 인증합니다.

  • 최종 사용자를 만들거나 업데이트합니다.

  • 최종 사용자와 채팅을 시작합니다.

  • Contact Center AI Platform에서 웹훅 이벤트를 수신하고 확인합니다.

  • 채팅에 문자 메시지를 보냅니다.

  • 채팅 전 스크립트 가져오기, 대기열 선택 가상 에이전트 라우팅, 에스컬레이션 회피, 미디어 첨부파일과 같은 선택적 분기를 처리합니다.

  • 대화가 완료되면 채팅을 종료합니다.

이 가이드는 고객 소유 채팅 환경을 CCAI Platform에 연결하는 백엔드 서비스를 빌드하는 개발자를 대상으로 합니다. CCAI Platform에서 API 사용자 인증 정보를 만들고, HTTPS 웹훅 엔드포인트를 호스팅하고, 보안 비밀을 안전하게 저장하고, 서버에서 HTTP 요청을 수행할 수 있다고 가정합니다.

이 가이드는 Apps API Chat 엔드포인트를 보완합니다. 전체 요청 및 응답 스키마에는 API 참조를 사용하고 권장되는 엔드 투 엔드 구현 흐름에는 이 가이드를 사용하세요.

용어

이 문서에는 다음 정의가 적용됩니다.

  • 고객: 자체 소프트웨어에서 채팅 통합을 구현하는 CCAI Platform 고객입니다.

  • 소비자: Apps API에 요청을 보내고 CCAI Platform 웹훅 이벤트를 수신하는 고객 소유 서버 측 애플리케이션입니다.

  • 최종 사용자: 고객의 소프트웨어를 사용하여 상담사 또는 가상 에이전트와 채팅을 시작하거나 계속하는 사람입니다.

  • 채팅: Apps API가 만드는 CCAI Platform 대화 리소스입니다.

  • 웹훅 엔드포인트: CCAI Platform에서 채팅 이벤트를 수신하는 소비자 애플리케이션의 HTTPS 엔드포인트입니다.

시작하기 전에

시작하기 전에 다음과 같은 항목이 필요합니다.

  • 앱 API 사용자 인증 정보

    • CCAI Platform의 설정 > 개발자 설정 > API 사용자 인증 정보에서 API 사용자 인증 정보를 만듭니다.

    • 사용자 인증 정보 보안 비밀을 안전하게 저장합니다. 브라우저나 모바일 클라이언트 코드에 노출하지 마세요.

  • 테넌트 URL 세부정보

    • CCAI Platform 하위 도메인 및 도메인을 식별합니다.

    • Apps API 기준 URL은 다음과 같습니다. https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1

  • 웹훅 엔드포인트

    • CCAI Platform에서 POST 요청을 수신할 수 있는 공개 HTTPS 엔드포인트를 호스팅합니다.

    • CCAI Platform 개발자 설정에서 엔드포인트를 구성합니다.

    • 웹훅 기본 및 보조 보안 비밀을 생성하고 저장합니다.

  • 대기열 또는 메뉴 구성

    • 새 채팅이 들어오는 대기열 또는 메뉴를 식별합니다.

    • 대기열 선택 가상 에이전트를 사용하는 경우 API를 통해 채팅을 만들기 전에 해당 가상 에이전트를 구성하고 항목 대기열에 할당합니다.

  • 최종 사용자 ID

    • 시스템에서 각 최종 사용자에게 사용할 안정적인 식별자를 결정합니다.

    • Apps API에서 반환된 CCAI Platform 최종 사용자 ID를 저장합니다.

  • 비율 제한 처리

    • CCAI Platform은 Apps API를 비율 제한합니다. 통합에 재시도 및 백오프를 빌드하고 단일 테넌트에 대한 요청을 한꺼번에 전송하지 마세요.

인증 및 웹훅 보안

통합에서는 두 가지 인증 경로를 사용합니다.

  • 서버에서 CCAI Platform으로의 요청에 대한 Apps API 인증

  • CCAI Platform에서 서버로의 요청에 대한 웹훅 서명 확인

Apps API 요청 인증

요청은 HTTP 기본 인증을 사용합니다. CCAI Platform의 설정 > 개발자 설정 > API 사용자 인증 정보에서 API 토큰을 만들고 비밀번호 필드에 전달합니다 (권장). 테넌트가 기존 인증 경로를 사용하는 경우 회사 키를 사용자 이름으로, 회사 보안 비밀번호를 비밀번호로 전달할 수 있습니다. 전체 인증 설정은 Apps API 참조를 확인하세요. 다음 예시에서는 기본 인증을 사용하여 Apps API 요청을 인증하는 방법을 보여줍니다.

curl -X GET \
  https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1/chats/{chat_id} \
  -u "YOUR_SUBDOMAIN:YOUR_API_TOKEN" \
  -H "Accept: application/json"

사용자 인증 정보를 서버 측 보안 비밀 저장소에 저장하고 보안 정책에 따라 순환하며 브라우저나 모바일 앱에서 전송하지 않습니다.

웹훅 요청 확인

CCAI Platform은 웹훅 엔드포인트로 채팅 이벤트를 전송합니다. 각 웹훅 요청에는 다음이 포함됩니다.

  • X-Signature

  • X-Signature-Timestamp

X-Signature 헤더에는 기본 서명, 보조 서명 또는 둘 다 포함될 수 있습니다.

primary=<primary_signature> secondary=<secondary_signature>

각 서명은 Base64로 인코딩된 HMAC-SHA256 다이제스트입니다. 서명된 값은 원시 JSON 요청 본문과 연결된 타임스탬프 헤더입니다.

X-Signature-Timestamp + raw_request_body

웹훅 핸들러에서 다음을 수행합니다.

  1. X-Signature 및 X-Signature-Timestamp을 읽습니다.

  2. 헤더가 누락된 경우 요청을 거부합니다.

  3. 오래된 타임스탬프를 거부하여 재생 위험을 줄입니다.

  4. JSON을 파싱하기 전에 원시 요청 본문을 읽습니다.

  5. 각 활성 웹훅 보안 비밀을 사용하여 예상 서명을 계산합니다.

  6. 상수 시간 비교를 사용하여 수신된 서명과 예상 서명을 비교합니다.

  7. 활성 보안 비밀이 일치하면 요청을 수락합니다.

다음 Ruby 구현 예시는 UJET 웹훅 서명을 확인하는 방법을 보여줍니다.

require "base64"
require "openssl"
require "active_support/security_utils"

def parse_ujet_signature(header)
  header.to_s.split(/\s+/).each_with_object({}) do |part, result|
    key, value = part.split("=", 2)
    result[key] = value if key && value
  end
end

def expected_signature(secret, timestamp, raw_body)
  Base64.strict_encode64(
    OpenSSL::HMAC.digest(
      OpenSSL::Digest.new("sha256"),
      secret,
      "#{timestamp}#{raw_body}"
    )
  )
end

def secure_match?(received, expected)
  return false if received.nil? || expected.nil?
  return false unless received.bytesize == expected.bytesize

  ActiveSupport::SecurityUtils.secure_compare(received, expected)
end

def verify_ujet_webhook!(request, primary_secret:, secondary_secret:)
  signature_header = request.headers["X-Signature"]
  timestamp = request.headers["X-Signature-Timestamp"]

  return false if signature_header.nil? || timestamp.nil?

  # Optional but recommended: reject stale requests.
  return false if (Time.now.utc - Time.at(timestamp.to_i).utc).abs > 5.minutes

  raw_body = request.body.read
  signatures = parse_ujet_signature(signature_header)

  expected = [
    expected_signature(primary_secret, timestamp, raw_body),
    expected_signature(secondary_secret, timestamp, raw_body)
  ].compact

  received = [
    signatures["primary"],
    signatures["secondary"]
  ].compact

  received.any? do |received_signature|
    expected.any? do |expected_signature_value|
      secure_match?(received_signature, expected_signature_value)
    end
  end
end

확인에 성공하면 성공 응답을 빠르게 반환하고 이벤트를 멱등적으로 처리합니다. 웹훅 전송과 API 응답은 다른 순서로 도착할 수 있으므로 중복 레코드를 만들지 않고 동일한 상태 변경을 두 번 이상 수신할 수 있도록 통합을 빌드하세요.

통합 흐름

다음 흐름은 최종 사용자를 만들고, 채팅을 시작하고, CCAI Platform 이벤트를 수신하고, 메시지를 교환하고, 채팅을 종료합니다.

최종 사용자 만들기 또는 업데이트

목표: 채팅을 만들기 전에 CCAI Platform에 최종 사용자 레코드가 있는지 확인합니다.

엔드포인트

다음 엔드포인트를 사용하여 최종 사용자를 만들거나 업데이트합니다.

POST /apps/api/v1/end_users

요청 예시

다음 예시에서는 최종 사용자를 만들거나 업데이트하기 위한 요청 본문을 보여줍니다.

{
  "identifier": "customer-user-12345",
  "email": "customer.user@example.com",
  "name": "Customer User",
  "phone": "+15551234567"
}

저장할 항목

응답의 CCAI Platform 최종 사용자 ID를 시스템에 저장합니다. 채팅을 만들 때 이 ID를 사용합니다.

기대 효과

  • 최종 사용자가 없으면 CCAI Platform에서 새 레코드를 만듭니다.

  • 동일한 식별자를 가진 최종 사용자가 이미 있는 경우 CCAI Platform은 레코드를 업데이트하고 기존 최종 사용자의 정보를 반환합니다.

채팅 만들기

목표: 최종 사용자를 위해 새 CCAI Platform 채팅을 시작합니다.

엔드포인트

다음 엔드포인트를 사용하여 새 채팅을 시작합니다.

POST /apps/api/v1/chats

요청 예시

다음 예시는 채팅을 만들기 위한 요청 본문을 보여줍니다.

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en"
  }
}

가상 에이전트 라우팅을 위한 선택적 컨텍스트

큐 선택 가상 에이전트에 애플리케이션의 컨텍스트가 필요한 경우 다음 예시와 같이 채팅을 만들 때 컨텍스트 페이로드를 포함합니다.

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en",
    "context": {
      "value": {
        "customer_tier": "gold",
        "issue_type": "billing"
      }
    }
  }
}

가상 에이전트는 해당 컨텍스트의 값을 사용하여 채팅을 수신할 대기열을 결정할 수 있습니다.

기대 효과

  • Apps API는 채팅 리소스를 반환합니다.

  • CCAI Platform은 구성된 웹훅 엔드포인트로 chat_created 웹훅 이벤트를 전송합니다.

  • API 응답과 웹훅 이벤트는 어떤 순서로든 도착할 수 있습니다. 둘 다 채팅 ID를 키로 사용하는 동일한 채팅 기록에 대한 업데이트로 처리합니다.

채팅 웹훅 이벤트 처리

목표: 소비자 애플리케이션을 CCAI Platform 채팅 상태와 동기화된 상태로 유지합니다.

웹훅 엔드포인트는 CCAI Platform의 채팅 수명 주기 및 메시지 이벤트를 처리합니다. 최소한 다음을 저장합니다.

  • 채팅 ID입니다.

  • 이벤트 유형입니다.

  • 이벤트 타임스탬프입니다.

  • 이벤트에 메시지가 포함된 경우 메시지 발신자, 메시지 유형, 메시지 콘텐츠

  • 이벤트가 라우팅 동작을 설명하는 경우 에스컬레이션 또는 디플렉션 데이터

권장 동작

  • 이벤트를 처리하기 전에 모든 웹훅 서명을 확인합니다.

  • 재시도로 인해 중복이 생성되지 않도록 처리된 이벤트 ID 또는 결정론적 이벤트 키를 저장합니다.

  • 이벤트를 수락한 후 2xx 응답을 반환합니다.

  • 가능하면 다운스트림 부작용을 비동기식으로 처리합니다.

기대 효과

CCAI Platform에서 채팅 생성, 수신 메시지, 에이전트 메시지, 에스컬레이션 변경, 채팅 완료와 같은 이벤트를 전송하면 애플리케이션이 채팅 상태를 업데이트합니다.

SMS 보내기

목표: 소비자 애플리케이션에서 CCAI Platform 채팅으로 최종 사용자 메시지를 전송합니다.

엔드포인트

다음 엔드포인트를 사용하여 채팅에 문자 메시지를 보냅니다.

POST /apps/api/v1/chats/{chat_id}/message

요청 예시

다음 예시에서는 문자 메시지를 전송하기 위한 요청 본문을 보여줍니다.

{
  "from_user_id": 456,
  "message": {
    "type": "text",
    "content": "Hello, I need help with my order."
  }
}

기대 효과

  • CCAI Platform에서 메시지를 수락합니다.

  • 메시지가 상담사 또는 가상 에이전트 대화에 표시됩니다.

  • 웹훅 엔드포인트는 자체 애플리케이션이 Apps API를 통해 전송한 메시지를 포함하여 메시지에 대한 메시지 이벤트를 수신합니다.

CCAI Platform에서 메시지 수신 및 표시

목표: 고객 소유 채팅 환경에서 상담사 또는 가상 에이전트 메시지를 표시합니다.

웹훅 엔드포인트가 메시지 이벤트를 수신하는 경우:

  1. 웹훅 서명을 확인합니다.

  2. 이벤트가 새로운지 확인합니다.

  3. 채팅 ID로 채팅을 식별합니다.

  4. 발신자와 메시지 유형을 확인합니다.

  5. 고객 소유 채팅 UI에서 메시지를 렌더링합니다.

  6. 새로고침 또는 재시도 시 대화 기록이 손실되지 않도록 이벤트를 저장합니다.

기대 효과

고객 소유 채팅 UI는 상담사, 가상 에이전트, 최종 사용자가 보낸 메시지를 올바른 순서로 표시합니다. 이벤트가 순서에 맞지 않게 도착하면 이벤트 타임스탬프와 자체 지속성 레이어를 사용하여 표시 순서를 조정합니다.

가상 에이전트에서 상담사로 에스컬레이션

목표: 최종 사용자가 상담사의 도움이 필요할 때 채팅을 가상 에이전트 처리에서 상담사 대기열로 이동합니다.

통합에서 대기열 선택 가상 에이전트를 사용하는 경우 채팅을 대상 대기열로 라우팅하도록 가상 에이전트를 구성합니다. 서버에서 에스컬레이션을 직접 시작하는 경우 Apps API 에스컬레이션 엔드포인트를 사용합니다.

엔드포인트

다음 엔드포인트를 사용하여 가상 에이전트에서 상담사로 채팅을 에스컬레이션합니다.

POST /apps/api/v1/chats/{chat_id}/escalations

요청 예시

다음 예시는 채팅 에스컬레이션 요청 본문을 보여줍니다.

{
  "reason": "by_end_user_ask",
  "force_escalate": false
}

기대 효과

  • 대상 대기열을 사용할 수 있는 경우 채팅이 상담사 처리로 이동합니다.

  • 대기열에서 채팅을 받을 수 없고 편향 대안이 구성된 경우 CCAI Platform은 가상 에이전트와의 채팅을 유지하고 최종 사용자에게 제공되는 대안이 포함된 escalation_deflected 웹훅 이벤트를 전송합니다. 대안은 에스컬레이션 응답에 포함되지 않습니다.

  • 통합은 사용 가능한 편향 옵션을 최종 사용자에게 렌더링합니다.

에스컬레이션-회피 선택 기록

목표: 최종 사용자가 선택한 편향 옵션을 CCAI Platform에 알립니다.

CCAI Platform에서 에스컬레이션-회피 옵션을 제공하는 경우 에스컬레이션 업데이트 엔드포인트로 최종 사용자의 선택을 기록합니다.

엔드포인트

다음 엔드포인트를 사용하여 편향 선택으로 에스컬레이션 레코드를 업데이트합니다.

PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}

지원되는 deflection_channel 값:

  • email — 최종 사용자가 이메일 디플렉션 옵션을 선택합니다.

  • virtual_agent — 최종 사용자가 가상 에이전트를 계속 사용하기로 선택합니다.

  • human_agent — 최종 사용자가 상담사를 계속 기다리기로 선택합니다. 이 값은 용량 초과 전환에만 적용됩니다.

요청 예시

다음 예시는 편향 선택을 기록하기 위한 요청 본문을 보여줍니다.

{
  "deflection_channel": "email"
}

지원되는 deflection_channel 값만 이 엔드포인트로 전송합니다. external_link은 에스컬레이션 업데이트 엔드포인트에 유효한 값이 아닙니다. 최종 사용자가 외부 디플렉션 링크를 따르면 채팅이 종료됩니다.

기대 효과

CCAI Platform은 에스컬레이션에 대한 선택을 기록합니다. 선택사항을 기록해도 채팅이 라우팅되지 않습니다. 통합은 선택사항에 따라 작동합니다. 예를 들어 이메일 편향을 위해 채팅을 종료하거나 계속 대기 선택사항에 대해 force_escalate: true를 사용하여 새 에스컬레이션을 전송합니다.

채팅 종료하기

목표: 대화가 완료되면 채팅을 종료합니다.

엔드포인트

다음 엔드포인트를 사용하여 활성 채팅을 종료합니다.

PATCH /apps/api/v1/chats/{chat_id}/end

요청 예시

다음 예시는 채팅을 종료하는 요청 본문을 보여줍니다.

{
  "ended_by_user_id": 456
}

기대 효과

  • CCAI Platform에서 채팅을 종료합니다.

  • 웹훅 엔드포인트가 최종 채팅 상태 이벤트를 수신합니다.

  • 애플리케이션이 채팅을 완료로 표시하고 해당 채팅에 대한 새로운 최종 사용자 메시지 수락을 중지합니다.

최종 사용자가 편향 옵션을 선택하여 채팅이 종료되는 경우 이 엔드포인트를 사용하여 해당 선택을 기록하지 마세요. 먼저 에스컬레이션에서 선택사항을 기록하거나, PATCH /apps/api/v1/chats/{chat_id}를 사용하여 단일 요청으로 선택사항을 기록하고 채팅을 종료합니다. 이때 상태와 함께 escalation_id 및 deflection_channel를 제공합니다. 선택사항이 기록되지 않은 상태로 종료된 채팅은 에스컬레이션에 선택사항이 기록되지 않고 전환 결과 보고서에 표시되지 않습니다.

고급 플로우

다음 브랜치는 선택사항입니다. 통합에 적용되는 흐름만 구현합니다.

채팅 전 스크립트 가져오기

챗봇 대화와 같이 CCAI Platform 채팅을 만들기 전에 최종 사용자가 이미 시스템에서 대화를 나눈 경우 이 흐름을 사용합니다.

채팅을 만들 때 스크립트 페이로드를 추가합니다. 스크립트는 상담사에게 컨텍스트를 제공하므로 최종 사용자가 정보를 반복할 필요가 없습니다.

Apps API 참조에는 정확한 스크립트 스키마가 포함되어 있습니다.

대기열 선택 가상 에이전트로 채팅 라우팅

애플리케이션이 모든 새 채팅을 항목 큐로 전송하고 가상 에이전트가 최종 대상 큐를 결정하도록 하려면 이 흐름을 사용합니다.

  1. 대기열 선택을 위한 가상 에이전트를 만듭니다.

  2. 가상 에이전트를 항목 대기열에 할당합니다.

  3. 채팅을 만들 때 컨텍스트를 포함합니다.

  4. 컨텍스트를 검사하고 채팅을 올바른 대기열로 에스컬레이션하도록 가상 에이전트를 구성합니다.

  5. 대상 대기열을 사용할 수 없는 경우 전환 옵션을 처리합니다.

사진 또는 동영상 첨부파일 보내기

최종 사용자가 고객 소유 채팅 UI에서 미디어를 전송할 때 이 흐름을 사용합니다.

미디어 흐름에는 네 가지 단계가 있습니다.

1단계 — 미리 서명된 업로드 URL 요청

다음 엔드포인트를 사용하여 사진 또는 동영상 업로드를 위한 미리 서명된 URL을 요청합니다.

POST /apps/api/v1/chats/{chat_id}/photos/upload
POST /apps/api/v1/chats/{chat_id}/videos/upload

2단계 — 반환된 저장소 URL에 파일 업로드

CCAI Platform이 사전 서명된 업로드 응답에서 반환하는 파일과 모든 필드를 포함합니다.

3단계 — 업로드된 파일을 채팅에 추가하기

다음 엔드포인트를 사용하여 업로드된 사진 또는 동영상을 채팅에 추가합니다.

POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos

CCAI Platform에서 반환하는 media_id를 저장합니다. 채팅 메시지 페이로드는 미디어 ID로 미디어를 참조합니다.

4단계 — 미디어를 메시지로 전송

다음 엔드포인트를 사용하여 채팅에 미디어 메시지를 전송합니다.

POST /apps/api/v1/chats/{chat_id}/message

요청 예시

다음 예시는 사진 첨부파일을 전송하기 위한 요청 본문을 보여줍니다.

{
  "from_user_id": 456,
  "message": {
    "type": "photo",
    "content": "Photo of the damaged item",
    "media_id": 789
  }
}

엔드포인트는 type, content, media_id를 플랫 값으로 허용합니다. content에 제공된 중첩 객체는 삭제되고 미디어 참조가 손실됩니다. 동영상 메시지에는 video 메시지 유형과 동영상 media_id를 사용합니다. media_id은 content의 동위 요소입니다.

채팅 중에 맞춤 데이터 전송

통합에서 고객 정의 컨텍스트를 활성 채팅에 연결해야 하는 경우 다음 엔드포인트를 사용합니다.

POST /apps/api/v1/chats/{chat_id}/custom_data

Apps API 참조는 정확한 페이로드 형태와 예약된 키 동작을 정의합니다.

채팅 중에 최종 사용자 ID 업데이트

채팅이 시작된 후 최종 사용자의 ID가 변경되거나 알려지면 다음 엔드포인트를 사용합니다.

POST /apps/api/v1/chats/{chat_id}/end_user

예를 들어 익명의 최종 사용자가 활성 채팅 중에 로그인하고 통합에서 CCAI Platform이 채팅을 업데이트된 최종 사용자 ID와 연결해야 하는 경우 이 엔드포인트를 사용합니다.

고객만족도 또는 평점 데이터 수집

통합에서 채팅 후 평가 환경을 소유하는 경우 다음 채팅 CSAT 및 평가 엔드포인트를 사용하세요.

GET /apps/api/v1/chats/{chat_id}/csat
GET /apps/api/v1/chats/{chat_id}/rating
PATCH /apps/api/v1/chats/{chat_id}/rating

정확한 자격 요건 규칙과 평점 페이로드는 Apps API 참조를 확인하세요.