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

채팅 플랫폼 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은 다이어그램의 시스템 및 상담사 측면을 처리합니다. 다이어그램에 포함된 것은 독자에게 채팅의 전반적인 흐름에 대한 컨텍스트를 제공하기 위한 것입니다.

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

최종 사용자 만들기

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

채팅 만들기

채팅 플랫폼 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 또는 채팅 엔드포인트로 새 채팅을 만들 때 가상 에이전트가 채팅을 라우팅해야 하는 대기열을 결정하는 데 사용할 수 있는 생성된 채팅에 대한 일부 컨텍스트를 포함하는 커스텀 컨텍스트 페이로드를 포함합니다. 컨텍스트 페이로드는 고객이 정의한 모든 커스텀 데이터를 포함할 수 있지만, 대기열에 할당된 가상 에이전트가 데이터에 액세스할 수 있도록 하려면 다음 형식이어야 합니다.
- 예: "context": {"value": {"foo": "bar" } }를 사용하면 가상 에이전트가 $session.params.context.foo 값을 bar로 읽을 수 있습니다.
컨텍스트 필드에 포함된 데이터를 사용하여 가상 에이전트는 고객이 구성한 방식에 따라 채팅을 선택한 대기열로 에스컬레이션합니다. 대상 대기열에 상담사가 없는 경우 (예: 대기열이 영업시간 외 또는 용량 초과인 시나리오) 에스컬레이션이 리디렉션되고 소비자는 리디렉션 이유와 사용 가능한 리디렉션 옵션을 나타내는 웹훅을 수신합니다.

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

이메일: 최종 사용자가 지원팀에 이메일을 보내고 채팅을 종료하도록 합니다. 최종 사용자가 이 옵션을 선택하면 이메일이 전송된 후 고객은 요청 본문에 다음 매개변수가 포함된 PATCH /chats/:id 엔드포인트를 사용하여 채팅을 리디렉션되고 종료된 것으로 표시해야 합니다. "status": "finished" , "escalation_id": <id of escalation> , 및 "deflection_channel": "email"
가상 에이전트로 계속: 기술적으로는 유효한 리디렉션 옵션이지만 가상 에이전트가 채팅을 다시 에스컬레이션하려고 하므로 대기열 선택 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 이벤트를 수신합니다.
사진 및 동영상 콘텐츠: 사진 및 동영상 콘텐츠는 Contact Center AI Platform에서 구성된 Cloud Storage 서비스의 사전 서명된 업로드 URL을 가져오고, 스토리지 서비스에 업로드한 후, 메시지 페이로드의 스토리지 URL을 Contact Center AI Platform으로 전송하여 전송됩니다.
1. 사전 서명된 URL 가져오기: Contact Center AI Platform에서 사전 서명된 업로드 URL을 가져옵니다. POST /v1/chats/:chat_id/photos/upload 또는 POST /v1/chats/:chat_id/videos/upload endpoints를 사용합니다. 이 엔드포인트는 파일을 업로드할 때 스토리지 서비스로 전달할 필드 모음과 함께 사전 서명된 URL을 반환합니다. 사전 서명된 업로드에는 다음과 같은 제한사항이 있습니다.
  - Content-Type은 사진의 경우 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">,
    "media_id": < media_id returned as described in 2.c >
  }
}
```

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

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

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

용어