Disposition codes API

処理コード API を使用すると、インテグレーションで次の操作を行うことができます。

  • インスタンス、キュー、セッションの処理コードリストを取得する。

  • 以前に完了した通話またはチャット セッションの処理コードまたはメモ（あるいはその両方）を更新する。

認証とベース URL

このドキュメントのすべてのエンドポイントでは、API ユーザー トークン（ベアラー トークン）を使用した標準の API トークン認証を使用します。

ベース URL: https://SUBDOMAIN.REGION_CODE.ccaiplatform.com

処理コードリストを取得する

使用可能な処理コードを取得します。インスタンス、キュー、セッションのレベルでクエリを実行できます。

インスタンス別

インスタンスの完全な処理コードツリー（すべてのマルチレベル処理コードを含む）を返します。

リクエストの例

次のリクエストは、処理コードの完全なリストを取得します。

GET /api/v1/disposition_codes
Authorization: Bearer {token}
Content-Type: application/json

レスポンスの例

次のレスポンス例は、処理コードの完全なリストを示しています。

{
  "disposition_codes": [
    {
      "id": 1,
      "name": "Issue Resolved",
      "full_path": "/Support/Issue Resolved",
      "children": []
    },
    {
      "id": 2,
      "name": "Escalated",
      "full_path": "/Support/Escalated",
      "children": [
        {
          "id": 3,
          "name": "Tier 2",
          "full_path": "/Support/Escalated/Tier 2",
          "children": []
        }
      ]
    }
  ]
}

キュー別

キューに割り当てられた処理コードを返します。キュー固有のリストが構成されていない場合は、グローバル（インスタンス レベル）のリストが返されます。

リクエストの例

次のリクエストは、キューの処理コードを取得します。

GET /api/v1/disposition_codes?queue_id=QUEUE_ID
Authorization: Bearer TOKEN
Content-Type: application/json

クエリ パラメータ

パラメータ タイプ 必須 説明
queue_id integer はい 処理コードを取得するキューの ID。

セッション別

セッションが最後にルーティングされたキューに基づいて、指定されたセッション ID で使用可能な処理コードを返します。

リクエストの例

次のリクエストは、セッションの処理コードを取得します。

GET /api/v1/disposition_codes?session_id=SESSION_ID
Authorization: Bearer TOKEN
Content-Type: application/json

クエリ パラメータ

パラメータ タイプ 必須 説明
session_id integer はい セッション ID。

処理コードとメモを更新する

以前に完了した通話またはチャット セッションの更新された処理コードまたはメモ（あるいはその両方）を送信します。これにより、新しい処理レコードと CRM メモが作成されます。元の CRM レコードは編集されません。

リクエストの例

次のリクエストは、セッションの処理コードまたはメモを更新します。

POST /api/v1/sessions/SESSION_ID/disposition
Authorization: Bearer TOKEN
Content-Type: application/json

パスパラメータ

パラメータ タイプ 必須 説明
session_id integer はい 更新する通話またはチャットのセッション ID。

リクエスト本文の例

次の例は、リクエスト本文を示しています。

{
  "disposition_code": {
    "id": 5,
    "full_path": "/Support/Verification/Pending Documents"
  },
  "notes": "Customer must upload documents via portal."
}

リクエスト本文のパラメータ

パラメータ タイプ 必須 説明
disposition_code オブジェクト 条件 更新された処理コード。disposition_code または notes のいずれか 1 つ以上を指定する必要があります。
disposition_code.id integer はい（disposition_code を指定した場合） 処理コード ID。
disposition_code.full_path 文字列 はい（disposition_code を指定した場合） 処理コードの完全な階層パス（例: /Support/Verification/Pending Documents）。セッションの処理ツリーに対する 検証に使用されます。
notes 文字列 いいえ 更新されたエージェントのメモ。メモの動作 の表をご覧ください。

メモの動作

値 行動
テキスト付きで表示 （例: "notes": "Updated notes"） 既存のメモが新しいテキストに置き換えられます。
空の文字列として表示 （"notes": ""） 既存のメモを明示的にクリアします。セッション メタデータ ファイルにメモは含まれなくなります。CRM の履歴には以前のレコードが保持されます。
省略 （リクエストにフィールドがない） 既存の注釈は変更されません。

電話拒否（DNC）の処理

[電話拒否] の処理を送信するには、disposition_code.id: -1 を使用します。 これは、インスタンスで電話拒否機能が有効になっていて、電話拒否の処理が構成されている場合にのみ受け入れられます。それ以外の場合、API は 422 Unprocessable Entity というメッセージとともに「この テナントでは電話拒否の処理が有効になっていません」を返します。

エージェントの属性

API にはエージェント ID は含まれません。システムは、優先順位に従って、次の処理を属性として割り当てます。

  1. このセッションの処理を最初に送信したエージェント。

  2. 元の処理が存在しない場合は、通話またはチャットの最新のエージェント参加者。

どちらも存在しない場合、API は 422 Unprocessable Entity を返します。

検証

検証ルールは次のとおりです。

  • セッションの通話またはチャットが終了している必要があります。アクティブなセッションで処理を更新しようとすると、422 Unprocessable Entity が返されます。

  • disposition_code.id パラメータと disposition_code.full_path パラメータは、セッションの処理ツリー（セッションが最後にルーティングされたキューに基づく）に対して検証されます。

  • allow_disposition_edit 管理者設定は、UI 専用のコントロールです。この設定に関係なく、公開 API は常に処理データを更新できます。

レスポンスの例

次の例は、リクエストが成功した場合のレスポンスを示しています。

{
  "session_id": 12345,
  "disposition": {
    "id": 5,
    "name": "Verification Pending",
    "full_path": "/Support/Verification/Pending Documents",
    "notes": "Customer must upload documents via portal.",
    "submitted_at": "2026-03-13T10:15:01Z"
  }
}

注: name フィールドは、指定された id 値と full_path 値に基づいて、サーバーによって処理ツリーから解決されます。便宜上、レスポンスで返されます。

セッション メタデータ

この API を使用して処理を更新すると、次のようになります。

  • 外部ストレージ: セッション メタデータ ファイルが再生成され、 既存のメタデータ ファイルが上書きされます。

  • CRM: 新しいメモが作成され、監査証跡が保持されます。

エラー処理

このセクションでは、エラー処理について説明します。

共通のステータス コード

ステータス 条件 メッセージの例
400 Bad Request 必須フィールドがない（disposition_code と notes の両方が存在しない）、または形式が無効です。 「disposition_code または notes のいずれか 1 つ以上を指定する必要があります。」
401 Unauthorized API トークンが無効または欠落しています。 「Unauthorized」
403 Forbidden API ユーザーが、指定されたセッションまたはテナントにアクセスできません。 「Forbidden」
404 Not Found セッションが見つからないか、存在しません。 「Session not found.」
422 Unprocessable Entity さまざまな検証エラー。422 処理できないエンティティのシナリオ の表をご覧ください。 422 処理できないエンティティのシナリオ の表をご覧ください。

422 処理できないエンティティのシナリオ

シナリオ エラー メッセージ
通話またはチャット セッションがまだアクティブである 「Session has not ended. Disposition can only be updated for completed sessions.」
セッションのツリーに処理コード ID が見つからない 「Disposition code is invalid for this session's queue.」
電話拒否の処理が送信されたが、機能が有効になっていない 「Do Not Call disposition is not enabled for this tenant.」
属性のエージェント参加者を解決できない 「Unable to determine agent for disposition attribution.」

レスポンスの例

次の例は、エラー レスポンスを示しています。

{
  "error": {
    "code": "session_not_ended",
    "message": "Session has not ended. Disposition can only be updated for completed sessions.",
    "details": {
      "session_id": 12345
    }
  }
}

一般的なインテグレーション フロー

一般的なインテグレーション フローは次のとおりです。

  1. 関連するキューまたはセッションの処理コードを取得します。

    • GET /api/v1/disposition_codes?session_id=SESSION_ID

  2. 選択する処理ツリーをユーザーまたは自動システムに提示します。

  3. 更新された処理を送信します。

    • POST /api/v1/sessions/SESSION_ID/disposition

    • 選択した処理コード（id と full_path を含む）とメモを含めます。

  4. レスポンスを処理します。

    • 200 OK の場合: 処理が更新されました。CRM レコードは自動的に更新されます。

    • エラーの場合: エラー メッセージを表示し、必要に応じて再試行またはエスカレーションします。

CRM の動作

この API を使用して処理を送信すると、次のようになります。

  • Salesforce、ServiceNow、Zendesk、Dynamics、HubSpot などの接続された CRM に新しい CRM メモが作成されます。元のメモは変更されません。

  • 外部ストレージの場合、セッション メタデータ ファイルは更新された処理データで上書きされます。

制限

HubSpot の通話エンゲージメントには、スカラー hs_call_disposition プロパティが含まれています。このプロパティは、処理が更新されるたびに上書きされます（追加されません）。HubSpot のメモには完全な履歴が保持されますが、エンゲージメント プロパティには最新の処理コードのみが反映されます。