会話メンバー API

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

    • 会話メンバー API は、特定のエージェントチャット会話で特定のエージェントのメンバーステータスを削除済みまたは更新に変更するためのメソッドを提供します。

    この API は、対話型インターフェースのエクスペリエンスで、会話中のエージェントメンバーのステータスをプログラムで管理する機能を提供します エージェントチャット 。詳細については、「エージェントチャット」を参照してください。

    この API はデフォルトで利用可能です。呼び出し元ユーザーには、awa_integration_user ロールが必要です。

    会話メンバー:PUT /now/conversation/member/{user_id}/drop

    会話からエージェントを削除します。

    URL 形式

    デフォルト URL: /api/now/conversation/member/{user_id}/drop

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

    表 : 1. パスパラメーター
    名前 説明
    user_id 会話から削除するエージェントのSys_id。

    データタイプ：文字列

    テーブル： ユーザー [sys_user]
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    interaction_id 必須。エージェントをドロップする会話レコードのSys_id。

    データタイプ：文字列

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

    ヘッダー

    次のリクエストや応答ヘッダーは、この 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会話メンバーの操作の処理中にエラーが発生しました。たとえば、次のようになります。
    • 指定されたインタラクションの会話が見つかりません。
    • ユーザーは、提供されたインタラクション会話のメンバーではありません。

      要求に別のuser_idまたはinteraction_idを指定します。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    403 禁止されました。ユーザーには、指定されたレコードへのアクセス権がありません。

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

    名前 説明
    conversation_member ドロップ要求が処理された後の、会話メンバーとしてのエージェントのステータスに関する情報を含むオブジェクト。

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

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    conversation_member.active 現在のユーザーが会話に存在するかどうかを示すフラグ。
    可能な値：
    • true:エージェントは会話でアクティブです。
    • false:エージェントは会話から削除され、チャットのアクティブな参加者ではなくなります。

    データタイプ：ブーリアン
    conversation_member.memberType メンバーエージェントのタイプ。
    可能な値：
    • public_fulfiller:エージェントは、指定された会話で他のエージェントや要求者と公開でチャットできます。
    • 観測者:マネージャーロールを持つユーザーのみが使用できます。会話に参加せずに会話の内容を表示する権限を付与します。
    • private_fulfiller:エージェントは、エージェント間のプライベートチャットに参加して、アクティブな会話について話し合うことができます。

    データタイプ：文字列

    テーブル:会話メンバー [sys_cs_conversation_member]
    conversation_member.conversation_id 必須。エージェントが削除された会話レコードのSys_id。

    データタイプ：文字列

    テーブル:インタラクション [interaction]
    正常終了 ドロップエージェントプロセスが成功したかどうかを示すフラグ。
    有効な値：
    • true:エージェントが正常に削除されました。
    • false:エージェントの削除に失敗しましたが、会話では引き続きアクティブと見なされます。

    データタイプ：ブーリアン
    メッセージ アサインの成功または例外を確認する応答メッセージ。

    成功メッセージ: エージェントの削除要求が正常に処理されました。

    考えられる例外:
    • 無効な要求。入力不足:エージェントsys_idまたはインタラクションsys_idが要求に指定されていません。
    • 提供されたインタラクションはサードパーティインタラクションではありません:要求はサードパーティインタラクションに対してのみ機能し、指定されたinteraction_idはサードパーティインタラクションではありません。
    • 対応するインタラクションの会話が見つかりませんでした:指定されたインタラクション の対応する会話レコードが見つかりませんsys_id。
    • 無効な要求。ユーザーは指定されたインタラクションのメンバーではありません:エージェントsys_idは指定されたインタラクション会話のメンバーではありません。

    データタイプ：文字列

    cURL 要求

    次の例は、指定されたインタラクション ID から指定されたエージェントのユーザー ID を削除する方法を示しています。

    curl "https://instance.servicenow.com/api/now/conversation/member/0b10223c57a313005baaaa65ef94f970/drop" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{\" interaction_id":\"27f675e3739713004a905ee515f6a7c3\"}" \ 
--user 'username':'password'

    応答には、インタラクションから指定されたエージェントの正常なドロップ操作が表示されます。active フィールドが false に設定され、ドロップ操作が成功したことを示すメッセージが表示されます。

    {
  "result": {
    "conversation_member": {
      "active": false,
      "memberType": "public_fulfiller",
      "conversation_id": "27f675e3739713004a905ee515f6a7c3"
    },
    "success": true,
    "message": "Request to drop agent processed successfully."
  }
}

    会話メンバー:PUT /now/conversation/member/{user_id}/update

    指定された会話のエージェントのメンバータイプを、オブザーバーまたはプライベート履行者タイプから公開履行者に更新します。

    このエンドポイントは、エージェントの現在のオブザーバーまたはプライベート履行者タイプを公開履行者タイプに更新する場合にのみ使用できます。このエンドポイントは、エージェントをオブザーバータイプまたはプライベートタイプに戻すことをサポートしていません。指定されたエージェントがすでに公開履行者ロールを保持している場合、応答は 500 ステータスコードを返します。

    次のシナリオは、 会話メンバーの PUT 更新 エンドポイントを使用してエージェントのメンバータイプを更新する方法の例です。
    1. スーパーバイザーは、エージェントが支援を求めている進行中の会話を開き、観察します。
    2. スーパーバイザーは、ヘルプを提供するために会話に参加することを決定し、UI の [会話に参加] ボタンをクリックします。会話への参加要求がサードパーティサーバーに送信されます。
    3. サードパーティサーバーは会話への参加要求を処理し、 会話メンバーの PUT 更新 エンドポイントを呼び出して、スーパーバイザーのメンバータイプをオブザーバーからパブリック履行者に更新します。
    4. エージェントのクライアント UI に、更新された会話のステータスが反映されます。

    URL 形式

    バージョニングされた URL: /api/now/{api_version}/conversation/member/{user_id}/update

    デフォルト URL: /api/now/conversation/member/{user_id}/update

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

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

    データタイプ：文字列
    user_id 会話で新しいメンバータイプで更新するエージェントのSys_id。

    データタイプ：文字列

    テーブル： ユーザー [sys_user]
    表 : 8. クエリパラメーター
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    interaction_id 必須。エージェントメンバータイプを更新する会話レコードのSys_id。

    データタイプ：文字列

    テーブル:インタラクション [interaction]
    member_type 必須。特定の会話でエージェントを更新するメンバーのタイプ。

    有効な値:public_fulfiller

    データタイプ：文字列

    テーブル:会話メンバー [sys_cs_conversation_member]、フィールド:メンバータイプ

    ヘッダー

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

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

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

    ステータスコード

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

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 会話メンバーの操作の処理中にエラーが発生しました。
    たとえば、次のようになります。
    • 指定されたインタラクションの会話が見つかりません。
    • ユーザーは、提供されたインタラクション会話のメンバーではありません。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    403 禁止されました。ユーザーには、指定されたレコードへのアクセス権がありません。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

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

    名前 説明
    conversation_member 更新要求が処理された後のエージェントメンバーのステータスに関する情報を含むオブジェクト。

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

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    conversation_member.active 現在のユーザーが会話に存在するかどうかを示すフラグ。
    可能な値：
    • true:エージェントは会話でアクティブです。
    • false:エージェントは会話から削除され、チャットのアクティブな参加者ではなくなります。

    データタイプ：ブーリアン
    conversation_member.memberType メンバーエージェントのタイプ。
    可能な値：
    • public_fulfiller:エージェントは、指定された会話で他のエージェントや要求者と公開でチャットできます。
    • 観測者:マネージャーロールを持つユーザーのみが使用できます。会話に参加せずに会話の内容を表示する権限を付与します。
    • private_fulfiller:エージェントは、エージェント間のプライベートチャットに参加して、アクティブな会話について話し合うことができます。

    データタイプ：文字列

    テーブル:会話メンバー [sys_cs_conversation_member]
    conversation_member.conversation_id エージェントが更新された会話レコードのSys_id。

    データタイプ：文字列

    テーブル:インタラクション [interaction]
    正常終了 更新プロセスが成功したかどうかを示すフラグ。
    有効な値：
    • true:エージェントが正常に更新されました。
    • false:エージェントの更新に失敗しました。

    データタイプ：ブーリアン
    メッセージ アサインの成功または例外を確認する応答メッセージ。

    成功メッセージ: エージェントメンバータイプの更新要求が正常に処理されました。

    考えられる例外:
    • 無効な要求。入力不足:エージェントsys_idまたはインタラクションsys_idが要求に指定されていません。
    • 指定されたインタラクションはサードパーティインタラクションではありません。要求はサードパーティインタラクションに対してのみ機能し、指定されたインタラクションはサードパーティインタラクションではありません。
    • 無効な要求。メンバータイプは [許可されたメンバータイプ] のいずれかである必要があります:要求で指定されたメンバータイプは、更新が許可されたタイプのいずれでもありません。
    • 対応するインタラクションの会話が見つかりませんでした:指定されたインタラクションsys_idに対応する会話レコードが見つかりません。
    • 無効な要求。ユーザーは指定されたインタラクションのメンバーではありません:指定されたエージェントsys_idは、指定されたインタラクション会話のメンバーではありません。

    データタイプ：文字列

    cURL 要求

    次のリクエストは、特定の会話でエージェントユーザーを公開履行者ロールに更新する方法を示しています。

    curl "https://instance.servicenow.com/api/now/conversation/member/{user_id}/update" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{ 
 \"interaction_id"":\"< interaction_sys_id" >\", 
 \"member_type\":\"public_fulfiller\" 
}" \ 
--user 'username':'password'

    応答は、パブリック履行者ロールへの正常な更新に関する情報を返します。memberType は更新されますが、アクティブなフィールドは true のままです。これは、エージェントのタイプが変更されたが、会話ではまだアクティブであることを示します。

    {
  "result": {
    "conversation_member": {
      "active": true,
      "memberType": "public_fulfiller",
      "conversation_id": " <conversation_sys_id>"
    },
    "success": true,
    "message": "Request to update agent member type processed successfully."
  }
}