AWA オファーワーク API
AWA オファー作業 API は、作業アイテムをエージェントにアサインまたは転送するためのエンドポイントを提供します。
この API は、ルーティングとアサインの決定が外部 CCAAS システムで行われる Contact Center as a Service (CCAAS) 統合で使用することを目的としています。この API を使用すると、 受信ボックスカードを 作業アイテムを承認するための通知として ServiceNow エージェントワークスペース 内のエージェントに表示できます。
この API には 高度な作業アサイン (com.glide.awa) プラグインが必要です。この API を呼び出すには、awa_manager ロールまたは awa_integration_user ロールのいずれかが必要です。
AWAの詳細については、「高度なワークアサインメント」を参照してください。
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 | 新しい割り当てに必要です。アサインに関する情報を含むオブジェクト。 データタイプ: オブジェクト |
| 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 の場合、カウントダウンタイマーには 00:15 と表示されます (残り 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."
}
}