メニュー

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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 所在地
us1 北米 ヴァージニア
us2 北米 オレゴン
ie1 欧州 アイルランド
de1 欧州 フランクフルト
sg1 アジア太平洋 シンガポール
jp1 アジア太平洋 東京
br1 South America São Paulo
au1 アジア太平洋 シドニー

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

Sip名詞を使う

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

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

例:

        
        
        
        

        認証

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

        属性名
        username SIP認証のためのユーザ名
        password SIP認証のためのパスワード

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

              
              
              
              

              カスタムヘッダー

              カスタムヘッダーについては、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にパラメーターをセットし、どの転送プロトコルを使用したいか指定します。 現時点では、UDPTCP、そしてTLSのみ指定できます。 既定では、TwilioはUDPを通じてSIP INVITEを送信します。 transportパラメーターを使用するとこれを変更できます。

                          
                          
                          
                          

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

                                
                                
                                
                                

                                属性

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

                                属性名 許容値 初期値
                                url コールスクリーニングURL none
                                method GET, POST POST
                                statusCallbackEvent initiated, ringing, answered, completed none
                                statusCallback すべての URL none
                                statusCallbackMethod GET, POST POST

                                url

                                url属性は、発信者側の端末で動作させる TwiML へのURL を指定し、相手が応答し、かつ、二者間が接続される前に実行されます。このTwiML では <Play><Say> を使って発信先へ何か情報を発信したり、<Gather><Hangup> を用いて、受信者側に通話を拒否できる機会を設けることができます。発信者は、受信者側で TwiML が実行し終わるまで、呼び出し中の音が聞こえることになります。この形態で実行される TwiML には <Dial>動詞を中に含めることはできません。

                                method

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

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

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

                                属性名
                                SipCallId 相手先SIPエンドポイントへ渡す SIP Call ID。
                                SipHeader SIP INVITEリクエストに対してコード200のレスポンスが得られた全Xヘッダーの名前と値。

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

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

                                属性名
                                DialSipCallId 相手先SIPエンドポイントへ渡す SIP Call ID。
                                DialSipResponseCode INVITE に対するSIPレスポンスコード。
                                DialSipHeader_ SIP INVITE の最終応答コードとして返された全ての Xヘッダーの名前と値。

                                statusCallbackEvent

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

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

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

                                アウトバウンドダイアルコールイベントダイヤグラム

                                イベント 概要
                                initiated Twilioがダイヤリングを始めた時、initiatedイベントが発動します。
                                ringing 電話が鳴り始めると、ringingイベントが発動します。
                                answered 通話を開始(受話)するとansweredイベントが発動します。
                                completed completedイベントは端末の状態に関係なく(busycanceledcompletedfailedno-answer)コールが終了した時に発動します。 StatusCallbackEventが指定されない場合、completedがデフォルトで発動されます。

                                statusCallback

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

                                statusCallbackMethod

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

                                Status Callback HTTP パラメーター

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

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

                                パラメーター 概要
                                CallSid Twilio が生成したこの通話のユニークな識別子です。CallSidは新しい TwiML URLと共に Call/{CallSid}をPOSTし、チャイルドコールを修正することができます。
                                ParentCallSid 親コールを一意に特定する識別子
                                CallStatus このコールのステータス詳細取りうる値は queued(キューに入った), initiated(処理が開始された), ringing(呼び出し中), in-progress(通話中), busy(話し中), failed(失敗), no-answer(電話に出ず) です。詳細はコールのステータス セクションをご覧ください
                                CallDuration 通話の秒数completedのイベントにのみ現れます。
                                RecordingUrl 音声通話の録音済みオーディオのURLです。 このパラメーターは録音が <Dial> で設定されている場合に追加され、その他の手段で開始された録音には含まれません。 RecordingUrlcompleted イベント内にのみ存在します。 
                                RecordingSid この通話から発生した録音の一意なIDRecordingSidcompletedのイベントでのみ発生します。
                                RecordingDuration 録音されたオーディオの長さ (秒) です。 RecordingDurationcompleted イベント内にのみ存在します。 無音部分を削除した後の正確な録音の長さの確定値を取得するには、RecordingStatusCallbackを使用してください。
                                Timestamp このイベントが生成された日付の UTC 表記です。RFC 2822フォーマットを使用します。
                                CallbackSource webhookのソースを記述する文字webhookがなぜ発生したか曖昧さの排除に役立ちます。Status Callback では、値は常にcall-progress-eventsです。
                                SequenceNumber イベントが発動する順番は、0から始まります。イベントが順々に発動すると、分離されたHTTPリクエストを生成し、同じ順番の到着は保証されません。

                                サンプル

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

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

                                      
                                      
                                      
                                      

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

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

                                            
                                            
                                            
                                            

                                            例3: ヘッダーを渡す

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

                                                  
                                                  
                                                  
                                                  

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

                                                  <Dial>動詞の属性を与えた少し複雑な例です。コールスクリーニングや、プロトコルをTCPに変える設定も加わっています。

                                                        
                                                        
                                                        
                                                        

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

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

                                                              
                                                              
                                                              
                                                              

                                                              ヘルプが必要ですか?

                                                              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.