TwiML™ Voice： <Client>
<Dial> 動詞の <Client> 名詞は、ダイヤルするクライアント識別子を指定します。
同時に多くのクライアントに接続を試みるため、<Dial>動詞を含めた10個の<Client>名詞を含めることができます。最初のクライアントが着信接続をした際、他の試行中の接続はキャンセルされます。多くのクライアントと同時に接続したい場合<Conference>名詞の利用方法をお読みください。
The client identifier should not contain control, space, delims, or unwise characters. Mobile SDKs cannot include any special characters and must only use alphanumeric characters and underscore.
名詞の属性
この名詞<Client>は振る舞いを変更する属性をサポートします。
| 属性名 | 許容値 | 初期値 |
|---|---|---|
url |
Any URL | none |
method |
GET, POST |
POST |
statusCallbackEvent |
initiated, ringing, answered, completed |
none |
statusCallback |
Any 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属性では、Twilioがurl属性で与えられたURLにアクセスする際に、どのHTTPメソッドを用いるかを指定します。デフォルトは POST です。
statusCallbackEvent
<Dial>を使ってClientに発信した時、アウトバウンドコールが開始されます。initiatedからringingへのコール遷移は、電話が鳴り始めた時起こります。answeredは受話した時に、最後に通話が終わった時にcompletedへと遷移します。statusCallbackEventと共に、異なったコールプログレスイベントのwebhook を受け取ることができます。initiated、ringing、answered、completedをそれぞれ受け取ることができます。
The statusCallbackEvent attribute allows you to specify which events Twilio should call a webhook on. To specify multiple events separate them with a space: initiated ringing answered completed. If a statusCallback is provided and no status callback events are specified the completed event will be sent by default.
一報APIを通じてアウトバウンドコールが生成されるとき、<Dial>を使ってアウトバウンドコールはすぐさま開始され、キュー(queue)に入ることがありません。下記の返却されうるコールイベントのタイムラインです。異なるコールステータスが<Dial>レグ(leg)で発生します。
| イベント | 概要 |
|---|---|
initiated |
This event is fired when Twilio starts dialing the call. |
ringing |
This event is fired when the call starts ringing. |
answered |
This event is fired when the call is answered. |
completed |
This event is fired when the call is completed, regardless of the termination status: busy, canceled, completed, failed, or no-answer. If no StatusCallbackEvent is specified, completed will be fired by default. |
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 using the SDKs. For Client JS, refer to Connection.customParameters, for iOS, refer to TVOConnectOption.params, and for Android, refer to ConnectOptions.getParams()
サンプル
Example 1: Dialing a client
この例では、現在の通話を joey という名前のクライアントへ接続します。通話を joey に接続するには、 <Dial> 動詞を使い、中に <Client> 名詞をネストします。
Example 2: Simultaneous dialing
複数の電話番号と、クライントに同時に接続するため<Dial>動詞を含めた<Number>と<Client>名詞を10個まで使うことができます。初めての受信者とコールが成立した場合、残りの試行中の接続は切断されます。
Example 3: Call-progress events
In this case, we want to receive a webhook for each call-progress event when dialing a Client using <Dial>.
ヘルプが必要ですか？
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.