TwiML™ Voice： <Enqueue>
<Enqueue> 動詞は、現在の通話を通話キューに入れます。 キューに入った通話は、他の発信者からの <Dial> 動詞によってキューを外れるか、 REST API または <Leave> 動詞によってキューの外に転送されるまで、保留音で待機します。
<Enqueue> 動詞は、キューがまだ存在していない場合、オンデマンドでキューを作成します。キューの長さの最大値のデフォルトは 100 です。これは、REST API で変更できます。
動詞の属性
<Enqueue> 動詞は次の属性をサポートします。これらを使って動作を変更します。
| 属性名 | 許容値 | 初期値 |
|---|---|---|
| action | 相対または絶対 URL | none |
| method | GET, POST | POST |
| waitUrl | 相対または絶対 URL | 既定のクラシック音楽の再生リスト |
| waitUrlMethod | GET, POST | POST |
| workflowSid | TaskRouterワークフロー Sid | none |
action
action 属性は、絶対または相対 URL を値に取ります。 通話がキューを外れると、この URL へリクエストを送信し、後述のキューを外れた理由と、キューで待機した時間の詳細を通知します。 REST API リクエスト または <Leave> 動詞によってキューを外れた場合、ただちに action URL へリクエストを送信します。 <Dial> 動詞によってキューを外れた場合、ブリッジされた相手が通話を終了した後、action URL へリクエストを送信します。
リクエストパラメーター
Twilio は action URL へのリクエストとともに、 標準的な TwiML 音声通話リクエスト パラメーター に加え、次のパラメーターを渡します。
| パラメーター | 概要 |
|---|---|
| QueueResult | キューに入った通話の結果です。 詳細は、後述の QueueResult 値 を参照してください。 |
| QueueSid | キューの SID です。 通話が実際にキューに入った後に使用できます。 |
| QueueTime | 通話がキューで待機した時間です。 通話が実際にキューに入った後に使用できます。 |
QueueResult 値
次の値は、発信者をキューに入れた結果を示します。
| 値 | 概要 |
|---|---|
| bridged | 通話がキューから外れ、相手にブリッジされた。 |
| bridging-in-process | Twilio は、キューに入れられた側をブリッジするように指示されている。 |
| error | TwiMLはエラーコードを含みます。<Enqueue>動詞自身か waitUrlから返されたTwiMLに存在します。このAppモニターをクリックして下さい。 |
| hangup | キューに入った発信者が、相手に接続される前に電話を切った。 |
| leave | キューに入った発信者が、<Leave> 動詞によりキューを出て行った。 |
| redirected | キューで待機中に、通話がリダイレクトされてキューを外れた。 通常は REST API リクエストにより発生します。 |
| redirected-from-bridged | キューに入れられた後、正常にブリッジされたセッションが転送された。 |
| queue-full | 宛先のキューがいっぱいで、キューに入れなかった。 |
| system-error | The Twilio system malfunctioned during the enqueue process. This can happen if a caller hangs up before being fully enqueued. |
method
method 属性は GET または POST の値を取ります。 action URL へのリクエスト送信に、HTTP の GET と POST のどちらを使うかを、Twilio に指示します。 この属性は、HTML フォームの method 属性に従い指定します。初期値は POST です。
waitUrl
waitUrl 属性には、発信者がキューで待機中に実行される TwiML 動詞を記述した TwiML 文書 の URL を指定します。
waitUrl の TwiML フローで最後の動詞が実行されると、Twilio は waitUrl へリクエストを再送し、フローが最初から繰り返されます。通常は保留音の再生を無制限に繰り返します。 複数の TwiML 文書のフローを実行するには、<Redirect> 動詞を使います。ただし、すべての TwiML 文書が実行されると、フローは必ず waitUrl の TwiML 文書に戻ります。
waitUrl の TwiML 文書は次の動詞をサポートします。
| 動詞 | 概要 |
|---|---|
| <Play> | 発信者に音声ファイルを再生します。 |
| <Say> | Twilio のテキスト音声変換を使って、発信者にテキストを読み上げます。 |
| <Pause> | 指定された秒数のポーズを挿入します。 |
| <Hangup> | 電話を切ります。通話はキューから外れ、終了します。 |
| <Redirect> | 他の TwiML 文書へリダイレクトします。 |
| <Leave> | 現在の通話を終了せずに、キューから外します。 処理は次の動詞へ進みます。 |
| <Gather> | 発信者が電話機のプッシュボタンに入力した番号を収集します。 メモ: 「<Enqueue>」のwaitUrlで返される「<Gather>」では、DTMF入力タイプのみがサポートされ、スピーチ入力タイプはサポートされません。 |
リクエストパラメーター
Twilio は waitUrl URL へのリクエストとともに、 標準的な TwiML 音声通話リクエスト パラメーター に加え、次のパラメーターを渡します。
| パラメーター | 概要 |
|---|---|
| QueuePosition | キューに入った通話の、現在のキューの位置です。 |
| QueueSid | 発信者が入っているキューの SID です。 |
| QueueTime | 発信者がキューで待機している時間 (秒) です。 |
| AvgQueueTime | 現在待ち行列に入っている発信者がどのくらいの時間待たされているかの平均を示す秒数です。 |
| CurrentQueueSize | 現在このキューに入っている通話の数です。 |
waitUrlMethod
waitUrlMethod 属性は GET または POST の値を取ります。 waitUrl URL へのリクエスト送信に、HTTP の GET と POST のどちらを使うかを、Twilio に指示します。 この属性は、HTML フォームの method 属性に従い指定します。初期値は POST です。
workflowSid
workflowSid属性は、この通話を表す新しいTaskRouterタスクを作成するように指示し、その処理に使用するワークフローの ID を指定します。
workflowSid が指定されている場合、この通話を入れるキューの名前を指定する必要はありません。通話を処理するように指定されたワーカーは、デキューアサインメント命令を使用して、キューから外して接続することができます。
名詞
TwiML 動詞の名詞とは、動詞のネストされた要素で、それ自身が動詞ではないものを指します。動詞が動作を行う対象です。 <Enqueue> の名詞は、次の通りです。
| 名詞 | 概要 |
|---|---|
| plain text | 特定のキューの名前です。 |
| Task | 新しく作成されたタスクに設定する JSON 形式の属性です。 |
指定された名前のキューがまだ作成されていない場合、オンデマンドでキューが作成されます。キュー名は最大 64 文字で指定できます。
Task の使用方法の詳細情報と例については、TaskRouter TwiML Integration ページを参照してください。
サンプル
例 1: キューに入れる
この TwiML 文書では、wait-music.xml という TwiML 文書を取得し、発信者がキューで待機している間に実行するよう、Twilio に指示しています。
wait-music.xml は、発信者のために保留音を再生します。
ヒントとテクニック
- waitUrl へのリクエストのパラメーターと
<Say>を使って、発信者にキューの位置を読み上げたり、待ち時間の予想を知らせることができます。
ヘルプが必要ですか？
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。