外部セッション イベント

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

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

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

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

  1. CCAI プラットフォーム ポータルで、[設定] > [デベロッパー設定] をクリックします。 [**設定**] メニューが表示されない場合は、 [**メニュー**] をクリックします。

  2. [セッション データのエクスポート] パネルで、[データ エクスポート設定を管理] をクリックします。 [セッション データのエクスポート] ページが表示されます。

  3. [外部セッション イベント] パネルに移動し、トグルをクリックしてオンにします。

  4. 次のいずれかまたは両方を行います。

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

      1. [通話イベント - 通話セッション イベントを送信] チェックボックスをオンにします。

      2. [API エンドポイント] フィールドに、ターゲット API の完全な HTTPS URL を入力します。

      3. ユーザー名とパスワードを入力します。プラットフォームは、これらを基本認証に使用します。

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

      1. [チャットイベント - チャットセッション イベントを送信] チェックボックスをオンにします。

      2. [API エンドポイント] フィールドに、ターゲット API の完全な HTTPS URL を入力します。

      3. ユーザー名とパスワードを入力します。プラットフォームは、これらを基本認証に使用します。

  5. [保存] をクリックします。

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

セッションが進むにつれて、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"
            }
          }
        ]
      }
    }
  ]
}