AWA 受信ボックスアクション API

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間:16分
  • AWA 受信ボックスアクション API は、エージェントに代わって作業アイテムを承認または却下するためのエンドポイントを提供します。この API は、却下された作業アイテムの却下理由も取得します。

    この API には、 高度な作業アサイン (com.glide.awa) プラグインと awa_integration_user ロールが必要です。詳細については、「 高度なワークアサインメント」を参照してください。

    AWA 受信ボックスアクション:GET /awa/inbox/actions/reject_reasons/{channel_id}

    指定されたサービスチャネルの作業アイテム却下理由を取得します。

    URL 形式

    バージョニングされた URL: /api/now/awa/inbox/actions/reject_reasons/{channel_id}

    デフォルト URL: /api/now/{api_version}/awa/inbox/actions/reject_reasons/{channel_id}

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

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

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

    データタイプ:文字列

    channel_id サービスチャネルのSys_id。

    データタイプ:文字列

    テーブル:サービスチャネル [awa_service_channel]

    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

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

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

    デフォルト: application/json

    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    401 権限がありません。ユーザー認証情報が正しくないか、渡されていません。
    403 禁止されました。
    考えられる理由:
    • ユーザーにawa_integration_userロールがありません。
    • glide.awa.enabled プロパティの値が true ではありません。高度なワークアサインメント (com.glide.awa) プラグインがインストールされている場合、このプロパティはシステムのプロパティ [sys_property] テーブルにリストされます。詳細については、「 高度なワークアサインメントとともにインストールされるコンポーネント」を参照してください。
    404 レコードが見つかりません。指定されたチャネル ID が有効ではありません。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

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

    名前 説明
    display_value 却下理由 [awa_reject_reason] テーブルの [理由] フィールドの表示値。

    データタイプ:文字列

    order 却下理由をエージェントの受信ボックスに表示する順序。

    データタイプ:数値

    value データベースに格納されている [却下理由] フィールドの値。

    データタイプ:文字列

    Sys_id このサービスチャネルの却下理由のSys_id。

    データタイプ:文字列

    テーブル:却下理由 [awa_reject_reason]

    次の例は、チャットサービスチャネルの却下理由を取得する方法を示しています。

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject_reasons/27f675e3739713004a905ee515f6a7c3" \
    --request GET \
    --header "Accept:application/json" \
    --user 'username':'password'

    却下されたタスクと却下の理由を表示する応答本文。

    {
      "result": [
        {
          "order": 2,
          "value": "Not my expertise",
          "display_value": "Not my expertise",
          "sys_id": "31e3fa29b38023002e7b6e5f26a8dc17"
        },
        {
          "order": 1,
          "value": "Busy",
          "display_value": "Busy",
          "sys_id": "4e93fa29b38023002e7b6e5f26a8dc20"
        }
      ]
    }

    AWA 受信ボックスアクション:POST /awa/inbox/actions/accept

    エージェントに代わって [ 保留中の承認 ] ステータスの作業アイテムを受け入れます。

    URL 形式

    バージョニングされた URL: /api/now/{api_version}/awa/inbox/actions/accept

    デフォルト URL: /api/now/awa/inbox/actions/accept

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

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

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

    データタイプ:文字列

    表 : 8. クエリパラメーター
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    agent_id リストされたエージェントのSys_id。

    データタイプ:文字列

    テーブル: ユーザー [sys_user]

    work_item_id 作業アイテムのSys_id。
    作業アイテムは次の基準を満たしている必要があります。
    • 作業アイテムは指定されたエージェントにアサインされている必要があります。
    • 作業アイテムは [ 承認保留中] ステータスである必要があります。

    データタイプ:文字列

    テーブル:AWA 作業アイテム [awa_work_item]

    ヘッダー

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

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

    デフォルト: application/json

    表 : 11. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 無効な要求。
    考えられる理由:
    • エージェント ID がありません。
    • 作業アイテム ID がありません。
    • 作業アイテムが別のエージェントにアサインされています。
    • 作業アイテムが保留中の承認ステータスではありません。
    401 権限がありません。ユーザー認証情報が正しくないか、渡されていません。
    403 禁止されました。
    考えられる理由:
    • ユーザーにawa_integration_userロールがありません。
    • glide.awa.enabled プロパティの値が true ではありません。高度なワークアサインメント (com.glide.awa) プラグインがインストールされている場合、このプロパティはシステムのプロパティ [sys_property] テーブルにリストされます。詳細については、「 高度なワークアサインメントとともにインストールされるコンポーネント」を参照してください。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

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

    名前 説明
    documentTable この作業アイテムにアサインされたドキュメントをリストするテーブルの名前。

    データタイプ:文字列

    documentSysId タスクにアサインされたドキュメントレコードのSys_id。

    データタイプ:文字列

    テーブル: documentTable フィールドで識別されたテーブル内。

    エラー 要求プロセス中に発生したエラーを説明する詳細。

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

    "error": {
      "detail": "String",
      "message": "String"
    }
    error.detail 要求プロセス中に発生したエラーの詳細。
    可能な値:
    • エージェント ID がありません: agent_id が要求本文に指定されていません。
    • 作業アイテム ID がありません: work_item_id が要求本文に指定されていません。
    • 作業アイテムは別のエージェントにアサインされています:指定された作業アイテムは、指定されたエージェントにアサインされていません。
    • 作業アイテム ID が正しくありません:要求本文に指定された作業アイテムが不正確であるか、存在しません。
    • 作業アイテムが保留中の承認ステータスではありません:要求本文で指定された作業アイテムのステータスが [保留中の承認] 以外の状態です。

    データタイプ:文字列

    error.message 要求プロセス中に発生したエラーのメッセージ。 説明は error.detail プロパティに入力されます。

    データタイプ:文字列

    status 失敗した要求のステータス。このプロパティは、エラーがある場合にのみ応答に含まれます。

    有効な値: 失敗

    データタイプ:文字列

    cURL 要求

    次の例は、選択したエージェントの作業アイテムのステータスを [ 受入待ち ] から [ 受入済み] に変更する方法を示しています。

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/accept" \
    --request POST \
    --header "Accept:application/json" \
    --header "Content-Type:application/json" \
    --data "{
     \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
     \"work_item_id\":\"fd69abfc878b01101ae365b83cbb35fe\"
    }" \
    --user 'username':'password'

    応答本文には、作業アイテムに関連するドキュメントのsys_idとテーブルが一覧表示されます。

    {
      "result": {
        "documentSysId": "57af7aec73d423002728660c4cf6a71c",
        "documentTable": "incident"
      }
    }

    AWA 受信ボックスアクション:POST /awa/inbox/actions/reject

    エージェントに代わって、 保留中の承認 ステータスの作業アイテムを却下します。成功すると、指定された作業アイテムの [アサイン先 ] フィールドが空で、[ 却下] フィールドの値が true になります。

    URL 形式

    バージョニングされた URL: /api/now/{api_version}/awa/inbox/actions/reject

    デフォルト URL: /api/now/awa/inbox/actions/reject

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

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

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

    データタイプ:文字列

    表 : 14. クエリパラメーター
    名前 説明
    なし
    表 : 15. 要求本文パラメーター (XML または JSON)
    名前 説明
    agent_id リストされたエージェントのSys_id。

    データタイプ:文字列

    テーブル: ユーザー [sys_user]

    reject_reason_id このサービスチャネルの却下理由のSys_id。

    データタイプ:文字列

    テーブル:却下理由 [awa_reject_reason]

    work_item_id 作業アイテムのSys_id。
    作業アイテムは次の基準を満たしている必要があります。
    • 作業アイテムは指定されたエージェントにアサインされている必要があります。
    • 作業アイテムは [ 承認保留中] ステータスである必要があります。

    データタイプ:文字列

    テーブル:AWA 作業アイテム [awa_work_item]

    ヘッダー

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

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

    デフォルト: application/json

    表 : 17. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 18. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 無効な要求。
    考えられる理由:
    • エージェント ID がありません。
    • 作業アイテム ID がありません。
    • 却下理由 ID がありません。
    • 作業アイテムが別のエージェントにアサインされています。
    • 作業アイテムが保留中の承認ステータスではありません。
    401 権限がありません。ユーザー認証情報が正しくないか、渡されていません。
    403 禁止されました。
    考えられる理由:
    • ユーザーにawa_integration_userロールがありません。
    • glide.awa.enabled プロパティの値が true ではありません。高度なワークアサインメント (com.glide.awa) プラグインがインストールされている場合、このプロパティはシステムのプロパティ [sys_property] テーブルにリストされます。詳細については、「 高度なワークアサインメントとともにインストールされるコンポーネント」を参照してください。
    404 見つかりません。要求されたアイテムが見つかりませんでした。
    考えられる理由:
    • エージェント ID が正しくない:指定されたユーザーのレコードがありません。
    • 却下理由 ID が正しくない:指定された却下理由のレコードがありません。
    • 作業アイテム ID が正しくない:指定された作業アイテムのレコードがありません。
    500 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

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

    名前 説明
    agent_id リストされたエージェントのSys_id。

    データタイプ:文字列

    テーブル: ユーザー [sys_user]

    エラー 要求プロセス中に発生したエラーを説明する詳細。

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

    "error": {
      "detail": "String",
      "message": "String"
    }
    error.detail 要求プロセス中に発生したエラーの詳細。
    可能な値:
    • エージェント ID がありません : agent_id が要求本文に指定されていません。
    • 却下理由アイテム ID がありませんreject_reason_id が要求本文に指定されていません。
    • 作業アイテム ID がありません: work_item_id が要求本文に指定されていません。
    • awa_reject_reasonのレコードがありません:<reason_sys_id> :要求本文で指定された reject_reason_id に、却下理由 [awa_reject_reason] テーブルに一致するレコードがありません。
    • awa_work_itemのレコードがありません:<work_item_sys_id> :要求本文で指定された work_item_id に、AWA 作業アイテム [awa_work_item] テーブルに一致するレコードがありません。
    • sys_userのレコードがありません:<agent_sys_id> :要求本文で指定された agent_id に、ユーザー [sys_user] テーブルに一致するレコードがありません。
    • 作業アイテムが保留中の承認ステータスではありません:要求本文で指定された作業アイテムのステータスが [保留中の承認] 以外の状態です。

    データタイプ:文字列

    error.message 要求プロセス中に発生したエラーのメッセージ。 説明は error.detail プロパティに入力されます。

    データタイプ:文字列

    status 失敗した要求のステータス。このプロパティは、エラーがある場合にのみ応答に含まれます。

    有効な値: 失敗

    データタイプ:文字列

    reject_reason_id このサービスチャネルの却下理由のSys_id。

    データタイプ:文字列

    テーブル:却下理由 [awa_reject_reason]

    work_item_id 作業アイテムのSys_id。

    データタイプ:文字列

    次の例は、「専門知識がありません」という理由でアサインされた作業アイテムを却下する方法を示しています。

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject" \
    --request POST \
    --header "Accept:application/json" \
    --header "Content-Type:application/json" \
    --data "{
        \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
        \"work_item_id\":\"3ed5df4d87cf01101ae365b83cbb35af\",
        \"reject_reason_id\":\"31e3fa29b38023002e7b6e5f26a8dc17\"
    }" \
    --user 'username':'password'

    成功した出力には、要求本文で指定されたものと同じ作業アイテム、却下理由、およびユーザー ID が表示されます。AWA 作業アイテム [awa_work_item] テーブルの指定された作業アイテムの [ アサイン先 ] フィールドは空で、[ 却下] フィールドの値は true です。

    {
      "result": {
        "work_item_id": "3ed5df4d87cf01101ae365b83cbb35af",
        "reject_reason_id": "31e3fa29b38023002e7b6e5f26a8dc17",
        "agent_id": "46c9e158a9fe198101d44d0d22cb640d"
      }
    }