AWA オファー作業 API
AWA オファー作業 API は、作業アイテムをエージェントにアサインまたは転送するためのエンドポイントを提供します。
この API は、ルーティングとアサインの決定が外部 CCAAS システムで行われるサービスとしての連絡先センター (CCAAS) 統合での使用を目的としています。この API を使用すると、作業アイテムを承認するための通知として、 受信ボックスカード を ServiceNow エージェントワークスペース 内のエージェントに表示できます。
この API には 高度な作業アサイン (com.glide.awa) プラグインが必要です。この API を呼び出すには、awa_manager ロールまたは awa_integration_user ロールのいずれかが必要です。
AWAの詳細については、「高度なワークアサインメント」を参照してください。
AWA エージェントコンサルト APIを使用して、エージェントコンサルト作業アイテムを処理します。
AWA オファー作業:POST /now/awa/documents/{document_table}/{document_sys_id}/offer
作業アイテムをエージェントにアサインまたは転送します。
作業アイテムは、 AWA エージェントによって最初から最後まで処理される 1 つの作業です。作業アイテムは、インタラクションやタスクなどのドキュメントに基づいて作成されます。
この API を使用して作業アイテムを受信または転送するすべてのエージェントには、awa_agentロールとawa_external_userロールが必要です。
URL 形式
バージョニングされた URL: /api/now/{api_version}/awa/documents/{document_table}/{document_sys_id}/offer
デフォルト URL: /api/now/awa/documents/{document_table}/{document_sys_id}/offer
サポートされている要求パラメーター
| 名前 | 説明 |
|---|---|
| api_version | オプション。アクセスするエンドポイントのバージョン。たとえば、 v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ：文字列 |
| document_table | インタラクション [interaction] テーブルやタスク [task] テーブルなど、ドキュメントに関連付けられたテーブルの名前。 データタイプ：文字列 |
| document_sys_id | エージェントまたはキューにルーティングするドキュメントのSys_id。 データタイプ：文字列 |
| 名前 | 説明 |
|---|---|
| なし |
| 名前 | 説明 |
|---|---|
| アサイン | 新しいアサインに必要です。アサインに関する情報を含むオブジェクト。 データタイプ: オブジェクト |
| assignment.after_timeout_presence | timeoutパラメーターの有効期限が切れた場合にエージェントが切り替える在席状況のSys_id。 timeout パラメーターが渡されない場合、このパラメーターは無視されます。 在席状況の詳細については、「 Configure agent presence states」を参照してください。 データタイプ：文字列 デフォルト:空の文字列 (エージェントの在席状況は変更されません)。 テーブル:AWA 在席状況 [awa_presence_state] |
| assignment.agent_sys_id | 新しいアサインに必要です。作業アイテムを受信できるエージェントのSys_id。エージェントには、awa_agentロールとawa_external_userロールが必要です。 エージェントが対応可能かどうかを判断する方法については、「 エージェントの受信ボックスの制御」を参照してください。 データタイプ：文字列 テーブル： ユーザー [sys_user] |
| assignment.allowed_to_decline | エージェントに作業アイテムの却下が許可されているかどうかを示すフラグ。このパラメーターが true の場合、受信ボックスカードの受信ボックスカードには [承認 ] ボタンと [ 却下 ] ボタンの両方が表示されます。有効な値：
データタイプ：ブーリアン デフォルト：true |
| assignment.display_option | 作業アイテムが自動的にアサインされるときのカードとタブの表示オプション。 このパラメーターは、 enable_auto_assign が true の場合にのみ有効です。 有効な値：
データタイプ：文字列 デフォルト値:card_only |
| assignment.enable_auto_assign | 作業アイテムを自動的に受け入れるかどうか、またはエージェントが作業アイテムを手動で受け入れまたは却下できるようにするかどうかを示すフラグ。 有効な値：
データタイプ：ブーリアン デフォルト値：false |
| assignment.offered_on | 作業アイテムの提供時間。オファー時間は、エージェントが受信ボックスの作業アイテムを受け入れるために残っている時間を計算するために使用されます。これは、API 要求が処理された時間と、サードパーティルーティングシステムが API 要求を呼び出す時間の間の不一致を考慮するのに役立ちます。このパラメーターを使用すると、このエンドポイントを呼び出す外部システムは、作業アイテムの外部システムの内部追跡との同期を維持するように作業アイテムのオファー時間を構成できます。 たとえば、作業アイテムが 11:30:30 に提供され、タイムアウトが 30 秒で、現在の時刻が 11:30:45 の場合、カウントダウンタイマーには (残り 15 秒と同様) 00:15 と表示されます。 この値は、作業アイテムの [offered_on] フィールドに格納されます。 timeoutパラメーターが渡されない場合、このパラメーターは無視されます。 データタイプ：文字列 形式:UTC タイムスタンプ (yyyy-MM-dd'T'HH:mm:ss.SSS) |
| assignment.timeout | エージェントがワークアサインメントを受け入れるのを待機して、作業アイテムをエージェントの受信ボックスに保持する時間。 データタイプ：数値 単位：秒 デフォルト:空の文字列 (時間制限なし)。 |
| external_segment_id | エージェントに提供されるコールセグメントの CCAAS システムからの外部識別子。 データタイプ：文字列 |
| queue_id | 新しいアサインに必要です。外部システム内のキューレコードまたはキュー識別子のSys_id。 外部システムからのqueue_idを使用する場合は、awa_queueレコードのプロバイダーキュー ID (external_id) フィールドにマッピングする必要があります。 データタイプ：文字列 テーブル:キュー [awa_queue] |
| 転送 | 転送の割り当てには必要です。転送に関する情報を含むオブジェクト。 このパラメーターに値が指定されている場合、割り当ては転送割り当てと見なされます。 データタイプ: オブジェクト |
| transfer.source_queue_id | 転送の割り当てには必要です。 転送が開始されるソースキュー。外部システム内のキューレコードまたはキュー識別子のSys_id。 外部システムからのqueue_idを使用する場合は、awa_queueレコードのプロバイダーキュー ID (external_id) フィールドにマッピングする必要があります。 このパラメーターは、アクティブな作業アイテムが見つからない場合に転送を開始する前に作業アイテムを作成するために使用されます。元のインタラクションがルーティングなしで作成された場合 (発信コールなど) に転送を実行できます。 データタイプ：文字列 テーブル:キュー [awa_queue] |
| transfer.target_id | 転送の割り当てには必要です。アサインの転送先のエージェントまたはキューレコードのSys_id。
データタイプ：文字列 |
| transfer.target_type | 転送の割り当てには必要です。アサインの転送先のレコードのタイプ。 有効な値：
データタイプ：文字列 |
| transfer.transfer_type | 転送の割り当てには必要です。転送のタイプ。 有効な値：
データタイプ：文字列 |
ヘッダー
次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。
| ヘッダー | 説明 |
|---|---|
| 承認 | 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。 デフォルト： application/json |
| Content-Type | 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。 デフォルト： application/json |
| ヘッダー | 説明 |
|---|---|
| なし |
ステータスコード
この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。
| ステータスコード | 説明 |
|---|---|
| 200 | 成功。要求が正常に処理されました。 |
| 401 | 権限がありません。ユーザー認証情報が正しくないか、渡されていません。 |
| 404 | 見つかりません。要求されたアイテムが見つかりませんでした。 |
| 409 | 競合。指定されたドキュメントの作業アイテムまたはエージェントsys_idのエラーのため、要求を処理できませんでした。 |
| 500 | 内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。 |
応答本文のパラメーター (JSON または XML)
| 名前 | 説明 |
|---|---|
| メッセージ | アサインの成功または失敗に関する情報を含む応答メッセージ。 可能な値：
|
| 成功 | 割り当てが成功したかどうかを示すフラグ。 可能な値：
データタイプ：ブーリアン |
| work_item | 作成または更新された作業アイテムに関する詳細。 データタイプ: オブジェクト |
| work_item.display_name | ドキュメントレコードの表示名。 データタイプ：文字列 |
| work_item.document_id | ドキュメントレコードのSys_id。 データタイプ：文字列 |
| work_item.document_table | ドキュメントに関連付けられたテーブルの名前。 データタイプ：文字列 |
| work_item.queue | 外部システム内のキューレコードまたはキュー識別子のSys_id。 データタイプ：文字列 テーブル:キュー [awa_queue] |
| work_item.sys_id | 作業アイテムのSys_id。 データタイプ：文字列 テーブル:作業アイテム [awa_work_item] |
cURL 要求
この例では、作業アイテムをエージェントにアサインする方法を示します。
curl "https://instance.servicenow.com/api/now/awa/documents/interaction/59616aba87bd5210be070d48dabb35e6/offer" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data '{
"external_segment_id": "segment_59616aba87bd5210be070d48dabb35e6",
"queue_id": "92f8942787851210be070d48dabb35fb",
"assignment": {
"agent_sys_id": "0d584509c323120095ccd02422d3ae5b",
"allowed_to_decline": "true",
"enable_auto_assign": "false",
"timeout": 30,
"offered_on":"2024-04-03T23:09:31.000"
}
}'
--user 'username':'password'応答は、作業アイテムがエージェントに正常にアサインされたことを示しています。作業アイテム [awa_work_item] レコードの [アサイン先] フィールドで結果を確認できます。
{
"result": {
"work_item": {
"display_name": "Interaction: IMS0000221",
"sys_id": "bfa3a27e87bd5210be070d48dabb3588",
"document_id": "59616aba87bd5210be070d48dabb35e6",
"document_table": "interaction",
"queue": "92f8942787851210be070d48dabb35fb"
},
"success": true,
"message": "Manual assignment successfully requested."
}
}