채팅 플랫폼 API 통합 가이드

이 가이드를 사용하여 Apps API로 서버 측 채팅 통합을 빌드하세요. 이 과정을 마치면 통합에서 다음 작업을 할 수 있습니다.

  • Apps API에 인증합니다.

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

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

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

  • 채팅에 텍스트 메시지를 보냅니다.

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

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

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

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

용어

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

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

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

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

  • Chat: Apps API에서 만드는 CCAI Platform 대화 리소스입니다.

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

시작하기 전에

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

  • 앱 API 사용자 인증 정보

    • 설정 > 개발자 설정 > API 사용자 인증 정보에서 CCAI Platform의 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 플랫폼 채팅으로 최종 사용자 메시지를 보냅니다.

엔드포인트

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

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은 채팅 흐름을 통해 전환 옵션을 반환하거나 전송할 수 있습니다.

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

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

목표: 최종 사용자가 선택한 전환 옵션을 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은 선택한 옵션에 따라 에스컬레이션 레코드를 업데이트하고 채팅을 전환합니다.

채팅 종료

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

엔드포인트

활성 채팅을 종료하려면 다음 엔드포인트를 사용하세요.

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

요청 예시

다음 예시에서는 채팅 종료를 위한 요청 본문을 보여줍니다.

{
  "ended_by_user_id": 456
}

참고사항

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

  • 웹훅 엔드포인트가 최종 chat-state 이벤트를 수신합니다.

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

고급 흐름

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

채팅 전 스크립트 가져오기

CCAI Platform 채팅을 만들기 전에 최종 사용자가 챗봇 대화와 같은 시스템에서 이미 대화를 나눈 적이 있는 경우 이 흐름을 사용하세요.

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

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

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

애플리케이션이 모든 새 채팅을 진입 대기열로 보내고 가상 상담사가 최종 타겟 대기열을 결정하도록 하는 경우 이 흐름을 사용하세요.

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

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

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

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

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

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

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

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

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": {
      "media_id": 789
    }
  }
}

동영상 메시지에는 video 메시지 유형과 동영상 media_id을 사용합니다.

채팅 중에 맞춤 데이터 전송

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

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 또는 평가 데이터 수집

통합에서 채팅 후 평가 환경을 소유하는 경우 다음 채팅 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

정확한 자격 요건 규칙 및 등급 페이로드는 앱 API 참조를 확인하세요.