OpenFrame API

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：17分

    • openframe API は、Contact Center as a Service (CCaaS) に操作ハンドラーを使用せずにインタラクションレコードを作成および更新する機能を提供するエンドポイントを提供します。

    この API を使用して、エージェントの電話を追跡するインタラクションレコードを作成します。インタラクションレコードが作成されると、エージェントが電話を受けたときにインタラクションが CSM 構成可能ワークスペース に自動的に表示されます。

    この API にアクセスするには、com.sn_openframe_store プラグインをインスタンスにインストールし、呼び出し元ユーザーが sn_openframe_api_user または sn_openframe_user ロールを持っている必要があります。openframe API は sn_openframe 名前空間で実行されます。

    CSM 音声インタラクションレコードの詳細については、「 CSM voice interaction record page」を参照してください。

    openframe:PATCH /openframe/voice-interaction/{interactionSysId}

    インタラクション [interaction] テーブル内の指定されたインタラクションレコードを更新します。サービスとしてのコンタクトセンター (CCaaS) プロバイダーは、これらのレコードを使用して通話を追跡できます。

    URL 形式

    バージョニングされた URL: /api/now/openframe/{api_version}/voice-interaction/{interactionSysId}

    デフォルト URL: /api/now/openframe/voice-interaction/{interactionSysId}

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

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

    表 : 1. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    interactionSysId 更新するインタラクションレコードのSys_id。この値は、 Create Voice Interaction/POST エンドポイントによって返されます。

    データタイプ：文字列

    テーブル:インタラクション [interaction]
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    インタラクション 必須。音声インタラクションの詳細。少なくとも 1 つのパラメーターを渡す必要があります。

    データタイプ: オブジェクト

    "interaction": {
  "additionalParams": {Object},
  "callbackPhoneNumber": "String",
  "clientSessionId": "String",
  "inboundId": "String",
  "userPhoneNumber": "String"
}
    interaction.additionalParams 関連付けられたインタラクションレコードフィールドとそれぞれの値の名前と値のペア。
    たとえば、次のようになります。
    "additionalParams": {
  "direction": "inbound",
  "short_description": "New outbound call",
  "assigned_to": "a8f98bb0eb32010045e1a5115206fe3a"
}

    データタイプ: オブジェクト

    デフォルト：なし
    interaction.callbackPhoneNumber 発信者のコールバック電話番号。これは、コールが切断された場合に、エージェントが発信者に連絡するために使用する番号です。

    データタイプ：文字列

    フォーマット：E.164

    デフォルト：なし
    interaction.clientSessionId この電話を追跡するために使用される外部システム内のレコードの一意の識別子。この情報は、2 つのシステム間でレコードをリンクします。

    データタイプ：文字列

    デフォルト：なし
    interaction.inboundId 音声サービスのアプリケーションプロバイダーの一意の識別子。

    テーブル:プロバイダーチャネルアプリケーション [sys_cs_provider_application] テーブルの受信 ID フィールド。

    デフォルト：なし
    interaction.userPhoneNumber 音声インタラクションに関連付けられたコールを行ったユーザーの電話番号。

    データタイプ：文字列

    フォーマット：E.164
    interactionContext 設定するインタラクションコンテキスト変数。インタラクションレコードに保存するインタラクションコンテキスト変数の名前と値のペア。これらの値は CCaaS によって決定されます。
    たとえば、次のようになります。
    "interactionContext":{
  "devicetype": "genesys",
  "requester_session_language": "en-US"
}

    データタイプ: オブジェクト

    デフォルト：なし
    phoneLog コールを作成して関連付ける電話ログの名前と値のペア。電話ログ [sn_open_frame_phone_log] テーブルの任意のフィールドを指定できます。
    たとえば、次のようになります。
    "phoneLogs":[
  {
    "agent": "String",
    "call_id": "String",
    "start_time": "String"
  }
]

    データタイプ：オブジェクトのアレイ

    デフォルト：なし
    関連レコード コールに関連するレコード。
    データタイプ：オブジェクトのアレイ
    "relatedRecords":[
  {
    "documentId": "String",
    "documentTable": "String"
  }
]

    デフォルト：なし
    relatedRecords.documentId 関連レコードのSys_id。

    データタイプ：文字列

    テーブル: relatedRecords.documentTable パラメーターで指定します。
    relatedRecords.documentTable 関連レコードを含むテーブルの名前。

    データタイプ：文字列

    ヘッダー

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

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    ステータス レコード更新のステータス。
    可能な値：
    • 成功:インタラクションレコードが正常に更新されました。
    • エラー:インタラクションレコードが更新されませんでした。

    cURL 要求

    次のコード例は、sys_id 12961fff7fb2d2102d0cd3cf8c86652b でインタラクションレコードを更新する方法を示しています。

    curl "http://instance.service-now.com/api/now/openframe/voice-interaction/12961fff7fb2d2102d0cd3cf8c86652b" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"interaction\":{
      \"additionalParams\":{
         \"direction\":\"inbound\",
         \"short_description\":\"New Poonam outbound call\",
         \"assigned_to\":\"a8f98bb0eb32010045e1a5115206fe3a\"
      }
   },
   \"interactionContext\":{
      \"devicetype\":\"genesys\",
      \"requester_session_language\":\"en-US\"
   },
   \"phoneLogs\":[
      {
         \"call_id\":\"2323223\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"33535353\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"1997654\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      }
   ],
   \"relatedRecords\":[
      {
         \"documentTable\":\"csm_consumer\",
         \"documentId\":\"59e788fbdb1b1200b6075200cf9619d2\"
      },
      {
         \"documentTable\":\"sys_user\",
         \"documentId\":\"62826bf03710200044e0bfc8bcbe5df1\"
      }
   ]
}" \
--user 'username':'pasword'

    応答：

    {
  "result": {
    "status": "SUCCESS"
  }
}

    openframe:POST /openframe/voice-interaction

    エージェントがコールを受け入れたときに、インタラクション [interaction] テーブルにインタラクションレコードを作成します。サービスとしてのコンタクトセンター (CCaaS) プロバイダーは、これらのレコードを使用して通話を追跡できます。

    このエンドポイントを使用すると、電話を受けるときに、チャットやケースなどの他のネイティブチャネルと同様に、エージェントに一貫したエクスペリエンスを提供できます。

    URL 形式

    バージョニングされた URL: /api/now/openframe/{api_version}/voice-interaction

    デフォルト URL: /api/now/openframe/voice-interaction

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

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

    表 : 7. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    表 : 8. クエリパラメーター
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    インタラクション 必須です。音声インタラクションの詳細。 少なくとも 1 つのパラメーターを渡す必要があります。
    データタイプ: オブジェクト
    "interaction": {
  "additionalParams": {Object},
  "callbackPhoneNumber": "String",
  "clientSessionId": "String",
  "inboundId": "String",
  "userPhoneNumber": "String"
}
    interaction.additionalParams 関連付けられたインタラクションレコードフィールドとそれぞれの値の名前と値のペア。
    たとえば、次のようになります。
    "additionalParams": {
  "direction": "inbound",
  "short_description": "New outbound call",
  "assigned_to": "a8f98bb0eb32010045e1a5115206fe3a"
}

    データタイプ: オブジェクト

    デフォルト：なし
    interaction.callbackPhoneNumber 発信者のコールバック電話番号。これは、コールが切断された場合に、エージェントが発信者に連絡するために使用する番号です。

    データタイプ：文字列

    フォーマット：E.164

    デフォルト：なし
    interaction.clientSessionId この電話を追跡するために使用される外部システム内のレコードの一意の識別子。この情報は、2 つのシステム間でレコードをリンクします。

    データタイプ：文字列

    デフォルト：なし
    interaction.inboundId 音声サービスのアプリケーションプロバイダーの一意の識別子。

    テーブル:プロバイダーチャネルアプリケーション [sys_cs_provider_application] テーブルの受信 ID フィールド。

    デフォルト：なし
    interaction.userPhoneNumber 必須。音声インタラクションに関連付けられたコールを行ったユーザーの電話番号。

    データタイプ：文字列

    フォーマット：E.164
    interactionContext 設定するインタラクションコンテキスト変数。インタラクションレコードに保存するインタラクションコンテキスト変数の名前と値のペア。これらの値は CCaaS によって決定されます。
    たとえば、次のようになります。
    "interactionContext":{
  "devicetype": "genesys",
  "requester_session_language": "en-US"
}

    データタイプ: オブジェクト

    デフォルト：なし
    phoneLog コールを作成して関連付ける電話ログの名前と値のペア。電話ログ [sn_open_frame_phone_log] テーブルの任意のフィールドを指定できます。
    たとえば、次のようになります。
    "phoneLogs":[
  {
    "agent": "String",
    "call_id": "String",
    "start_time": "String"
  }
]

    データタイプ：オブジェクトのアレイ

    デフォルト：なし
    関連レコード コールに関連するレコード。
    データタイプ：オブジェクトのアレイ
    "relatedRecords":[
  {
    "documentId": "String",
    "documentTable": "String"
  }
]

    デフォルト：なし
    relatedRecords.documentId 関連レコードのSys_id。

    データタイプ：文字列

    テーブル: relatedRecords.documentTable パラメーターで指定します。
    relatedRecords.documentTable 関連レコードを含むテーブルの名前。

    データタイプ：文字列

    ヘッダー

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

    表 : 10. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    番号 成功した場合にのみ返されます。新しく作成された音声インタラクションのインタラクション番号。

    データタイプ：文字列
    ステータス レコード作成のステータス。
    可能な値：
    • 成功:インタラクションレコードが正常に作成されました。
    • エラー:インタラクションレコードが作成されませんでした。
    sysId 成功した場合にのみ返されます。新しく作成された音声インタラクションレコードのSys_id。

    テーブル:インタラクション [interaction]

    cURL 要求

    次のコード例は、新しいインタラクションレコードを作成する方法を示しています。

    curl "http://instance.service-now.com/api/now/openframe/voice-interaction" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"interaction\":{
      \"userPhoneNumber\":\"+1303506536\",
      \"clientSessionId\":\"a545t65678\",
      \"callbackPhoneNumber\":\"+14089965744\",
      \"additionalParams\":{
         \"direction\":\"inbound\",
         \"short_description\":\"New outbound call\",
         \"assigned_to\":\"a8f98bb0eb32010045e1a5115206fe3a\"
      }
   },
   \"interactionContext\":{
      \"devicetype\":\"genesys\",
      \"requester_session_language\":\"en-US\"
   },
   \"phoneLogs\":[
      {
         \"call_id\":\"2323223\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"33535353\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      },
      {
         \"call_id\":\"1997654\",
         \"agent\":\"a8f98bb0eb32010045e1a5115206fe3a\",
         \"start_time\":\"2024-11-04 21:45:00\"
      }
   ],
   \"relatedRecords\":[
      {
         \"documentTable\":\"csm_consumer\",
         \"documentId\":\"59e788fbdb1b1200b6075200cf9619d2\"
      },
      {
         \"documentTable\":\"sys_user\",
         \"documentId\":\"62826bf03710200044e0bfc8bcbe5df1\"
      }
   ]
}" \
--user 'username':'password'

    応答：

    {
  "result": {
    "status": "SUCCESS",
    "sysId": "12961fff7fb2d2102d0cd3cf8c86652b",
    "number": "IMS0000052"
  }
}