TwiML™ Voice： <Conference>
<Dial> 動詞の <Conference> 名詞を使って、カンファレンスルームに接続できます。<Number> 名詞で別の電話番号に接続できるように、<Conference> 名詞では、名前をつけたカンファレンスルームに接続し、同じカンファレンスルームに接続している他の発信者と会話できます。このように、カンファレンスは、コールの保留・転送・割り込み時の退避場所のような形で使うこともできます。
Twilioは、世界規模に分散された低遅延な電話会議システムを提供しています。 電話会議は大多数の参加者にもっとも近い地域でホストされ、最大の参加者キャパシティーは250人です。 通常の音声通話の分単位の料金に加え、参加者単位、分単位の料金も適用されます。 Conferenceの料金体系についてさらに詳しく
カスタマイズが可能な機能
自由にルームの名前をつけることができます。この名前はアカウント内でのみ有効です。これは、あなたのアカウント経由で room1234 に入室する発信者は全員同じカンファレンスルームに入室することになりますが、別のアカウント経由で接続している発信者はそこには入室できないことを意味します。
注 : コンプライアンス上の理由から、電話番号、メールアドレス、または個人名やその他の機密情報のような個人データ（個人識別情報とも呼ばれます）をカンファレンスの命名に使用しないでください。
デフォルトでは、Twilioカンファレンスルームはあなたのニーズに合わせてルームを 有効・無効 にすることができます。
- カンファレンスは 2名以上の参加が無ければ始まりません。
- 待機中は、カスタマイズ可能な音楽を再生します。
- 参加者が入室したり退出したりする時に、通知音を出して他の参加者に知らせます。
- イベントを構成してアプリケーションに対して電話会議の状態変化を知らせるアラートを発することができます。
- ベータ版の機能: 参加者が話し始めたり、話し終えたりした際にWebhookを受信する
これらの機能は、ユーザーのニーズに合わせて設定したり、無効化したりできます。
名詞の属性
この名詞<Conference>は振る舞いを変更する属性をサポートします。
| 属性名 | 許容値 | 初期値 |
|---|---|---|
| muted | true, false | false |
| beep | true, false, onEnter, onExit | true |
| startConferenceOnEnter | true, false | true |
| endConferenceOnExit | true, false | false |
| waitUrl | TwiML の URL、空文字列 | デフォルトの Twilio 保留音 |
| waitMethod | GET または POST | POST |
| maxParticipants | 250以下の正の整数です | 250 |
| record | do-not-record もしくは record-from-start | do-not-record |
| region | us1, ie1, de1, sg1, br1, au1, jp1 | なし |
| trim | trim-silence (無音部分を削除する) もしくはdo-not-trim | trim-silence |
| coach | 通話SIDです | none |
| statusCallbackEvent | start end join leave mute hold speaker | なし |
| statusCallback | 相対または絶対 URL | なし |
| statusCallbackMethod | GET, POST | POST |
| recordingStatusCallback | 相対または絶対 URL | なし |
| recordingStatusCallbackMethod | GET, POST | POST |
| recordingStatusCallbackEvent | in-progress, completed, absent |
completed |
| eventCallbackUrl | 相対または絶対 URL | なし |
muted
muted属性は参加者がカンファレンスで話すことができるかを指定します。trueに設定された場合、参加者はカンファレンスで音声を聞くことだけができます。デフォルトはfalseです。
beep
beep属性は参加者がカンファレンスに参加、退出した際に通知音を出すか否かを設定できます。デフォルトはtrueです。
| 値 | 動作 |
|---|---|
| true | デフォルト設定。参加者が参加、退出した歳、ビープ音を再生します。 |
| false | 参加者が参加、退出した際のビープ音を無効にします。 |
| onEnter | 参加者がカンファレンスに参加した時のみビープ音を再生します。参加者が退出したした時はビープ音を再生しません。 |
| onExit | 参加者がカンファレンスを退出した時のみビープ音を再生します。参加者が参加した時はビープ音を再生しません。 |
startConferenceOnEnter
参加者がいて、まだカンファレンスが始まっていない場合、カンファレンスのスタートを伝える属性です。デフォルトはtrueです。設定値がfalseで且つ参加者がいるがカンファレンスが始まっていない場合、参加者はミュートになり、バックグランドミュージックが流れます。startConferenceOnEnterがtrueである特定の参加者が参加するまで続きます。司会者が存在するカンファレンスで便利です。
endConferenceOnExit
trueに設定されている場合、該当の参加者が退出するとカンファレンスは終了し、他の参加者全員が強制的に退出させられます。デフォルトはfalseです。2つのコールをブリッジし、片方が切断してもTwiMLを実行し続ける場合、且つ司会者がいるカンファレンスを作る場合に便利です。
waitUrl
waitUrl 属性には、カンファレンスが始まる前に流す音楽の URL を指定します。 URL のコンテンツは MP3、WAV、 <Play> または <Say> を使った TwiML 文書を使用できます。 デフォルトは、クリエイティブ コモンズ ライセンスのバックグラウンド音楽が選ばれます。ただし、自分で用意した音楽やメッセージに変更できます。 waitUrl が TwiML のレスポンスの場合、Twilio は <Play> 、 <Say>、 <Redirect> 動詞のみを処理します。 <Record>、 <Dial>、 <Gather> 動詞を使うことはできません。 カンファンレンスの開始前に音楽を流したくない場合は、空文字列を指定します (waitUrl を '' に設定)。
If no 'waitUrl' is specified, Twilio will use its own HoldMusic Twimlet
that reads a public AWS S3 Bucket for audio files. The default 'waitUrl' is:http://twimlets.com/holdmusic?Bucket=com.twilio.music.classical
この URL は、クリエイティブ コモンズ のクラシック音楽を格納した S3 バケット com.twilio.music.classical を示しています。 次のリストの S3 バケットが用意されています。いろいろなジャンルの音楽から選べます。
waitMethod
waitMethod 属性には、waitUrl へのリクエスト送信に使う HTTP メソッドを指定します。 初期値は POST です。 WAV や MP3 などの静的な音声ファイルを直接リクエストする場合は、GET を使って Twilio がキャッシュできるようにしてください。
maxParticipants
この属性は、名前のついた電話会議室に許容したい最大参加者数を表します。 最大参加者数は250です。
record
'record'属性は <conference> 全体の録音を可能にします。 record-from-start に設定した場合は、最初の2人の参加者が接続されたタイミングで録音が開始されます。 保留中の音楽は録音されません。 'recordingStatusCallback' URLが指定されている場合、TwilioはそのURLに録音の詳細を伴うリクエストを、録音がアクセス可能になった時点で発行します。
region
「region」属性はTwilioが電話会議をミックスするリージョン（地域）を指定します。 リージョンの値を指定により、Twilioの自動リージョン選択ロジックが上書きされます。 これは電話会議がミックスされる場所が分かっている確信がある場合のみ使用してください。 Twilioは、regionパラメーターを指定した最初の参加者に基づいてこのパラメーターを設定し、それ以降の参加者で指定されたものについてはこれを無視します。
trim
”trim”属性は音声ファイルから無音部分を探しだします。
"trim"のデフォルトはtrim-silenceです。録音の始めと終わりの無音部分を削除します。
これにより、録音ファイルの分数は通話時間よりも少なくなります。
coach
Coach accepts a call SID of a call that is currently connected to an in-progress conference. Specifying a call SID that does not exist or is no longer connected to the conference will result in the call failing to the action URL and throwing a 13240 error. Coach is a feature of Agent Conference, which can be enabled via the Twilio Console.
statusCallbackEvent
「statusCallbackEvent」属性により、「statusCallback」属性で指定されている URL にどのカンファレンスの状態変更で webhook を生成するかを指定できます。 使用可能な値はstart、end、join、leave、mute、hold、およびspeakerです。 複数の値を指定する際は、スペースで区切ります。 イベントは電話会議に接続した最初の参加者によって設定され、以降のstatusCallbackEventsは無視されます。 電話会議イベントを指定すると、指定されたConsole内の電話会議ログに対応するトリガーされたイベントのログを閲覧できます。
| イベント | 概要 |
|---|---|
| start | The conference has begun and audio is being mixed between all participants. This occurs when there are at least two participants in the conference, and at least one of the participants has startConferenceOnEnter="true". |
| end | 最後の参加者がカンファレンスから退出したか、または endConferenceOnExit="true" の参加者がカンファレンスから退出しました。 |
| join | 参加者がカンファレンスに参加しました。 |
| leave | 参加者がカンファレンスから退出しました。 |
| mute | 参加者がミュートまたはミュート解除されています。 |
| Hold | 参加者が保留、または保留解除しました。 |
| speaker | 参加者が話し始め（または終わり）ました |
statusCallback
'statusCallback' 属性はURLを引数として取ります。 'statusCallbackEvent' パラメーターで指定された電話会議のイベントがこのURLに送信されます。 statusCallbackのURLは電話会議に接続した最初の参加者によって設定され、以降のstatusCallbackは無視されます。 イベントリクエストに含まれるパラメーターについて、下記で詳述します。
statusCallbackMethod
上述の URL へリクエストを送信する際に、Twilio が使用する HTTP のメソッドです。初期値は POST です。
リクエストパラメーター
Twilio は、リクエストと以下のパラメーターを「statusCallback」URL へ転送します。
| パラメーター | 例 | 送信時 |
|---|---|---|
| ConferenceSid | CFe08c870b500f6e44a9ad184defd1f391 | 送信時：すべて |
| FriendlyName | AgentConf | 参加時、退出時、開始時、終了時、消音時、保留時に呼び出されます |
| AccountSid | AC25e16e9a716a4a8617a7c83f58e30482 | 送信時：すべて |
| SequenceNumber | 1 | 送信時：すべて |
| Timestamp | Thu, 1 Jun 2017 20:48:32 +0000 | 送信時：すべて |
| StatusCallbackEvent | conference-end conference-start participant-leave participant-join participant-mute participant-unmute participant-hold participant-unhold participant-speech-start participant-speech-stop |
参加時、退出時、開始時、終了時、消音時、保留時に呼び出されます |
| CallSid | CA25e16e9a716a4a1786a7c83f58e30482 | 参加時、退出時、開始時、終了時、消音時、保留時に呼び出されます |
| muted | true, false | 参加時、退出時、開始時、終了時、消音時、保留時に呼び出されます |
| Hold | true, false | 参加時、退出時、開始時、終了時、消音時、保留時に呼び出されます |
| endConferenceOnExit | true, false | 以下の際に送信されます: 参加 退出 ミュート スピーカー |
| startConferenceOnEnter | true, false | 以下の際に送信されます: 参加 退出 ミュート スピーカー |
| EventName* | conference-record-end | 送信時： conference-record-end |
| RecordingUrl* | https://api.twilio.com/2010-04-01/Accounts/AC123/Recordings/RE234 | 送信時： conference-record-end |
| Duration* | 6 | 送信時： conference-record-end |
| RecordingFileSize* | 90786 | 送信時： conference-record-end |
* 上記すべての 'conference-record-end' パラメーターは、録音の関連情報を取得に推奨されるアプローチであるrecordingStatusCallbackに取って代わられ、廃止予定となりました。 recordingStatusCallback を与えることで、conference-record-end コールバックは呼び出されなくなります。
recordingStatusCallback
'recordingStatusCallback'属性はその引数に相対または絶対URLを取ります。
電話会議の録音が record 属性で要求され、 'recordingStatusCallback' URLが与えられると、Twilioは録音がアクセス可能になったときにGETまたはPOSTリクエストを指定されたURLに発行します。
リクエストパラメーター
Twilio は、リクエストと以下のパラメーターを「recordingStatusCallback」URL へ転送します。
| パラメーター | 概要 |
|---|---|
| AccountSid | この録音の属するアカウントの一意な識別子です。 |
| ConferenceSid | 録音の関連づけられた電話会議の一意な識別子です。 |
| RecordingSid | この録音のユニークな識別子です。 |
| RecordingUrl | 録音された音声の URL。 |
| RecordingStatus | The status of the recording. Possible values are: in-progress, completed,absent. |
| RecordingDuration | この録音の長さ（秒）です。 |
| RecordingChannels | 最終的な録音ファイルのチャンネル数を示す整数です。 電話会議の録音では、1 チャンネルのみがサポートされます。 |
| RecordingStartTime | The timestamp of when the recording started. |
| RecordingSource | The initiation method used to create this recording. Conference is returned for Conference recordings. |
recordingStatusCallbackMethod
この属性は、「recordingStatusCallback」のリクエスト送信に使う HTTP メソッドを指定します。デフォルトは「POST」です。
recordingStatusCallbackEvent
This attribute allows you to specify which recording status changes should generate a webhook to the URL specified in the 'recordingStatusCallback' attribute. The available values are in-progress, completed, absent. To specify multiple values separate them with a space. Default is completed.
既定でのステータス変更イベントは以下の通りです:
| パラメーター | 概要 |
|---|---|
| in-progress | 録音が開始されました |
| completed | 録音が完了しアクセス可能です |
| absent | The recording is absent and not accessible |
To pause or resume conference recordings, see the Recording API Docs.
eventCallbackUrl
このパラメーターは recordingStatusCallbackに取って代わられ、廃止予定となりました。
'eventCallbackUrl' 属性は引数にURLをとります。 電話会議が終了すると、TwilioはstatusCallbackの conference-record-end イベント・パラメーターを伴うPOSTリクエストをこのURLに発行します。
サンプル
例 1: カンファレンスをする
この TwiML を実行する最初の発信者が Room 1234 という名前のカンファレンス ルームに入室すると、デフォルトの保留音が聞こえてきます。 次の発信者がこの TwiML を実行すると、2 人の発信者が同じカンファレンス ルームに入室し、カンファレンスが始まります。 保留音は終了し、通知音が鳴り、すべての参加者が会話できる状態になります。
例 2: モデレーターがいるカンファレンス
まず、カンファレンスがまだ始まらないように指定して、参加者をカンファレンス ルームに入室させます。
参加者は保留音を聞きながら待機します。 カンファレンスを主催する「モデレーター」が電話をかけてきたらカンファレンスが始まるように指定します。
また、このモデレーターには endConferenceOnExit='true' が指定されているので、モデレーターが電話を切ると、カンファレンスが終了し、参加者の <Dial> は終了します。
例 3：イベント付きカンファレンスに参加する
このプログラム・コードでは、参加者の電話会議への入退室、消音、保留、および電話会議の開始と終了にイベントが呼び出される電話会議に接続します。
例 4：ミュートでカンファレンスに参加する
このコードでは、マイクをミュートにして、カンファレンスに参加できます。この参加者は、ミュートにされていない参加者の会話を聞くことはできますが、自分の発言は他の参加者には聞こえません。muted 属性は、REST API でリアルタイムに有効化または無効化できます。
例 5：通話をブリッジする
単に 2 つの通話をブリッジしたいだけ、という場合があります。 このような最小限のカンファレンスでは、バックグラウンド音楽も通知音も再生せず、参加者は入室後すぐに会話を始めて、どちらかの参加者が電話を切るとカンファレンスがただちに終了します。 Dial をするように、既存の 2 つの通話をブリッジするケースなどで役立ちます。
このコードでは、最初の発信者は待合室に入り、バックグラウンド音楽を聞きます。 担当者やオペレーターを待っている間、発信者を保留中にするのと同じです。
オペレーターや担当者の準備ができると、彼らの通話は次のコードを実行します。
このコードで、オペレーターが保留していた人とつながります。 カンファレンスは 2 人が入室すると始まるので、最初の人が聞いていた保留音は終わり、2 人は会話を始めます。 beep='false' が設定されているため、担当者が電話に出た時の通知音は、発信者には聞こえません。このケースではその方が適切でしょう。 オペレーターが電話を切ると、endConferenceOnExit でカンファレンスが終了します。
例 7： Dial の属性との組み合わせ
Conference は Dial の要素なので、すべての Dial の属性は Conference と組み合わせて使えます (ただし、callerId と timeout には影響しません)。 timeLimit を設定し、これを超えるとカンファレンスから退出させることができます。 hangupOnStar を有効にし、* キーを押すとカンファレンスを退出するように設定できます。 action を指定すると、カンファレンス ルームを退出した時に Twilio が action へリクエストを送信し、ユーザーのウェブ サーバーが新しい TwiML レスポンスで応答して、通話を継続させることができます。
例 8：カンファレンスを録音する
このコードは、最初の2人の参加者が接続されたときに開始される電話会議の完全な録音を可能にし、電話会議の録音がアクセス可能になったら recordingStatusCallback を送信します。
ヘルプが必要ですか？
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.