メニュー

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?

Queueing Twilio calls with TaskRouter

概要

TaskRouterとTwiMLを使用して通話ルーティングを実装してみましょう。 概要については、クイックスタートをご覧ください

TwilioのProgrammable Voiceの <Queue> 名詞は、通話を保留して、指定された先入れ先出しQueueに入れる、単純なメカニズムを提供します。 <Queue> をTaskRouterと組み合わせることによって、豊富な機能を備えたルーティングモデルで <Queue> を拡張できます。 また、TaskRouterのエージェント可用性モデルおよびTaskのReservation / 承諾フローにより、使用可能になったエージェントに自動的に該当する作業を割り当てることができます。

動作の仕組み

TwiML 音声通話アプリケーションの詳細については、Twilio の TwiML API をご覧ください。

TaskRouterをTwiML通話と組み合わせる場合、次の基本フローに従います。

  1. Twilio 音声通話の着信/発信通話により、アプリケーションサーバーへの webhook が生成されます。
  2. アプリケーションサーバーは、<Enqueue> を含むTwiMLドキュメントを生成し、その際、TaskRouterの WorkflowSidが通話ルーティングを制御する必要があることを示す属性および通話に設定する任意のTask属性を指定します。
  3. 通話自体は保留されます。 TaskRouterはWorkflowを実行して、通話を処理する資格を持つWorkerを探します。
  4. 発信者がWorkerに割り当てられる前に通話を切った場合、Taskは自動的にキャンセルされます。
  5. 通話を処理するWorkerが見つかったら、TaskRouterはそのWorkerをReservationして、アプリケーションへのWebhookを生成します。
  6. アプリケーションはレスポンスで選択されたWorkerに通話をブリッジする方法を指定し、オプションで通話を処理した後のWorkerを割り当てるActivity(例:「Wrapping up」)を指定します。
  7. 通話がWorkerにブリッジされると、Taskは 'accepted' とマークされます。
  8. 通話が終了すると、Workerは割り当て命令レスポンスで指定されたActivityに移行します。

<Enqueue> でTaskRouterを使う通話のルーティング

TaskRouterを使って通話を自動的に割り当てる TwiML ドキュメントの例を次に示します。

例 #1: TaskRouterでQueueに入れる

TaskRouterでEnqueueを使用するには、TwiMLドキュメントで <Enqueue> 文を生成するときに、WorkflowSidを指定します。 要素のボディーのQueue名の指定は省略します。 次のTwiMLドキュメントの例では、指定されたWorkflowでTaskを作成し、発信者に対して既定の保留音を再生します。

        
        
        
        

        このWorkflowでTaskが生成されて、通話の標準のパラメーターが属性(call_sid、account_sid、to、fromなど)として設定されます。

        例 #2:Task を使って通話にデータを添付する

        オプションで <Task> 名詞要素を取り込み、Task に属性を追加することもできます。<Task> には、Task の属性の本文として有効な JSON オブジェクトがなければなりません。例 :

              
              
              
              

              例 #3:Task を使って優先度とタイムアウトを通話に添付する

              オプションで、Taskに優先度やタイムアウトを指定することができます。この例では、<Task> 名詞要素のプロパティーとしてTaskに動的な優先度とタイムアウトを指定します。優先度とタイムアウトはどちらも有効な整数でなければなりません。例 :

                    
                    
                    
                    

                    例 #4:カスタムな保留音および通話後の処理を指定する

                    この例では、waitUrl プロパティーを使って発信者に保留音を提供するとともに、action プロパティーを使って、Workerと発信者の接続切断後に実行される通話後の調査アプリケーションを指定します。 アクションプロパティーの詳細については、ここをご覧ください。

                          
                          
                          
                          

                          注:TaskAttributes は 2015 年 8 月 15 日時点でレガシーですが、Task の代わりに動詞としてまだサポートされています。

                          音声通話に対するTaskRouterの割り当てコールバックの処理: 通話をWorkerにブリッジする

                          通話を処理するWorkerがReservationされると、アプリケーションは、<Enqueue> 文で指定した WorkflowSid に設定されている AssignmentCallbackURL で、HTTP リクエストを受信します。 アプリケーションは、次のいずれかの例を使用して応答して、実際に通話をWorkerにブリッジする方法を制御します。 割り当てコールバックの処理の他のオプションについては、こちらをご覧ください。

                          自動的に通話をWorkerにブリッジする

                          「dequeue」命令は、通話を保留から外して、選択されたWorkerにブリッジします。 アプリケーションは、「dequeue」命令を使用するために、次のフィールドを含むJSONドキュメントを使用して割り当てコールバックリクエストに応答する必要があります。

                          {
                            "instruction": "dequeue",
                            "to": "{the Worker's phone number, sip uri, or client uri. Required.}"
                            "from": "{the caller ID that you want to send to the Worker. Required.}"
                            "post_work_activity_sid": "{the ActivitySid that should be assigned to the Worker after the call ends. Optional.}"
                          }
                          

                          これらのフィールドの詳細は、次のとおりです。

                          • instruction 実行する割り当てActivityを指定します。 「dequeue」を使用して、通話をQueueから外してWorkerに接続します。 割り当て命令の完全なリストについては、こちらの割り当てコールバックの処理をご覧ください。
                          • to Workerである相手の電話番号を指定します。
                          • from 通話をWorkerに接続する際に送信する必要がある発信者 ID を指定します。
                          • post_work_activity_sid 通話終了後にWorkerに割り当てるActivitySidを指定します。 これを使用して、Workerを通話後の作業として意味のあるステータス(「Wrapping up」など)に移行させます。

                          リンクされた通話の捕捉

                          Dequeueインストラクションの発行に先立って、TaskRouterはTaskのTaskAttributeをworker_call_sidで更新し、指定されたWorkerへの発信通話用に作成されたCallSidが分かるようにしています。

                          そのため、TaskのTaskAttributesはcall_sidおよびworker_call_sidを含んでいます。 これ以降、task.completedなどといったそのTaskに関連したEventには同様にこの情報を持っています。

                          リンクされた通話の捕捉が必要な場合は、この情報を持つtask.completedEventをリッスンするか照会するようにしてください。

                          追加アプリケーションロジックの実行後に通話をブリッジする

                          選択されたWorkerに通話をブリッジする前に、アプリケーションが何らかのアクションを実行する必要がある場合があります。 TaskRouterとTwiMLには、これを実現するための統合ポイントがいくつか用意されています。 次に、通常の動作を示します。

                          1. 上述の方法で、アプリケーションがTwiMLで <Enqueue> を使用して通話をQueueに入れます。 TaskRouterは、通話を処理するWorkerを予約して、AssignmentCallback HTTPリクエストをアプリケーションに送信します。
                          2. アプリケーションは、リクエストにHTTP 200レスポンスと空のボディーを返す必要があります。 これは、リクエストを処理しているがReservationを受諾する準備はまだできていないことをTaskRouterに通知します。
                          3. アプリケーションは、AssignmentCallback リクエストから取得した情報を使用して、CRM レコードの更新など、何らかのアクションを実行します。
                          4. 実行したアクションが失敗した場合または期待した結果が得られなかった場合、アプリケーションはReservationを拒否するようにTaskRouterに通知します。
                          5. アプリケーションは、CRMの更新の完了確認を受け取ると、Twilioの /Calls REST APIにPOSTリクエストを送信して、通話をWorkerの電話に発信します。
                          6. Workerが通話に応答したら、Twilioは、アプリケーションにHTTPリクエストを送信します。 アプリケーションは、Taskの reservationSid を指定して、<Queue><Dial> するTwiMLドキュメントを返します。 例:
                          <?xml version="1.0" encoding="UTF-8"?>
                          <Response>
                            <Dial>
                              <Queue reservationSid="WR0123456789abcdef0123456789abcdef"/>
                            </Dial>
                          </Response>
                          

                          このTwiMLドキュメントを実行すると、Workerと通話がブリッジされて、保留中のReservationは「accepted」とマークされます。

                          メモ: 待機中の通話をWorkerにブリッジする前に追加ロジックを実行する予定がある場合は、WorkflowでTask Reservationタイムアウトの時間を長めに設定してください。 既定値は120秒です。ほとんどの操作の場合、これで十分なはずです。

                          ReservationSid に <Dial> する際に追加パラメーターを指定する

                          次の例では、前の例と同じように、Reservationを承諾してTaskの通話にブリッジします。 通話が終了したら、Workerは指定されたActivity状態(たとえば「wrapping up」)に移行します。

                          <?xml version="1.0" encoding="UTF-8"?>
                          <Response>
                            <Dial>
                              <Queue
                                reservationSid="WR0123456789abcdef0123456789abcdef"
                                postWorkActivitySid="WA0123456789abcdef0123456789abcdef"/>
                            </Dial>
                          </Response>
                          

                          重要な制限と検討事項

                          TwiMLとTaskRouterを組み合わせて使用する場合、知っておく必要があるいくつかの重要な動作があります。

                          TwiMLが関連付けられているTaskRouterのTaskの更新を管理する

                          <Enqueue><Dial><Queue reservationSid="..."></Dial> を使用してTaskを作成して管理する場合、TwilioがTaskのライフサイクルを最新の状態に維持します。たとえば、Workerが応答する前に通話が終了した場合、TaskRouterは関連付けられているTaskをキャンセルします。この関連付けが存在するので、待機中のTwilio通話に関連付けられているTaskの状態は変更しないでください。

                          TaskRouter REST APIを使用してTaskの属性を変更すると、TwilioのTaskのライフサイクルを管理する機能を妨害してしまう可能性があります。 また、Dial->Queueは、指定されたReservationの受諾を実行します。 TaskRouter REST APIまたは割り当て命令によって、Reservationがすでに受諾されていた場合、Queueから外す操作はエラーが発生して失敗します。

                          Taskと通話を関連付けるTaskの属性

                          TwiMLによって生成される各Taskには、「call_sid」属性、および他の標準のTwilio通話の属性(「to」、「from」など)があります。

                          属性の完全なリストは次のとおりです。

                          {
                            "from_country": "",
                            "called": "",
                            "to_country": "",
                            "to_city": "",
                            "to_state": "",
                            "caller_country": "",
                            "call_status" : "",
                            "call_sid" : "",
                            "account_sid" : "",
                            "from_zip" : "",
                            "from" : "",
                            "direction" : "",
                            "called_zip" : "",
                            "caller_state" : "",
                            "to_zip" : "",
                            "called_country" : "",
                            "from_city" : "",
                            "called_city" : "",
                            "caller_zip" : "",
                            "api_version" : "",
                            "called_state" : "",
                            "from_state" : "",
                            "caller" : "",
                            "caller_city" : "",
                            "to" : ""
                          }
                          

                          Twilio Queueの一覧の変更

                          TaskRouterを <Enqueue> と一緒に使用する場合、TaskRouterは、指定されたWorkflowSidをフレンドリー名として使用して、Taskを保持する音声通話Queueを動的に作成します。 これらのQueueは、TaskRouterシステムが内部的に通話を保留するために使用します。 REST APIを使用して、これらのQueueまたはそのメンバーを変更すると、予測できない結果または不都合な結果が発生して、通話が正しくブリッジされなくなる可能性があります。

                          Rate this page:

                          ヘルプが必要ですか?

                          We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.