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

Example 6: Parallel Calling or Simultaneous Dialing

Parallel calling, also known as simultaneous dialing, is useful when you have several phones (or several people) that you want to ring when you receive an incoming call. Say you have multiple different endpoints where you can take a call, such as a mobile phone, home phone, office phone, and/or PC soft phone. This feature allows you to call up to ten endpoints at the same time by specifying a <Dial> verb with multiple destinations. Additionally, for each endpoint, you can specify which Status Callback events for which you want to receive Webhook requests.

In addition to phone numbers and/or Twilio Client identifiers, you can now specify SIP URIs for parallel calling using the <Dial> verb’s <Sip> noun.

You can mix up to ten different <Sip>, <Number>, or <Client> nouns within a Dial verb to call simultaneously.

Keep in mind that the first call that connects will cancel all the other attempts. If you dial an office phone system or a mobile phone in airplane mode, etc., that endpoint may pick up after a single ring, preventing the other endpoints from ringing long enough for a human to ever answer. Hence you should take care to use simultaneous dialing in situations where you know the behavior of the called parties.

For the example, Alice has three different ways to contact her using SIP. She wants you to ring her on her SIP soft phone, SIP desk phone and SIP mobile client at the same time, and she will pick up one depending on where she is at the time of the call.

Example 7: Serial Calling or Sequential Dialing

Serial calling, also known as sequential dialing, is useful when you have several phones (or several people) that you want to ring in a specific order when you receive an incoming call. Say you have a group of agents in a call center, and you want to try each of them in order until one of them picks up. This feature allows you to call up to ten agents sequentially by specifying a <Dial> verb with multiple destinations, and setting the sequential attribute to true. The priority of the calls is based on the order within the <Dial> verb. Additionally, for each endpoint, you can specify which Status Callback events you want to receive via Webhooks.

You can mix up to ten different <Sip>, <Number>, or <Client> nouns within a <Dial> verb to call sequentially.

Keep in mind that the first call that connects will cancel all the remaining attempts in the sequence. If you dial an office phone system or a mobile phone in airplane mode, etc., that endpoint may pick up after a single ring, preventing the remaining endpoints from being called. Hence you should take care to use sequential dialing in situations where you know the behavior of the called parties.

For the example below, if Alice rejects or does not answer then the call will go to Bob. Similarly if Bob rejects or does not answer then the call will go to Charlie. If Charlie does not answer, the call will fail.