채팅 플랫폼 API 가이드

이 페이지에서는 채팅 플랫폼 API 엔드포인트에 설명된 대로 채팅 엔드포인트를 사용하는 방법을 보여줍니다.

용어

명확성을 위해 이 문서를 사용할 때 유의해야 할 몇 가지 정의를 소개합니다.

고객: 소프트웨어에 채팅 플랫폼 API를 구현하는 Contact Center AI Platform (CCAI Platform) 고객입니다.
소비자: 채팅 플랫폼 API에 요청을 보내는 소프트웨어입니다.
최종 사용자: 상담사와 채팅을 시도하는 고객의 소프트웨어 사용자입니다.

웹훅 인증

채팅 플랫폼 API는 채팅 중에 발생하는 이벤트를 소비자 서버에 웹훅 요청을 전송하여 소비자에게 전달합니다. 웹훅 페이로드와 유형은 API 사양에 정의되어 있습니다. 각 웹훅 요청에는 X-Signature 및 X-Signature-Timestamp라는 두 개의 헤더가 포함됩니다.

X-Signature에는 다음 형식의 웹훅 서명이 포함됩니다. primary=<primary_signature> secondary=<secondary_signature>

기본 및 보조 서명은 각각 기본 또는 보조 웹훅 비밀의 base64로 인코딩된 sha256 다이제스트이며, X-Signature-Timestamp 헤더와 요청의 json 페이로드가 연결된 문자열입니다.

다음은 샘플 Ruby on Rails 앱에서 웹훅 요청에 대한 승인의 구현 예입니다.

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

개요

일반적으로 채팅 플랫폼 API 대화의 기본 흐름은 다음과 같습니다. 핵심 사항에 번호가 매겨지고 추가 컨텍스트를 위한 메모가 제공됩니다. 고객은 다이어그램의 '고객' 측면만 구현하면 되며, Contact Center AI Platform은 다이어그램의 Google 시스템 및 상담사 측면을 처리합니다. 다이어그램에 포함된 것은 독자에게 채팅의 전체 흐름에 관한 컨텍스트를 제공하기 위한 것입니다.

채팅 플랫폼 API 대화 흐름이 표시됩니다.

최종 사용자 만들기

채팅을 만들 때는 유효한 최종 사용자 ID가 필요합니다. 즉, 채팅을 만들기 전에 최종 사용자가 Contact Center AI Platform 시스템에 있어야 합니다.
최종 사용자는 소비자가 제공하는 문자열 값인 identifier 속성으로 고유하게 식별됩니다. 최종 사용자가 웹 또는 모바일 SDK를 사용한 경우 시스템에 이미 존재할 수 있습니다. POST /end_users 엔드포인트는 동일한 삽입으로 구현되므로 기존 최종 사용자의 경우 다시 만들려고 하면 변경된 데이터가 업데이트되고 최종 사용자의 정보가 반환됩니다.

채팅 만들기

채팅 플랫폼 API를 사용하여 채팅을 만들려면 다음 단계를 따르세요.

새 채팅 페이로드 처리: 채팅 초기화 프로세스는 POST /chats 요청과 비동기적으로 발생합니다. 이 때문에 chat_created 이벤트는 POST /chats 생성 엔드포인트의 API 응답 전후에 수신될 수 있습니다. 소비자의 버그를 방지하려면 chat_created 이벤트와 채팅 생성 API 응답을 동일한 방식으로 처리하는 것이 좋습니다.
스크립트가 포함된 채팅 만들기: 채팅 플랫폼 API는 고객의 플랫폼 내에서 채팅이 발생하는 시나리오를 위해 기존 대화의 스크립트가 포함된 채팅을 만드는 것을 지원합니다(예: Contact Center AI Platform으로 전송되기 전에 챗봇과 채팅). 이를 통해 채팅에 응답하는 상담사에게 채팅 세션에 관한 추가 정보를 제공하고 최종 사용자가 반복하는 것을 방지할 수 있습니다. 스크립트 페이로드 형식은 chat_platform_openapi.yaml을 참고하세요.

대기열 선택 가상 에이전트

API 소비자의 메뉴 선택을 간소화하기 위해 채팅 플랫폼 API는 Dialogflow 가상 에이전트와 함께 사용하여 새 채팅의 대기열 배치를 지원하도록 설계되었습니다.

가상 상담사를 설정하려면 다음 단계를 따라야 합니다.

이 용도로 지정된 가상 에이전트를 만들고 대기열에 할당합니다. 채팅 플랫폼 API로 생성된 모든 새 채팅은 이 대기열에서 생성되어야 합니다. 새 가상 에이전트를 만들고 구성하는 것은 이 문서의 범위를 벗어납니다.
POST 또는 chats 엔드포인트로 새 채팅을 만들 때 가상 상담사가 채팅을 라우팅해야 하는 대기열을 결정하는 데 사용할 수 있는 생성된 채팅에 관한 컨텍스트가 포함된 맞춤 컨텍스트 페이로드를 포함합니다. 컨텍스트 페이로드에는 고객이 정의한 맞춤 데이터가 포함될 수 있지만, 대기열에 할당된 가상 상담사가 데이터에 액세스할 수 있도록 다음 형식을 따라야 합니다.
- 예: "context": {"value": {"foo": "bar" } }를 사용하면 가상 에이전트가 값이 bar인 $session.params.context.foo을 읽을 수 있습니다.
컨텍스트 필드에 포함된 데이터를 사용하여 가상 에이전트 (고객이 구성한 방식에 따라)는 선택한 대기열로 채팅을 에스컬레이션합니다. 타겟 대기열에 상담사가 없는 경우 (예: 대기열이 영업시간 외이거나 용량을 초과하는 시나리오) 에스컬레이션이 리디렉션되고 소비자에게 리디렉션 이유와 사용 가능한 리디렉션 옵션을 나타내는 웹훅이 전송됩니다.

에스컬레이션 전환: 채팅 플랫폼 API의 채팅 에스컬레이션은 Contact Center AI Platform 포털에서 구성된 경우 다음 전환 옵션을 지원합니다.

이메일: 최종 사용자가 지원팀에 이메일을 보내고 채팅을 종료하도록 안내합니다. 최종 사용자가 이 옵션을 선택하면 이메일이 전송된 후 고객이 요청 본문에 "status": "finished" , "escalation_id": <id of escalation> , 및 "deflection_channel": "email" 매개변수를 사용하여 PATCH /chats/:id 엔드포인트를 통해 채팅을 전환되고 종료된 것으로 표시해야 합니다.
가상 상담사로 계속: 기술적으로는 유효한 전환 옵션이지만, 대화를 다시 에스컬레이션하려고만 하는 VA로 대기열 선택 VA를 사용하는 것은 의미가 없습니다.
상담사 대기: 이 옵션은 over_capacity 이유로 에스컬레이션된 경우에만 사용할 수 있습니다. 최종 사용자가 이 옵션을 선택하면 PATCH chats/:id/escalations/:id with deflection_channel=human_agent로 에스컬레이션 전환을 업데이트합니다.
- 외부 전환 링크: 전환에 제공된 링크를 선택하면 채팅이 종료된다는 경고를 최종 사용자에게 표시합니다. 링크를 선택하면 채팅을 종료하고 deflection_channel 매개변수에 external_link를 사용합니다.

메시지 주고받기

메시지를 보내거나 받으려면 다음 단계를 따르세요.

텍스트 콘텐츠: 문자 메시지를 보내려면 API 문서에 정의된 대로 POST /chats/:id/message 엔드포인트를 사용합니다. 메시지를 수신하려면 message_received 웹훅 이벤트를 수신 대기합니다. API 소비자는 최종 사용자가 보낸 메시지를 포함하여 API를 사용하여 전송된 모든 메시지에 대해 message_received 이벤트를 수신합니다.
사진 및 동영상 콘텐츠: 구성된 Cloud Storage 서비스의 사전 서명된 업로드 URL을 고객센터 AI 플랫폼에서 가져오고, 스토리지 서비스에 업로드한 후, 메시지 페이로드의 스토리지 URL을 고객센터 AI 플랫폼에 전송하여 사진 및 동영상 콘텐츠가 전송됩니다.
1. 사전 서명된 URL 가져오기: POST /v1/chats/:chat_id/photos/upload 또는 POST /v1/chats/:chat_id/videos/upload endpoints을 사용하여 Contact Center AI Platform에서 사전 서명된 업로드 URL을 가져옵니다. 이 엔드포인트는 파일 업로드 시 스토리지 서비스로 전달할 필드 모음과 함께 사전 서명된 URL을 반환합니다. 사전 서명된 업로드에는 다음과 같은 제한사항이 있습니다.
  - 콘텐츠 유형은 사진의 경우 image/jpeg, 동영상의 경우 video/mp4입니다.
  - 최대 사진 크기는 2MB입니다. 최대 동영상 크기는 20MB입니다.
  - 만료 시간은 5분입니다.
  - 클라이언트는 업로드하기 전에 사진의 크기를 조절하고 방향을 조정해야 합니다.
  - 각 사전 서명된 URL은 단일 사진 또는 동영상용입니다. 여러 첨부파일을 보내려면 각 첨부파일에 대해 사전 서명된 URL을 요청해야 합니다.
2. 미디어 파일 업로드: 미디어 파일을 업로드하려면 2a에서 가져온 사전 서명된 URL에 POST 요청을 하고 요청 본문에 다음을 포함하세요.
  - "file": 업로드할 파일
  - 사전 서명된 URL 요청의 필드 객체에 반환된 모든 필드입니다.
3. 채팅에 미디어 파일 추가: 채팅에 미디어 파일을 추가하려면 POST /chats/:id/photos 또는 POST /chats/:id/videos 엔드포인트를 사용합니다. 사진 엔드포인트는 사진 배열 전송을 지원하는 반면 동영상 엔드포인트는 한 번에 하나의 동영상만 지원합니다.
  - s3_path 요청 본문 매개변수는 사전 서명된 URL 응답의 key 필드와 동일한 값이어야 합니다.
  - 요청이 성공하면 두 필드가 반환됩니다. 채팅 메시지의 모든 미디어는 media_id로만 참조되므로 API 소비자에서 media_id와 URL의 매핑을 저장하거나 캐시하는 것이 좋습니다.
    - url: 파일이 있는 읽기 전용 S3 또는 Cloud Storage URL입니다.
    - media_id: Contact Center AI Platform의 미디어 파일 ID입니다. 채팅 페이로드에서 미디어를 참조하는 데 사용되는 ID입니다.
4. 미디어 파일을 채팅 메시지로 보내기: 미디어 파일을 채팅 메시지로 보내려면 다음 페이로드를 POST /chats/:id/message endpoint에 보냅니다.
```
{
  "from_user_id": <id of end user>,
  "message":
    "type": <"photo" or "video">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}
```

API 응답에서 인식할 수 없는 JSON 키 예상

모든 API 업데이트는 하위 호환됩니다. Google은 언제든지 기존 API 응답에 새로운 JSON 키를 도입할 권리를 보유합니다. 인식할 수 없는 키를 무시하여 계속 기능을 유지함으로써 방어적으로 응답을 처리하는 것이 좋습니다.

채팅 플랫폼 API 가이드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

용어