TwiML™ Voice： <Number>
<Dial> 動詞の <Number> 名詞は、ダイヤルする宛先の電話番号を指定します。名詞の属性を使って、その番号をダイヤルする時における Twilio の動作を指定できます。
<Dial> 動詞で最大 10 件の <Number> 名詞を使用して、全宛先に同時に電話をかけることができます。最初に応答があった電話が現在の通話に接続され、残りの電話は切断されます。各 <Number> 名詞について、webhook を受け取るコールプログレスイベントの種類を指定できます。
名詞の属性
この名詞<Number>は振る舞いを変更する属性をサポートします。
| 属性名 | 許容値 | 初期値 |
|---|---|---|
| sendDigits | すべての数字 | none |
| url | すべての URL | none |
| method | GET, POST |
POST |
| statusCallbackEvent | initiated, ringing, answered, completed |
completed |
| statusCallback | すべての URL | none |
| statusCallbackMethod | GET, POST |
POST |
電話番号には「+」と国番号が必要です。例 : +16175551212 (E.164 フォーマット) Twilio はこのフォーマット以外のアメリカの番号も扱えます (例 : (415) 555-1212 または 415-555-1212)。
sendDigits
sendDigits 属性は、相手が応答したら DTMF を送信するよう、Twilio に指示します。 電話番号と内線番号をダイヤルする場合に便利です。 Twilio は電話番号をダイヤルし、自動システムが応答すると、DTMF を送信して内線を呼び出します。
url
url属性では、相手が応答した後 かつ 相手との接続が成立する前に、相手側で実行したい TwiML 文書を指定することができます。 この TwiML を使うと、相手に向けて情報を再生したり読み上げたりすることができます。また、<Gather> や <Hangup> を使うと、相手に通話の拒否や切断の機会を与えます。 相手側 (つまり発信先) で、TwiML 文書が実行されている間は、発信者側では呼び出し音が聞こえます。 ただし、この方式で実行される TwiML 文書には <Dial> 動詞 を含めることはできません。
method
method 属性には、url 属性の URL へのリクエスト送信に使う HTTP メソッドを指定します。 初期値はPOSTです。
statusCallbackEvent
<Dial>を使ってClientに発信した時、アウトバウンドコールが開始されます。initiatedからringingへのコール遷移は、電話が鳴り始めた時起こります。answeredは受話した時に、最後に通話が終わった時にcompletedへと遷移します。statusCallbackEventと共に、異なったコールプログレスイベントのwebhook を受け取ることができます。initiated、ringing、answered、completedをそれぞれ受け取ることができます。相対URL以外では、有効なホスト名を指定しなければなりません（アンダースコアは使用できません）。
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特定します。
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リクエストを生成し、同じ順番の到着は保証されません。 |
サンプル
例 1: sendDigits を使う
ここでは、415-123-4567 の内線 1928 へダイヤルします。 <Number> 名詞を使って電話番号を記述し、sendDigits 属性を追加します。 内線をダイヤルする前にウエイトを入れたいので、先頭に「W」の文字を追加します。 Twilio は、「W」 1 文字につき 0.5 秒待ってから、番号を送信します。 これで、番号のダイヤルを始めるタイミングを、自動応答システムに合わせます。
例 2: 一斉発信
ここでは、複数の <Number> を使って、3 つの電話番号へ一斉にダイヤルします。3 つの通話のうち、最初に相手が応答した通話が発信者へ接続され、それ以外の通話はキャンセルされます。
例 3: コールプログレスイベント
ここでは、<Dial> で番号をダイヤルするときに、コールプログレスイベントが発生するたびに webhook を受け取ります。
例 4：コールプログレスイベントによる複数のダイヤル
ここでは、<Dial> で複数の番号にダイヤルするときに、各番号でコールプログレスイベントが発生するたびに webhook を受け取ります。
ヒントとテクニック
<Dial>動詞を含めて10個の番号に同時にダイヤルできます。-
一斉発信は、着信通話を受けた時に複数の番号 (または人) を呼び出したい場合に役立ちます。 最初に通話が接続されると、残りの通話の呼び出しはキャンセルされますので、注意してください。 オフィスの電話システムや、フライト モードに設定された携帯電話へダイヤルすると、1 回の呼び出し音で応答があります。このため、他の通話がすぐにキャンセルされてしまい、人が応答するまで長く呼び出し音を鳴らすことができません。
一斉発信は相手の状況を知っている場合に使うよう、注意する必要があります。
ヘルプが必要ですか？
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.