TwiML™ Voice： <Client>
<Dial> 動詞の <Client> 名詞は、ダイヤルするクライアント識別子を指定します。
同時に多くのクライアントに接続を試みるため、<Dial>動詞を含めた10個の<Client>名詞を含めることができます。最初のクライアントが着信接続をした際、他の試行中の接続はキャンセルされます。多くのクライアントと同時に接続したい場合<Conference>名詞の利用方法をお読みください。
現在クライアント識別子には、半角英数字とアンダースコアのみ使用できます。
名詞の属性
この名詞<Client>は振る舞いを変更する属性をサポートします。
| 属性名 | 許容値 | 初期値 |
|---|---|---|
| url | すべての URL | none |
| method | GET, POST |
POST |
| statusCallbackEvent | initiated, ringing, answered, completed |
none |
| statusCallback | すべての URL | none |
| statusCallbackMethod | GET, POST |
POST |
url
The 'url' attribute allows you to specify a url for a TwiML document that will run on the called party's end, after she answers, but before the parties are connected. You can use this TwiML to privately play or say information to the called party, or provide a chance to decline the phone call using <Gather> and <Hangup>. If answerOnBridge attribute is used on <Dial>, the current caller will continue to hear ringing while the TwiML document executes on the other end. TwiML documents executed in this manner are not allowed to contain the <Dial> verb.
method
method 属性には、url 属性の URL へのリクエスト送信に使う HTTP メソッドを指定します。 初期値はPOSTです。
statusCallbackEvent
<Dial>を使ってClientに発信した時、アウトバウンドコールが開始されます。initiatedからringingへのコール遷移は、電話が鳴り始めた時起こります。answeredは受話した時に、最後に通話が終わった時にcompletedへと遷移します。statusCallbackEventと共に、異なったコールプログレスイベントのwebhook を受け取ることができます。initiated、ringing、answered、completedをそれぞれ受け取ることができます。
statusCallbackEvent属性はTwilioがどのイベントを webhook するべきかを認めます。複数のイベントを指定する際は右記の通りスペースで区切ります。 : initiated ringing answered completedstatusCallbackあり、ステータスコールバックイベントが特定されない場合、completedイベントがデフォルトで送信されます。
一報APIを通じてアウトバウンドコールが生成されるとき、<Dial>を使ってアウトバウンドコールはすぐさま開始され、キュー(queue)に入ることがありません。下記の返却されうるコールイベントのタイムラインです。異なるコールステータスが<Dial>レグ(leg)で発生します。
| イベント | 概要 |
|---|---|
| initiated | Twilioがダイヤリングを始めた時、initiatedイベントが発動します。 |
| ringing | 電話が鳴り始めると、ringingイベントが発動します。 |
| answered | 通話を開始(受話)するとansweredイベントが発動します。 |
| completed | completedイベントは端末の状態に関係なく（busy、canceled、completed、failed、no-answer）コールが終了した時に発動します。 StatusCallbackEventが指定されない場合、completedがデフォルトで発動されます。 |
statusCallback
statusCallback属性は、statusCallbackEvent属性で指定されたおのおののイベントに対してWebhookリクエストを送信するためのURLを指定できます。 相対URL以外では、有効なホスト名を指定しなければなりません（アンダースコアは使用できません）。
statusCallbackMethod
statusCallbackMethod属性では、TwilioがstatusCallback属性で与えられたURLにアクセスする際に、どのHTTPメソッドを用いるかを指定します。デフォルトは POST です。
Status Callback HTTP パラメーター
TwilioがTwilio番号の一つのコールを受信した時、Twilioがアプリケーションに渡すStatusCallbackに送信される非同期のリクエスト中のパラメーターはTwiML検索するために非同期のリクエストにパラメーターを含めます。全てのリストと詳細はTwiML Voiceリクエストドキュメントをご覧ください。
コールプログレスイベントが発動された時、コールバックリクエストは、この他にも次のパラメーターを渡します。
| パラメーター | 概要 |
|---|---|
| CallSid | Twilio が生成したこの通話のユニークな識別子です。CallSidは新しい TwiML URLと共に Call/{CallSid}をPOSTし、チャイルドコールを修正することができます。 |
| ParentCallSid | 親コールを一意に特定する識別子 |
| CallStatus | このコールのステータス詳細取りうる値は queued(キューに入った), initiated(処理が開始された), ringing(呼び出し中), in-progress(通話中), busy(話し中), failed(失敗), no-answer(電話に出ず) です。詳細はコールのステータス セクションをご覧ください |
| CallDuration | 通話の秒数completedのイベントにのみ現れます。 |
| RecordingUrl | 音声通話の録音済みオーディオのURLです。 このパラメーターは録音が <Dial> で設定されている場合に追加され、その他の手段で開始された録音には含まれません。 RecordingUrl は completed イベント内にのみ存在します。 |
| RecordingSid | この通話から発生した録音の一意なIDRecordingSidはcompletedのイベントでのみ発生します。 |
| RecordingDuration | 録音されたオーディオの長さ (秒) です。 RecordingDuration は completed イベント内にのみ存在します。 無音部分を削除した後の正確な録音の長さの確定値を取得するには、RecordingStatusCallbackを使用してください。 |
| Timestamp | このイベントが生成された日付の UTC 表記です。RFC 2822フォーマットを使用します。 |
| CallbackSource | webhookのソースを記述する文字webhookがなぜ発生したか曖昧さの排除に役立ちます。Status Callback では、値は常にcall-progress-eventsです。 |
| SequenceNumber | イベントが発動する順番は、0から始まります。イベントが順々に発動すると、分離されたHTTPリクエストを生成し、同じ順番の到着は保証されません。 |
Custom Parameters
It is possible to include additional key value pairs that will be passed to the Client (Web or Mobile). You can do this by using the nested <Parameter> TwiML noun.
These custom parameters can retrieved in the SDKs. For Client JS, refer to Connection.customParameters, for iOS, refer to TVOConnectOption.params, and for Android, refer to ConnectOptions.getParams()
サンプル
例 1: クライアントへダイヤルする
この例では、現在の通話を joey という名前のクライアントへ接続します。通話を joey に接続するには、 <Dial> 動詞を使い、中に <Client> 名詞をネストします。
例 2: 一斉発信
複数の電話番号と、クライントに同時に接続するため<Dial>動詞を含めた<Number>と<Client>名詞を10個まで使うことができます。初めての受信者とコールが成立した場合、残りの試行中の接続は切断されます。
例 3: コールプログレスイベント
これは、<Dial>でClientにダイヤルするときに それぞれのコールプログレスイベントをwebhookで受け取りたいケースです。
ヘルプが必要ですか？
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。