エージェントマッピング API

  • リリースバージョン: Yokohama
  • 更新日 2025年02月10日
  • 所要時間：5分

    • エージェントマッピング API は、Contact Center as a Service (CCaaS) システムの外部エージェント ID をNow Platformの内部エージェント ID にマッピングするエンドポイントを提供します。

    この API には、外部エージェント管理ユーティリティパック (sn_external_agent) プラグインが必要です。この API を呼び出すには、interaction_agent ロールが必要です。

    CCaaS システムとの統合の詳細については、「 Integrating with contact centers」を参照してください。

    エージェントマッピング:PUT /sn_ct_ctr_it_core/agent_mapping/agent/{agentId}/inboundId/{inboundId}

    Contact Center as a Service (CCaaS) システムの外部エージェント ID を Now Platformの内部エージェント ID にマッピングします。

    エージェントが CCaaS システムにログインまたはログアウトしたときに、このエンドポイントを呼び出してアクティブステータスを更新します。このエンドポイントは、次のデータを使用して外部エージェントマッピング [external_agent_mapping] テーブルのレコードを作成または更新します。
    • 外部 CCaaS エージェント ID
    • 受信 ID に関連付けられたプロバイダーチャネル ID
    • CCaaS システムでのエージェントのアクティブステータス
    • エージェントのユーザー [sys_user] レコードへの参照

    URL 形式

    デフォルト URL: /api/sn_ct_ctr_it_core/agent_mapping/agent/{agentId}/inboundId/{inboundId}

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    agentId 内部エージェントのSys_id。

    データタイプ：文字列

    テーブル:ユーザー [sys_user]
    inboundId CCaaS システムのプロバイダーチャネル ID レコードからの受信 ID。

    データタイプ：文字列

    テーブル:プロバイダーチャネル ID [sys_cs_provider_application]

    フィールド:受信 ID
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (JSON)
    名前 説明
    アクティブ エージェントが現在 CCaaS システムにログインしているかどうかを示すフラグ。
    有効な値：
    • true:エージェントはログインしています。
    • false:エージェントはログアウトしています。

    デフォルト：true

    データタイプ：ブーリアン
    external_agent_id 必須。CCaaS システムからの外部エージェント ID。

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。application/json のみをサポートします。
    Content-Type 要求本文のデータ形式。application/json のみをサポートします。
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 よろしいですね。

    既存のエージェントマッピングレコードが更新されました。
    201 作成されました。

    新しいエージェントマッピングレコードが作成されました。
    400 要求が正しくありません。

    要求で指定されたエージェント ID または受信 ID が無効です。

    応答本文のパラメーター (JSON)

    名前 説明
    結果 要求に関する情報を含む結果オブジェクト。

    データタイプ: オブジェクト
    result.mappingIds 外部エージェントマッピング [external_agent_mapping] テーブルで作成または更新されたレコードのSys_ids。

    データタイプ：文字列のアレイ
    result.message 要求の結果を説明するメッセージ。

    データタイプ：文字列
    result.status 要求のステータス。
    可能な値：
    • 成功
    • 失敗

    データタイプ：文字列

    cURL 要求

    この例では、sys_id da419c1fc312310015519f2974d3ae15 を持つ内部エージェントを、外部 CCaaS システムからの対応する ID 12345 にマッピングします。

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/agent_mapping/agent/da419c1fc312310015519f2974d3ae15/inboundId/ServiceNowVoice" \ 
--request PUT \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{\"external_agent_id\":\"12345\"}" \ 
--user 'username':'password'

    応答本文：

    {
  "result": { 
    "message": "Agent Id mapping record inserted", 
    "status": "success", 
    "mappingIds": [ 
      "128b74fcc3931a50325a4ad9d00131c3" 
    ] 
  } 
}

    cURL 要求

    この例では、 active パラメーターを false に設定して、エージェントが CCaaS システムからログアウトされたことを示します。

    curl "https://instance.service-now.com/api/sn_ct_ctr_it_core/agent_mapping/agent/da419c1fc312310015519f2974d3ae15/inboundId/ServiceNowVoice" \ 
--request PUT \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{"external_agent_id":"12345", "active":"false"}" \ 
--user 'username':'password'

    応答本文：

    { 
  "result": { 
    "message": "Agent Id mapping record updated", 
    "status": "success", 
    "mappingIds": [ 
      "cea77cebebef9e10a341fc7acad0cdc2" 
    ] 
  } 
}