TwiML™ 音声通話:レスポンス

Twilio 番号のいずれかに通話が着信すると、Twilio はその番号に設定された URL へ、HTTP リクエストを送信します。このリクエストへのアプリケーションのレスポンスの中で、この通話をどのように処理するかを Twilio に指示できます。

HTTP クライアントとしての Twilio

URL へ HTTP リクエストを送信する際、Twilio は通常のウェブ ブラウザと同じように振る舞います。

  • Cookie : Twilio は通常のウェブ ブラウザと同じように、HTTP cookie を受信し、リクエストに追加します。
  • リダイレクト : Twilio は通常のウェブ ブラウザと同じように、HTTP リダイレクト (HTTP ステータス コード 301、307 など) をサポートします。
  • キャッシュ : Twilio は、HTTP ヘッダーでキャッシュが有効になっている場合 (ETag と Last-Modified ヘッダー)、および HTTP のメソッドが GET の場合、通常のウェブ ブラウザと同じように、ファイルをキャッシュします。

MIME Type に対応

Twilio はユーザー アプリケーションのレスポンスの MIME Type に応じて異なる動作をします。

MIME Type 動作
text/xml, application/xml, text/html Twilio は返却された文書を XML の命令のセット (TwiML と呼ぶことにします) として解釈します。 詳細は TwiML インタープリター セクションを参照してください。 これは最もよく使われるレスポンスです。
various audio types Twilio は発信者に向けて音声ファイルを再生し、通話を終了します。 サポートする MIME Type については、 <Play> のドキュメントを参照してください。
text/plain Twilio は発信者に向けてテキストの内容を読み上げ、通話を終了します。

Twilio の TwiML インタープリター

Twilio のリクエストに対してユーザー アプリケーションが XML で応答すると、Twilio は TwiML インタープリターでユーザ-の文書を実行します。 しくみをシンプルに保つために、TwiML インタープリターは、特別に命名された少数の XML 要素のみを解釈します。 TwiML では、これらの要素は 3 つのグループに分けられます。ルートの <Response> 要素動詞名詞です。 それぞれのグループについて説明します。

インタープリターは、ユーザーの TwiML 文書の先頭から開始し、上から順番に命令を実行 (動詞) します。 たとえば、次の TwiML のコードは、発信者に向けて「Hello World」とテキストを読み上げた後、Cowbell.mp3 を再生し、通話を終了します。

<?xml version="1.0" encoding="UTF-8" ?>  
<Response> 
    <Say>Hello World</Say>
    <Play>https://api.twilio.com/Cowbell.mp3</Play>
</Response>

TwiML 要素名 (動詞と名詞) では、大文字と小文字は区別されます。 たとえば、<Say> ではな <say> とした場合、結果はエラーになります。 属性名も大文字と小文字を区別し、キャメルケースを使用 (camelCased) しています。 XML コメントは自由に入れられます。インタープリターで無視されます。

<Response> 要素

<Response> 要素は、Twilio の XML マークアップのルート要素です。 Twilio のリクエストに対する TwiML レスポンスでは、必ずすべての動詞をこの要素の中にネストします。 それ以外の構造は無効となります。

例 :
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hello</Say>
</Response>

TwiML 動詞

TwiML 文書の XML 要素のほとんどは、TwiML 動詞です。 動詞の名前は大文字と小文字を区別し、属性名も同様です。 TwiML 音声通話の動詞には、コアとなる 6 つのプライマリ動詞と、4 つのセカンダリ動詞しかありません。それぞれに詳細なドキュメントが用意されています。 6 つのコアとなる動詞は次の通りです。

  • <Say>: 発信者にテキストを読み上げます。
  • <Play>: 発信者に音声ファイルを再生します。
  • <Record>: 通話や通話の一部を録音します。
  • <Gather>: 発信者がダイヤルした数字を取得します。
  • <Dial>: 相手の電話番号またはカンファレンスに電話をかけ、発信者を接続します。
  • <Sms>: 通話中に SMS メッセージを送信します。

制御フローが別の文書に移ったために、TwiML インタープリターが TwiML 文書内の動詞に到達しない場合がありますので、注意してください。 通常は、動詞の action 属性を設定している場合に起こります。 たとえば、<Say> 動詞の後に <Sms> ともう 1 つの <Say> が続いており、<Sms> に action URL を設定している場合、2 番目の <Say> は不達となります。 この場合、コールフローは、action URL リクエストに対するアプリケーションのレスポンスとして受信した TwiML に従って進みます。

制御フローに関係する動詞は、 <Gather><Record><Dial><Sms><Redirect><Hangup><Reject>です。

TwiML 名詞

TwiML の名詞とは、動詞の中にネストされた、それ自身が動詞ではないものすべてを指します。 動詞が動作を行う対象です。 通常は、単純なテキストです。 ただし、 <Dial> に使う <Number><Conference> 名詞のように、ネストされた XML 要素の場合もあります。

ステータス・コールバック

Status callbacks do not control call flow, so TwiML does not need to be returned. If you do respond, use status code 204 No Content or 200 OK with Content-Type: text/xml and an empty <Response/> in the body. Not responding properly will result in warnings in Debugger.