TwiML™ Voice: <Sip>

<Dial>動詞の<Sip>名詞を使うことで、SIP (Session Initiation Protocol) を用いた VoIP通信がが可能になります。 この機能より、SIPエンドポイントへ音声通話を架けることができます。<Dial>動詞の中で<Sip>名詞を用いたTwiMLを、お持ちのTwilio電話番号に着信した際に呼ばれるTwiMLに盛り込んでみましょう。あまりSIPに詳しくない方、あるいは、TwilioがあなたのSIPエンドポイントへどのように働きかけるかの詳細情報については、SIPの概要を参照してください。

SIPセッション

SIP INVITEメッセージには、APIバージョンと、その通話の AccountSid、CallSid が含まれます。カスタムSIPヘッダーを含んだINVITEメッセージを通すためには、Twilioの設定をします。オプションとして、シグナリングの制御や認証を制御するためのパラメータを与えることもできます。

ひとつのSIPセッションが完了すると、動詞のアクションURLにリクエストをかけますが、この時 Twilio は一般的な<Dial>パラメータと同様、 <Dial>この時 SIP CallIDヘッダー、INVITEに対する応答コード、SIPの最終応答に対するXヘッダー群 を渡します。

現在のところ、<Dial>動詞1つに対し、1つの<Sip>名詞が利用できます。そして、INVITEメッセージは1つのSIPエンドポイントにのみ送ることができます。また、SIPを使った<Dial>の中では、他の名詞(例えば <Number>、<Client>など) を追加することはできません。もし他の名詞を使いたい場合、<Dial>動詞でコールバックさせることで、他のメソッドが使えるようにします。

regionパラメーター

Twilioがお客様の通信インフラに対して送信するSIP-outトラフィックの地理的リージョンを指定するには、SIP URIにregionを含めることが必要です。 たとえば、region=ie1パラメーターがSIP URIに含まれる場合、TwilioはSIPトラフィックをヨーロッパのアイルランドリージョンから送信します。

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:alice@example.com;region=ie1</Sip>
    </Dial>
</Response>

regionパラメーターが指定されない場合、TwilioはSIP-outトラフィックを北米ヴァージニアリージョンから送信します。

Sip名詞を使う

全ての<Dial>動詞のパラメータ(record, timeout, hangupOnStar など)は、<Sip>名詞と一緒に利用できます。SIP通話においては、callerId 属性は、必ずしも認証済み電話番号である必要はありません。任意の半角文字列を指定できます。記号は +-_. を利用できますが、スペースは利用できません。

<Sip>名詞の中では、Twilio を用いて接続するための接続先 URI を指定する必要があります。URI は 255文字以内の有効なSIP URLを指定します。

例:

認証

あなたのSIPインフラへの認証情報は、<Sip>名詞の username および password 属性を使います。

たとえば、次のようになります。

カスタムヘッダー

カスタムヘッダーについては、SIP URI へ付加します。

例:

While the SIP URI itself must be under 255 chars, the headers must be under 1024 characters. Any headers starting with the x- prefix can be sent this way.

Transport

SIP URIにパラメーターをセットし、どの転送プロトコルを使用したいか指定します。 現時点では、UDP、TCP、そしてTLSのみ指定できます。 既定では、TwilioはUDPを通じてSIP INVITEを送信します。 transportパラメーターを使用するとこれを変更できます。

代わりに、SIPのシグナリングにTLSを使用するようカスタマイズすることができます。 TLSを使用すると、既定のポートは5061となりますが、他のものも指定できます。

属性

この名詞<Sip>は振る舞いを変更する属性をサポートします。

url

The url attribute allows you to specify a url for a TwiML document that runs on the called party's end, after they answer, but before the two 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 です。

コールスクリーニング HTTPパラメータ

音声通話の成立時、Twilioはリクエストに加えて以下のパラメータをスクリーニングURLへ渡します。(この時、一般的なTwiMLの音声通話リクエストパラメータも渡されます)

Dialアクション HTTPパラメータ

SIP通話試行に応じてアプリケーションの挙動を可変させるような場合、これらのアクションコールバックパラメータを使いましょう。

statusCallbackEvent

<Dial>を使ってClientに発信した時、アウトバウンドコールが開始されます。initiatedからringingへのコール遷移は、電話が鳴り始めた時起こります。answeredは受話した時に、最後に通話が終わった時にcompletedへと遷移します。statusCallbackEventと共に、異なったコールプログレスイベントのwebhook を受け取ることができます。initiated、ringing、answered、completedをそれぞれ受け取ることができます。

statusCallbackEvent属性はTwilioがどのイベントを webhook するべきかを認めます。複数のイベントを指定する際は右記の通りスペースで区切ります。 : initiated ringing answered completedstatusCallbackあり、ステータスコールバックイベントが特定されない場合、completedイベントがデフォルトで送信されます。

一報APIを通じてアウトバウンドコールが生成されるとき、<Dial>を使ってアウトバウンドコールはすぐさま開始され、キュー(queue)に入ることがありません。下記の返却されうるコールイベントのタイムラインです。異なるコールステータスが<Dial>レグ(leg)で発生します。

statusCallback

statusCallback属性は、statusCallbackEvent属性で指定されたおのおののイベントに対してWebhookリクエストを送信するためのURLを指定できます。 相対URL以外では、有効なホスト名を指定しなければなりません（アンダースコアは使用できません）。

statusCallbackMethod

statusCallbackMethod属性では、TwilioがstatusCallback属性で与えられたURLにアクセスする際に、どのHTTPメソッドを用いるかを指定します。デフォルトは POST です。

Status Callback HTTP パラメーター

TwilioがTwilio番号の一つのコールを受信した時、Twilioがアプリケーションに渡すStatusCallbackに送信される非同期のリクエスト中のパラメーターはTwiML検索するために非同期のリクエストにパラメーターを含めます。全てのリストと詳細はTwiML Voiceリクエストドキュメントをご覧ください。

コールプログレスイベントが発動された時、コールバックリクエストは、この他にも次のパラメーターを渡します。

サンプル

例1: SIPエンドポイントへの発信

この例では、kate@example.com へSIP発信してみます。Kate と音声通話を成立させるためには、<Dial>動詞を使い、中に <Sip>名詞をネストします。

例2: 認証が必要なSIPエンドポイントへの発信

この例は、先ほどと同様に Kate へ発信しますが、この際にSIP認証が必要な場合のケースです。

例3: ヘッダーを渡す

SIPアドレスにカスタムヘッダーを渡す例です。

例4: 様々な属性を与えてDialする

A more complex Dial, specifying custom settings as attributes on <Dial>, including call screening.

例 5：コールプログレスイベント

この例では、<Dial> で SIP エンドポイントにダイヤルするときに、コールプログレスイベントが発生するたびに webhook を受け取ります。