チャットプラットフォーム API ガイド

このページでは、チャットプラットフォーム API エンドポイントで説明されているように、チャットエンドポイントを使用する方法について説明します。

用語

このドキュメントを使用する際に留意すべき定義を以下に示します。

お客様: ソフトウェアにチャットプラットフォーム API を実装している Contact Center AI Platform（CCAI Platform）のお客様。
コンシューマー: チャットプラットフォーム API にリクエストを行うソフトウェア。
エンドユーザー: エージェントとのチャットを試みている、お客様のソフトウェアのユーザー。

Webhook 認証

チャットプラットフォーム API は、チャット中に発生したイベントを、Webhook リクエストをコンシューマーのサーバーに送信することでコンシューマーに伝えます。Webhook のペイロードとタイプは API 仕様で定義されています。各 Webhook リクエストには、X-Signature と X-Signature-Timestamp の 2 つのヘッダーが含まれています。

X-Signature には、次の形式の Webhook 署名が含まれます。 primary=<primary_signature> secondary=<secondary_signature>

プライマリ署名とセカンダリ署名は、それぞれプライマリまたはセカンダリの Webhook シークレットの 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 エンドポイントはべき等な 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 または chats エンドポイントを使用して新しいチャットを作成する場合は、作成されたチャットに関するコンテキストを含むカスタムコンテキストペイロードを含めます。このコンテキストは、チャットをどのキューに転送するかを仮想エージェントが判断するために使用できます。コンテキストペイロードには、お客様が定義した任意のカスタムデータを含めることができますが、キューに割り当てられた仮想エージェントがデータにアクセスできるようにするには、次の形式にする必要があります。
- 例: "context": {"value": {"foo": "bar" } } を指定すると、仮想エージェントは値が bar の $session.params.context.foo を読み取ることができます。
コンテキストフィールドに含まれるデータを使用して、仮想エージェントは（お客様の構成方法に基づいて）チャットを選択したキューにエスカレーションします。ターゲットキューにエージェントがいない場合（キューが営業時間外または容量超過の場合など）、エスカレーションは回避され、回避の理由と利用可能な回避オプションを示す Webhook が消費者に送信されます。

エスカレーションの回避: チャットプラットフォーム API のチャットエスカレーションは、Contact Center AI Platform ポータルで構成されている場合、次の回避オプションをサポートします。

メール: エンドユーザーにサポートにメールを送信してもらい、チャットを終了します。エンドユーザーがこのオプションを選択すると、メールが送信された後、お客様はリクエストの本文で "status": "finished" , "escalation_id": <id of escalation> , と "deflection_channel": "email" のパラメータを使用して PATCH /chats/:id エンドポイントを使用し、チャットを転送済みとしてマークして終了する必要があります。
仮想エージェントで続行: 技術的には有効な回避オプションですが、キュー選択 VA を使用する意味がありません。VA はチャットを再度エスカレーションしようとするだけです。
Keep waiting for human agent（人間のエージェントを待機し続ける）: このオプションは、理由が over_capacity のエスカレーションでのみ使用できます。エンドユーザーがこのオプションを選択した場合は、PATCH chats/:id/escalations/:id with deflection_channel=human_agent でエスカレーション回避を更新します。
- 外部の回避リンク: 回避で提供されたリンクを選択するとチャットが終了することをエンドユーザーに警告します。リンクが選択された場合は、チャットを終了し、deflection_channel パラメータに external_link を使用します。

メッセージを送信、受信する

メッセージを送信または受信する手順は次のとおりです。

テキストコンテンツ: テキストメッセージを送信するには、API ドキュメントで定義されている POST /chats/:id/message エンドポイントを使用します。メッセージを受信するには、message_received Webhook イベントをリッスンします。API コンシューマーは、エンドユーザーが送信したメッセージを含め、API を使用して送信されたすべてのメッセージに対して message_received イベントを受け取ります。
写真と動画のコンテンツ: 写真と動画のコンテンツは、構成された Cloud Storage サービスの事前署名付きアップロード URL を Contact Center AI Platform から取得し、ストレージサービスにアップロードしてから、メッセージペイロードでストレージ URL を Contact Center AI Platform に送信することで送信されます。
1. 署名付き URL の取得: POST /v1/chats/:chat_id/photos/upload または POST /v1/chats/:chat_id/videos/upload endpoints を使用して、Contact Center AI Platform から署名付きアップロード URL を取得します。このエンドポイントは、署名付き URL と、ファイルのアップロード時にストレージサービスに転送するフィールドのコレクションを返します。署名付きアップロードには次の制限があります。
  - Content-Type は写真の場合は image/jpeg、動画の場合は video/mp4 です。
  - 写真の最大サイズは 2 MB です。動画の最大サイズは 20 MB です。
  - 有効期限は 5 分です。
  - クライアントは、写真をアップロードする前にサイズを変更し、向きを調整する必要があります。
  - 事前署名付き URL は写真または動画 1 つにつき 1 つです。複数の添付ファイルを送信するには、それぞれについて事前署名付き URL をリクエストする必要があります。
2. メディアファイルのアップロード: メディアファイルをアップロードするには、2a で取得した事前署名付き URL に POST リクエストを送信します。リクエスト本文には次の内容を含めます。
  - "file": アップロードするファイル
  - 署名付き URL リクエストの fields オブジェクトで返されるすべてのフィールド。
3. メディアファイルをチャットに追加する: メディアファイルをチャットに追加するには、POST /chats/:id/photos エンドポイントまたは POST /chats/:id/videos エンドポイントを使用します。写真のエンドポイントは写真の配列の送信をサポートしていますが、動画のエンドポイントは一度に 1 つの動画のみをサポートしています。
  - s3_path リクエスト本文パラメータは、署名付き URL レスポンスの key フィールドと同じ値にする必要があります。
  - リクエストが成功すると、2 つのフィールドが返されます。チャットメッセージ内のすべてのメディアは 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 ガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

用語