Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

メニュー

Expand
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セッション

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 所在地
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.

                    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にパラメーターをセットし、どの転送プロトコルを使用したいか指定します。 現時点では、UDPTCP、そして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:

                                パラメーター
                                Called To header of the SIP Invite message. The SIP identifier of the called party.
                                caller From header of the SIP Invite message. The SIP identifier of the party that initiated the call.
                                SipCallId 相手先SIPエンドポイントへ渡す SIP Call ID。
                                SipDomain The host part of the SIP request.
                                SIPドメイン SID Your SIP Domain ID. It is 34 characters long, and always starts with the letters SD.
                                SipHeader_ The name/value of any X-headers returned in the 200 response to the SIP INVITE request. This is applicable only if you are using SIP custom headers.
                                SipSourceIp Source IP address for SIP signaling.

                                <Sip> 属性

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

                                属性名 許容値 初期値
                                action 相対または絶対 URL なし
                                method GET, POST POST
                                password SIP認証のためのパスワード
                                statusCallbackEvent initiated, ringing, answered, completed none
                                statusCallback すべての URL none
                                statusCallbackMethod GET, POST POST
                                url コールスクリーニングURL none
                                username SIP認証のためのユーザ名

                                action

                                In addition to dial action parameters the below parameters are support for SIP call. Use the action callback parameters to modify your application based on the results of the SIP dial attempt:

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

                                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 を受け取ることができます。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以外では、有効なホスト名を指定しなければなりません(アンダースコアは使用できません)。

                                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リクエストを生成し、同じ順番の到着は保証されません。

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

                                                              
                                                              
                                                              
                                                              
                                                              Rate this page:

                                                              ヘルプが必要ですか?

                                                              誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。