メニュー

Expand
ページを評価:

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.

                                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:

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

                                <Sip> 属性

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

                                属性名 許容値 初期値
                                method GET, POST POST
                                password SIP認証のためのパスワード
                                statusCallbackEvent initiated, ringing, answered, completed none
                                statusCallback すべての URL none
                                statusCallbackMethod GET, POST POST
                                url コールスクリーニングURL none
                                username 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 を受け取ることができます。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 を受け取ります。

                                                              
                                                              
                                                              

                                                              In order to use the SIP Parallel Calling Twilio feature, you must enable the "Enhanced Programmable SIP Features" in your Voice settings in the Console.

                                                              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.

                                                                    
                                                                    
                                                                    

                                                                    In order to use the SIP Serial Calling Twilio feature, you must enable the "Enhanced Programmable SIP Features" in your Voice settings in the Console.

                                                                    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.

                                                                          
                                                                          
                                                                          
                                                                          ページを評価:

                                                                          ヘルプが必要ですか?

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

                                                                                
                                                                                
                                                                                

                                                                                フィードバックくださりありがとうございます!

                                                                                We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

                                                                                Sending your feedback...
                                                                                🎉 Thank you for your feedback!
                                                                                Something went wrong. Please try again.

                                                                                Thanks for your feedback!

                                                                                Refer us and get $10 in 3 simple steps!

                                                                                ステップ1

                                                                                Get link

                                                                                Get a free personal referral link here

                                                                                ステップ2:

                                                                                Give $10

                                                                                Your user signs up and upgrade using link

                                                                                ステップ3

                                                                                Get $10

                                                                                1,250 free SMSes
                                                                                OR 1,000 free voice mins
                                                                                OR 12,000 chats
                                                                                OR more