外部セッションイベント

外部セッションイベント機能を使用すると、Webhook を使用して CCAI プラットフォームから外部システムにリアルタイムでデータをストリーミングできます。これにより、カスタムレポート、CRM レコードの更新、自動化されたやり取り後のワークフローでセッションライフサイクルをすぐに確認できます。

外部セッションイベントは、チャットまたは音声通話の状態が変化するたびにサーバーに通知するプッシュベースのメカニズムを提供します。API エンドポイントを指定すると、CCAI Platform は、移行が発生するたびに（通話接続、エージェント割り当て、セッション切断など）、JSON 形式のイベントデータをインフラストラクチャに POST します。

外部セッションイベントを構成する

外部セッションイベントを構成する手順は次のとおりです。

CCAI Platform ポータルで、[設定 > デベロッパー設定] をクリックします。[設定] メニューが表示されない場合は、 [メニュー] をクリックします。
[セッションデータのエクスポート] ペインで、[データエクスポート設定を管理] をクリックします。[Session Data Export]（セッションデータのエクスポート）ページが表示されます。
[外部セッションイベント] ペインに移動し、切り替えをオンの位置にクリックします。
次のいずれか、または両方を行います。
- 外部通話セッションイベントを構成する手順は次のとおりです。
  1. [通話イベント - 通話セッションイベントを送信] チェックボックスをオンにします。
  2. [API エンドポイント] フィールドに、ターゲット API の完全な HTTPS URL を入力します。
  3. ユーザー名とパスワードを入力します。プラットフォームはこれらを基本認証に使用します。
- 外部チャットセッションイベントを構成する手順は次のとおりです。
  1. [チャットイベント - チャットセッションイベントを送信] チェックボックスをオンにします。
  2. [API エンドポイント] フィールドに、ターゲット API の完全な HTTPS URL を入力します。
  3. ユーザー名とパスワードを入力します。プラットフォームはこれらを基本認証に使用します。
[保存] をクリックします。

イベントのライフサイクルと状態ロジック

セッションの進行に伴い、CCAI プラットフォームは複数の更新を送信します。更新のたびに、item オブジェクトが利用可能なメタデータで拡充されます。

状態の進行状況の表

イベントの順序	状態	参加者のステータス	重要なデータポイントを追加しました
1. 開始	`connected`	社外向け: `connected`	`call_id`、お客様の`dn`（電話番号）。
2. ルーティング	`connected`	社外向け: `connected`	`queue_path_names`、`initiator`（仮想エージェント）。
3. 割り当て済み	`connected`	エージェント: `accepted`	ライブエージェントの名前と ID が追加されます。
4. アクティブ	`connected`	エージェント: `connected`	メディアストリームが確立されました（会話が開始されます）。
5. 終了	`disconnected`	両方: `disconnected`	`ends_at` のタイムスタンプが入力されます。
6. 最終版	`disconnected`	エージェント: `dispositionSubmitted`	ラップアップコードを含む `dispositions` オブジェクト。

イベントデータのスキーマリファレンス

イベントはオブジェクトとして Webhook に送信されます。各 Webhook イベントの構造は同じです。次の表に示します。

ルートオブジェクト

フィールド	タイプ	説明
`count`	Integer	現在のペイロード内のイベントオブジェクトの数。
`events`	配列	セッションの詳細を含むイベントオブジェクトのコレクション。

セッションのキーフィールド

event_id: イベント通知の UUID。
timestamp: イベントが生成されたときのエポック時間（ミリ秒単位）。
connected_at と ends_at: セッション継続時間の ISO 8601 タイムスタンプ。
initiator: 状態の変更を処理したエンティティ（virtual_agent_15、agent_1 など）を識別します。
dispositions: code、custom_code_id、エージェントの note を含むネストされたオブジェクト。

セキュリティ

すべてのリクエストは、標準の Authorization ヘッダー Authorization: Basic <base64_encoded_credentials> で送信されます。

提供の要件

メソッド: POST
Content-Type: application/json
タイムアウト: サーバーは 5 秒以内に応答する必要があります。
確認応答: エンドポイントは 200 OK ステータスコードを返す必要があります。200 以外のコードが返された場合、プラットフォームは指数バックオフ再試行を使用する可能性があります。

サンプルペイロード

以下は、Webhook へのイベントメッセージで受信されるペイロードの例です。

アクティブな会話（メディア接続済み）

{
  "count": 1,
  "events": [
    {
      "event_id": "fc066edb-d99f-4db4-ba04-fb5dfea0e86a",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "connected",
        "queue_path_names": "Test/Talk to Andrew/English",
        "participants": [
          { "state": "connected", "type": "external", "dn": "+15555555555" },
          { "state": "connected", "type": "agent", "name": "Joe Smith", "agent_number": "528431" }
        ]
      }
    }
  ]
}

最終的な処理（通話後の作業）

{
  "count": 1,
  "events": [
    {
      "event_id": "479798ff-b1ed-4a5c-a910-17a7edb3f283",
      "timestamp": 1767874769480,
      "type": "CallState",
      "item": {
        "call_id": 1395,
        "state": "disconnected",
        "participants": [
          {
            "type": "agent",
            "state": "dispositionSubmitted",
            "dispositions": {
              "code": "Call completed",
              "custom_code_id": "callComplete",
              "note": "none"
            }
          }
        ]
      }
    }
  ]
}

外部セッション イベント コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。