メニュー

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

REST API: Reservations

Reservationインスタンスサブリソース

WorkerにTaskを予約するたびに、TaskRouterはReservationサブリソースを作成します。 TaskRouterは、アプリケーションサーバーに発行する割り当てコールバックHTTPリクエストでこのReservationインスタンスサブリソースの詳細を提供します。

Reservationを処理する方法は複数あります。

  1. 割り当て命令を含む、割り当てコールバックへのレスポンスを返します。
  2. REST API を呼び出して、Reservationの処理方法を指定します。
  3. 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リクエストを発行します。

        単純な受諾リクエストまたは拒否リクエストを送信できます。また、割り当てコールバックに応答するのと同じように、命令を発行することもできます。それぞれの方法で渡す必要があるパラメーターの詳細について、説明します。

        1. Reservationを承諾する
        2. Reservationを拒否する
        3. Issue a Conference Instruction
        4. Dequeue命令を発行する
        5. 通話命令を発行する
        6. アクティブな音声通話をTwiMLドキュメントにリダイレクトする

        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内の通話におけるカンファレンス指示は、ネイティブTaskRouterインテグレーションを使用すればそのままの状態で機能することに留意してください。 音声通話用のTaskを手動で作成している場合は、カンファレンス指示を使用するには最低限、{"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の一覧を返します
                                                  Rate this page:

                                                  ヘルプが必要ですか?

                                                  誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。