TwiML™ Voice： <SIP>

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

SIPセッション

The SIP INVITE message includes the API version, the AccountSid, and CallSid for the call. Optionally, you can also provide a set of parameters to manage signaling transport and authentication, or configure Twilio to pass custom SIP headers in the INVITE message: this method includes headers such as UUI (User-to-user Information).

ひとつの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.

You can also send multiple parameters and values as part of the x- header

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:jack@example.com?x-customname=Madhu%2CMathiyalagan%3BTitle%3DManager&amp;x-myotherheader=bar</Sip>
    </Dial>
</Response>

UUI (User-to-User Information) header can be sent without prepending x-

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:jack@example.com?User-to-User=123456789%3Bencoding%3Dhex&amp;x-myotherheader=bar</Sip>
    </Dial>
</Response>

Transport

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

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

<Sip> Call parameters

When a SIP call is answered, Twilio passes the following parameters with its request in addition to the standard TwiML Voice request parameters:

Additional parameters

When you invoke dial action attribute and <Sip>, Twilio passes the following parameters with its request in addition to the standard dial action parameters. Use the action callback parameters to modify your application based on the results of the SIP dial attempt:

<Sip> 属性

この名詞<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 です。

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以外では、有効なホスト名を指定しなければなりません（アンダースコアは使用できません）。

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

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

statusCallbackMethod

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

サンプル

例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 を受け取ります。