Task Reservation Resource
Reservationインスタンスサブリソース
TaskRouter creates a Reservation subresource whenever a Task is reserved for a Worker. TaskRouter will provide the details of this Reservation Instance subresource in the Assignment Callback HTTP request it makes to your application server.
Reservationを処理する方法は複数あります。
- 割り当て命令を含む、割り当てコールバックへのレスポンスを返します。
- REST API を呼び出して、Reservationの処理方法を指定します。
- Worker JS SDK を使用してReservationを取得できるかどうかをWorkerに判断させます。
この後は、REST API の詳細について説明します。
重要：Workflowで構成されている TaskReservationTimeout の時間内にReservationの処理方法をレスポンスで指定しないと、Reservationはタイムアウトして、他のWorkerがそのTaskを処理できるようになります。
アクション
Reservationを取得する
リソースURI
GET /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}/Reservations/{ReservationSid}
{ReservationSid} で識別される単一の Reservation リソースを返します。
例
リソースのプロパティ
予約は、以下のプロパティを持ちます。
| フィールド | 概要 |
|---|---|
| Sid | この予約のユニーク ID です。 |
| AccountSid | このTaskを所有するアカウントのIDです |
| WorkspaceSid | このTaskが属するWorkspaceのIDです。 |
| TaskSid | 予約されているTaskのIDです |
| WorkerSid | 予約されているWorkerのIDです。 |
| WorkerName | 予約されているWorkerの、人間が読みやすい形式の説明です。 |
| ReservationStatus | Reservationの現在のステータスです。取りうる値については、下記の表をご覧ください。 |
ReservationStatus の取りうる値：
| Status | 概要 |
|---|---|
| PENDING | このTaskにWorkerが予約されており、TaskRouterは予約応答の待機中です。 |
| accepted | ReservationはWorkerによって承諾されました。 |
| rejected | ReservationはWorkerによって拒否されました。 |
| Timeout | 応答を待っているReservationがタイムアウトしました。 この場合、TaskはQueueに残り、TaskRouterはこのTaskを資格を持つ次のWorkerに割り当てようとします。 |
Reservationを更新する
リソースURI
POST /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}/Reservations/{ReservationSid}
WorkerがReservationを受諾または却下したことを示すために、ReservationインスタンスリソースURIにHTTP POSTリクエストを発行します。
単純な受諾リクエストまたは拒否リクエストを送信できます。また、割り当てコールバックに応答するのと同じように、命令を発行することもできます。それぞれの方法で渡す必要があるパラメーターの詳細について、説明します。
Reservationを承諾する
Reservationの承諾は、WorkerはTaskに取り組むことになるが、開発者はTaskの詳細をWorkerに結びつけるために必要な作業を行う必要があるということです。 承諾は、Taskの承諾における必要最小限の選択肢と考えることができます。 音声通話のTaskについては、下記で説明されている他の手段が承諾よりも優先されます。
例
POSTパラメーター
| フィールド | 必須 | 概要 |
|---|---|---|
| ReservationStatus | はい | accepted. Specifying accepted means the Worker has received the Task and will process it. TaskRouter will no longer consider this task eligible for assignment, and no other Worker will receive this Task. (🏢 not PII ) |
POSTパラメーター
| フィールド | 必須 | 概要 |
|---|---|---|
| ReservationStatus | はい | rejected. Specifying rejected means the Worker has refused the assignment and TaskRouter will attempt to assign this Task to the next eligible Worker. (🏢 not PII ) |
| WorkerActivitySid | いいえ | If rejecting a reservation, change the worker that is tied to this reservation to the supplied activity. If not provided, the WorkerPreviousActivitySid on the Reservation will be used. (🏢 not PII ) |
Important: Tasks are automatically canceled after 10 rejections.
詳細については、「手動でReservationを受諾または拒否する」を参照してください。
Conference 命令
顧客とエージェントとの接続には、Conference命令が推奨されます。 コールセンターのシナリオのほとんどすべての場合において、dequeueやcallではなくこちらを使用してください。
カンファレンス指示は本来ご自身で行うことになる通話についての調整の多くを肩代わりします。 TaskRouter内のTaskによって表される通話に対しては、カンファレンス指示の発行は下記のことを意味しています:
- 指定されたWorkerの
contact_uriまたは入力されたtoフィールドのいずれかのWorkerに通話を発信する - 通話ステータスをモニターし、エージェントが通話に応答したか確認する
- エージェントの通話をTaskidで名前付けされたカンファレンスに接続する
- 上記が成功したかどうかモニターする
- 発信者をQueueから取り出し、カンファレンスに接続させる
- 上記すべての成功時に限りTaskを承諾済みとマークし、例外的なケース (発信者が上記の処理中に通話を切断した、など) を円滑に処理する。
TaskRouter内の通話におけるカンファレンス指示は、ネイティブ{"call_sid" : "<callsid>", "to" : "<E.164 to number>"} Task属性を追加しておくことが必要です。
例
POSTパラメーター
カンファレンス指示はConference Participants APIを使用します。 このAPI用のすべての有効な値をカンファレンス指示の一部として使用可能です。 これらのパラメーター名はここで再掲しません。 有効な値についてはリンク先のドキュメントを参照してください。
指定されたParticipant APIパラメーターは通話のWorkerレグに対して適用され、顧客側のレグには適用されないことに注意してください。 特に、endConferenceOnExit はWorkerレグのみに設定可能な点に注意してください。 顧客が通話を切断した際、エージェントの通話レグを破棄したい場合は、API経由でこれを行なってください。
| フィールド | 必須 | 概要 |
|---|---|---|
| Instruction | はい | Conference (🏢 not PII ) |
| To | いいえ | The contact URI of the Worker. A phone number or client ID. Required if the worker's attributes do not include a "contact_uri" property. (📇 PII ) |
| From | いいえ | The caller ID for the call to the worker. Note: This needs to be a verified Twilio number. If you need this to be the original callee number, please contact Support (📇 PII ) |
| postWorkActivitySid | いいえ | (Deprecated) The activity to move a worker to after executing a conference instruction. Not valid in multi-tasking workspaces. (🏢 not PII ) |
| Timeout | いいえ | The integer number of seconds that Twilio should allow the phone associated with "contact_uri" to ring before assuming there is no answer. Default is 60 seconds, the maximum is 999 seconds. Note, you could set this to a low value, such as 15, to hang up before reaching an answering machine or voicemail. (🏢 not PII ) |
| Participat APIで取りうる全パラメーター | いいえ | リンク先のドキュメントを参照してください |
注：contact_uri プロパティは、通話先を示すために WorkerAttributes に必要です。詳細については、こちらをご覧ください。
Dequeue命令
ほとんどの状況において、dequeueではなくConference命令の使用を推奨します
POSTパラメーター
| フィールド | 必須 | 概要 |
|---|---|---|
| Instruction | はい | Dequeue (🏢 not PII ) |
| DequeueTo | いいえ | The contact URI of the Worker. A phone number or client ID. Required if the worker's attributes do not include a "contact_uri" property. (📇 PII ) |
| DequeueFrom | はい | The caller ID for the call to the worker. Note: This needs to be a verified Twilio number. If you need this to be the original callee number, please contact Support (📇 PII ) |
| DequeuePostWorkActivitySid | いいえ | The activity to move a worker to after executing a dequeue instruction. (🏢 not PII ) |
| DequeueRecord | いいえ | The 'DequeueRecord' attribute lets you record both legs of a call. Set to "record-from-answer" to record the call from answer. Default to "do-not-record" which will not record the call. The RecordingUrl will be sent with DequeueStatusCallbackUrl. (🏢 not PII ) |
| DequeueTimeout | いいえ | The integer number of seconds that Twilio should allow the phone associated with "contact_uri" to ring before assuming there is no answer. Default is 60 seconds, the maximum is 999 seconds. Note, you could set this to a low value, such as 15, to hangup before reaching an answering machine or voicemail. (🏢 not PII ) |
| DequeueStatusCallbackUrl | いいえ | A URL that Twilio will send asynchronous webhook requests to on completed call event. **Note: TaskRouter sends "taskCallSid" as parameter with sid of the call that created the Task. This is very useful in the event a call to worker fails, where you could remove the original call from queue and send to voice mail or enqueue again with new workflow to route to different group of workers. (🏢 not PII ) |
| DequeueStatusCallbackEvent | いいえ | The call progress events that will be sent via webhooks on a worker's call. Available values are initiated, ringing, answered, and completed. If you want to receive multiple events, please provide multiple DequeueStatusCallbackEvent values as individual parameters in the POST request. If no event is specified, defaults to completed. For example to receive webhooks on answered and completed events pass "DequeueStatusCallbackEvent=answered&DequeueStatusCallbackEvent=completed". Please click here for more details. (🏢 not PII ) |
注：contact_uri プロパティは、通話先を示すために WorkerAttributes に必要です。詳細については、こちらをご覧ください。
詳細については、Dequeue命令を発行するをご覧ください。
POSTパラメーター
| フィールド | 必須 | 概要 |
|---|---|---|
| Instruction | はい | Call (🏢 not PII ) |
| CallTo | いいえ | The contact URI of the Worker. A phone number or client ID. Required if the worker's attributes do not include a "contact_uri" property. (📇 PII ) |
| CallFrom | はい | The caller ID to use when placing the outbound call (📇 PII ) |
| CallUrl | はい | A valid TwiML URI that is executed on the answering Worker's leg. (🏢 not PII ) |
| CallAccept | いいえ | If set to "true", the reservation will be accepted. Otherwise, a separate call to the REST API is responsible for moving the state to accept or reject. (🏢 not PII ) |
| CallRecord | いいえ | The 'CallRecord' attribute lets you record both legs of a call. Set to "record-from-answer" to record the call from answer. Default to "do-not-record" which will not record the call. The RecordingUrl will be sent with DequeueStatusCallbackUrl. (🏢 not PII ) |
| CallTimeout | いいえ | The integer number of seconds that Twilio should allow the phone associated with "contact_uri" to ring before assuming there is no answer. Default is 60 seconds, the maximum is 999 seconds. Note, you could set this to a low value, such as 15, to hangup before reaching an answering machine or voicemail. (🏢 not PII ) |
| CallStatusCallbackUrl | いいえ | A URL that Twilio will send asynchronous webhook requests to on completed call event. **Note: TaskRouter sends "taskCallSid" as parameter with sid of the call that created the Task. This is very useful in the event a call to worker fails, where you could remove the original call from queue and send to voice mail or enqueue again with new workflow to route to different group of workers. (🏢 not PII ) |
注：contact_uri プロパティは、通話先を示すために WorkerAttributes に必要です。詳細については、こちらをご覧ください。
詳細については、通話命令を発行するをご覧ください。
POSTパラメーター
| フィールド | 必須 | 概要 |
|---|---|---|
| Instruction | はい | Redirect (🏢 not PII ) |
| RedirectCallSid | はい | The Twilio call sid of the call which was parked in the queue(via enqueue for example). (🏢 not PII ) |
| RedirectUrl | はい | A valid TwiML URI to redirect the call to. (🏢 not PII ) |
| RedirectAccept | いいえ | Boolean. If true, the reservation will be accepted, otherwise, it is your application's responsibility to accept or reject the task at a later point. Defaults to false. (🏢 not PII ) |
詳細については、通話を新しいTwiMLドキュメントにリダイレクトするを参照してください。
Reservationリストリソース
リソースURI
GET /v1/Workspaces/{WorkspaceSid}/Tasks/{TaskSid}/Reservations
{TaskSid} で識別されるTaskを待機しているReservationのすべての一覧の表現を返します。
例
リストフィルター
| フィールド | 概要 |
|---|---|
| WorkerSid | 指定されているWorkerに対するTaskのReservationの一覧を返します。 |
| ReservationStatus | 指定された ReservationStatus を持つTaskのReservationの一覧を返します |
ヘルプが必要ですか？
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。