TwiML™ Voice： <Record>
<Record> 動詞は、発信者の音声を録音し、録音した音声ファイルの URL を返却します。<Record> 動詞の transcribe 属性を true にセットすることで、録音された通話のトランスクリプションも生成できます。
Legal implications of call recording
If you choose to record voice or video calls, you need to comply with certain laws and regulations, including those regarding obtaining consent to record (such as California’s Invasion of Privacy Act and similar laws in other jurisdictions). Additional information on the legal implications of call recording can be found here.
Notice: Twilio recommends that you consult with your legal counsel to make sure that you are complying with all applicable laws in connection with communications you record or store using Twilio.
動詞の属性
<Record> 動詞は次の属性をサポートします。これらを使って動作を変更します。
| 属性名 | 許容値 | 初期値 |
|---|---|---|
| action | 相対または絶対 URL | 現在の文書の URL |
| method | GET, POST |
POST |
| Timeout | 正の整数値(秒) | 5 |
| finishOnKey | すべての数字キー、# キー、* キー |
1234567890*# |
| maxLength | 1 より大きい整数値 | 3600 (1 時間) |
| playBeep | true, false |
true |
| trim | trim-silence, do-not-trim |
trim-silence |
| recordingStatusCallback | 相対または絶対 URL | none |
| recordingStatusCallbackMethod | GET, POST |
POST |
| recordingStatusCallbackEvent | in-progress, completed, absent |
completed |
| transcribe | true, false |
false |
| transcribeCallback | 相対または絶対 URL | none |
DIAL動詞 と SMS動詞は、複数の属性を使えます。
下の例ではcallerIdパラメータが省略されていますが、Twilio for KDDI Web Communications をご利用のお客様においては、callerId パラメータで必ずご自身で購入したTwilio電話番号を指定する必要があり、かつ、省略できません。
DIAL動詞で電話をかける場合にはTwilio電話番号（050/0120/0800/その他番号）を、SMS動詞でSMSを送信する場合にはアメリカ番号もしくはSMSが有効なTwilio番号を指定する必要があります。
action
'action'属性は、値として相対または絶対URLを取ります。 録音が終了すると、Twilioは下記のパラメーターを含んだGETまたはPOSTのリクエストを、このURLに発行します。 'action'が指定されなかった場合、<Record>は既定で現在のドキュメントのURLをリクエストします。
このリクエストの発行後、Twilioはユーザーのサーバーからのレスポンスで受け取ったTwiMLを使用して現在の通話を継続します。 既定ではTwilioは現在のドキュメントのURLを再リクエストすることから、不注意で意図せぬループ状態を引き起こすことがある点に留意してください。 <Record>以降に現れるTwiML動詞は到達不可能になります。
ただし 1 つ例外があります。録音された音声ファイルが空の場合、action URL へのリクエストは行われません。 コールフローは、現在の TwiML 文書内の次の動詞へ進みます。
リクエストパラメーター
Twilio は action URL へのリクエストとともに、 標準的な TwiML 音声通話リクエスト パラメーター に加え、次のパラメーターを渡します。
| パラメーター | 概要 |
|---|---|
| RecordingUrl | 録音されたオーディオのURLです。 録音ファイルは 'action' コールバックの送信時にはまだアクセスできない可能性があります。 レコーディングがアクセス可能になった時点での確実な通知には、recordingStatusCallbackを使用してください。 |
| RecordingDuration | 録音されたオーディオの長さ（秒単位）です。 無音部分を削除した後の正確な録音の長さの確定値を取得するには、RecordingStatusCallbackを使用してください。 |
| Digits | 指定したキーが押されると、録音を終了します。 |
RecordingUrl へのリクエストは、デフォルトでバイナリ WAV オーディオ フォーマットの録音を返却します。 MP3 フォーマットの録音をリクエストする場合は、RecordingUrl に「.mp3」を追加してください。
method
method 属性は GET または POST の値を取ります。 action URL へのリクエスト送信に、HTTP の GET と POST のどちらを使うかを、Twilio に指示します。 この属性は、HTML フォームの method 属性に従い指定します。初期値は POST です。
Timeout
The 'timeout' attribute tells Twilio to end the recording after a number of seconds of silence has passed. To disable this feature, set 'timeout' to 0. The default is 5 seconds.
finishOnKey
finishOnKey 属性を使うと、押された時に録音を終了するキーを選択できます。 たとえば、finishOnKey に「#」を設定した場合、発信者が「#」を押すと、Twilio は録音を終了し、action URL へのリクエストのパラメーターとして RecordingUrl、RecordingDuration、# を送信します。 許容値は、0 から 9 までの数字キー、「#」キー、「*」キーです。 初期値は「1234567890*#」 です (つまり、どのキーが押されても録音を終了します)。<Gather> とは異なり、finishOnKey の値には複数の文字を指定できます。
In some instances, when using the 'finishOnKey' attribute, the last part of the audio (approximately the one second before the key is pressed) may not be recorded.
maxLength
'maxLength' 属性はレコーディングの最大長を秒数で指定します。 'maxLength' を'30' に指定すると、録音時間が30秒を過ぎると自動的に録音が終了します。 既定値は通常の通話については3600秒（1時間）、テキスト文字化の録音については120秒（2分）です。 <Record>を使用するTwilioクライアント通話は600秒（10分）に制限されています。
playBeep
playBeep 属性には、 録音を開始する前に通知音を鳴らすかどうかを指定できます。 false を指定した場合、通知音は鳴りません。
trim
”trim”属性は音声ファイルから無音部分を探しだします。
"trim"のデフォルトはtrim-silenceです。録音の始めと終わりの無音部分を削除します。
これにより、録音ファイルの分数は通話時間よりも少なくなります。
recordingStatusCallback
'recordingStatusCallback'属性はその引数に相対または絶対URLを取ります。'recordingStatusCallback' URLが与えられた場合、Twilioは録音がアクセス可能になった時点で、指定されたURLにGETまたはPOSTのリクエストを発行します。
リクエストパラメーター
Twilio は、リクエストと以下のパラメーターを「recordingStatusCallback」URL へ転送します。
| パラメーター | 概要 |
|---|---|
| AccountSid | この録音の属するアカウントの一意な識別子です。 |
| CallSid | 録音に関連づけられた通話の一意な識別子です。 |
| RecordingSid | この録音のユニークな識別子です。 |
| RecordingUrl | 録音された音声の URL。 |
| RecordingStatus | The status of the recording. Possible values are: completed, failed. |
| RecordingDuration | この録音の長さ (秒) です。 |
| RecordingChannels | 最終的な録音ファイルのチャンネル数を示す整数です。 <Record>動詞に対しては、1チャンネルのみがサポートされます。 |
| RecordingSource | The initiation method used to create this recording. RecordVerb is returned for recordings initiated via the <Record> verb. |
recordingStatusCallbackMethod
この属性は、「recordingStatusCallback」のリクエスト送信に使う HTTP メソッドを指定します。デフォルトは「POST」です。
recordingStatusCallbackEvent
The recordingStatusCallbackEvent 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: the recording has startedcompleted: the recording is complete and availableabsent:the recording is absent and inaccessible
To specify more than one value, separate each with a space. Default value is: completed.
transcribe
※日本語には対応しておりません。英語のみ対応しています。
transcribe 属性を使って、録音された音声のテキスト化を Twilio に指示できます。 Twilio はこの録音を Twilio の音声テキスト変換エンジンに渡し、音声から文字への変換を試みます。デフォルトでは、transcribe オプションはオフになっています。 トランスクリプションを行わない場合は、transcribe 属性を設定しないでください。
Note: transcription is a paid feature. If you include a transcribe or transcribeCallback attribute on your Record verb, your account will be charged. See the pricing page for our transcription prices.
Additionally, transcription is currently limited to recordings initiated via the TwiML <Record> verb with a duration greater than 2 seconds and less than 120 seconds. If you request a transcription for a recording outside these duration limits, Twilio will write a warning to your debug log rather than transcribe the recording.
transcribeCallback
'transcribeCallback'属性は、'transcribe'属性と組み合わせて使用されます。 これによって、音声文字化の完了時にTwilioが非同期のPOSTリクエストを発行するURLを指定できます。 これはTwiMLのリクエストではなく、そのレスポンスは通話のフローを変更しませんが、リクエストには音声文字化固有のものに加え、標準のTwiMLリクエストパラメーターが含まれます。
transcribeCallback を指定した場合、transcribe=true を指定する必要はありません。 暗黙的に true となります。 transcribeCallback を指定せずに transcribe=true を指定した場合、完成したトランスクリプションは保存され、後で取得できます (REST API の Transcriptions セクションを参照してください) 。ただし、Twilio からユーザーアプリケーションへの非同期の通知は行われません。
The transcribeCallback URL attribute is considered Not PII.
リクエストパラメーター
Twilioは、以下のパラメータを付与して 'transcribeCallback' URL へリクエストを渡します。
| パラメーター | 概要 |
|---|---|
| TranscriptionSid | このトランスクリプションの 34 文字のユニークな ID です。 |
| TranscriptionText | トランスクリプションのテキストの内容です。 |
| TranscriptionStatus | トランスクリプションの結果です。completed または failed になります。 |
| TranscriptionUrl | トランスクリプションの REST API リソースの URL です。 |
| RecordingSid | トランスクリプションの元となった録音の 34 文字のユニークな ID です。 |
| RecordingUrl | トランスクリプションの元となった録音の URL です。 |
| CallSid | Twilio が生成したこの通話のユニークな識別子です。 |
| AccountSid | ユーザーの Twilio アカウント ID です。アカウント ID は 34 文字で、必ず AC から始まります。 |
| From | 発信者(相手側)の電話番号、または クライアント識別子 です。書式は E.164形式 (+で始まり国番号が続く形式) です。 例: +16175551212クライアント識別子は、 client: で始まるURLスキームで、例えば、'tommy' という名前のクライアントからの着信の場合、From パラメータは、client:tommy となります。 |
| To | 発信先の電話番号またはクライアント識別子です。 電話番号は「+」希望に続き国コードが続く形式で指定します。 (例: +16175551212) E.164形式と呼ばれます。 クライアント識別子は client: URIスキームから始まります。 たとえば「joey」というクライアント名に通話を発信するには、Toパラメーターの値はclient:joeyとなります。 |
| CallStatus | この通話のステータスに関する説明です。値は、queued(キューイングされた)、ringing(呼び出し中)、in-progress(通話中)、completed(完了)、busy(相手が通話中)、failed(失敗)、no-answer(相手が不出) のいずれかになります。詳細は、CallStatusセクションをご覧ください。 |
| ApiVersion | この通話の処理に使用する Twilio API のバージョンです。 着信通話では、宛先の電話番号に設定された API バージョンになります。 発信通話では、発信通話の REST API リクエストで使用する API のバージョンになります。 |
| Direction | この通話の方向を示す文字列です。着信通話は inbound、REST API で発信した通話は outbound-api、<Dial> 動詞で発信した通話は outbound-dial となります。 |
| ForwardedFrom | Twilio が転送通話を受けた場合のみ設定されます。ただし、転送情報などの値は、発信者が使用している通信事業者により異なります。 この情報を渡さない通信事業者もあります。 |
ネスティングルール
<Record>の中には、動詞をネストできません。また、すべての動詞の中に <Record> をネストできません。
参考
サンプル
例 1: 録音する
Twilio が <Record> 動詞を実行すると、通知音が鳴り、録音が始まります。 無音の状態が 5 秒を超えたか、発信者が「#」を押した場合、または録音の再長時間が経過した場合、Twilio は RecordingUrl と RecordingDuration パラメーターとともに、HTTP の POST リクエストをデフォルトの action (現在の TwiML 文書の URL) へ送信します。
例 2: ボイスメールを録音する
シンプルなボイスメールの例です。 発信者は、通知音の後にメッセージを録音します。<Record> 動詞は、通知音を鳴らして録音を開始します。最長 20 秒録音できます。
- 発信者が無音のまま 5 秒経過すると
<Record>動詞を抜けて TwiML 文書内の次の動詞へ移ります。 この例では、<Say>動詞へ移ります。 - 発信者が20秒未満発話して、その後5秒間無音状態が続くと、Twilioは「action」URLにGETリクエストを発行します。
<Say>動詞には到達できません。 - 発信者が 20 秒のメッセージを録音し終わると、Twilio は action URL へ GET リクエストを送信します。
<Say>動詞は不達となります。
例 3: 録音のトランスクリプション
Twilio は発信者の声を録音します。 録音が終了すると、Twilio は録音をテキスト化し、この録音のトランスクリプションを含むパラメーターとともに、HTTP の POST リクエストを transcribeCallback URL へ送信します。
ヒントとテクニック
- Twilio は、録音の最初と最後の無音部分を取り除いて、音声ファイルを生成します。 このため、発信者が実際に録音した時間よりも、音声ファイルの再生時間が少し短くなる場合があります。
ヘルプが必要ですか？
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。