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ヘッダー群 を渡します。
If Enhanced Programmable SIP Features is not enabled on your account, only one <Sip>
noun may be specified per <Dial>
, and the INVITE message may be sent to only one SIP endpoint. Also, you cannot add any other nouns (eg <Number>
, <Client>
) in the same <Dial>
as the SIP. If you want to use another noun, set up a callback on the <Dial>
to use alternate methods.
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&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&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:
パラメーター | 値 |
---|---|
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 を受け取ることができます。initiated
、ringing
、answered
、completed
をそれぞれ受け取ることができます。
statusCallbackEvent
属性はTwilioがどのイベントを webhook するべきかを認めます。複数のイベントを指定する際は右記の通りスペースで区切ります。 : initiated ringing answered completed
statusCallback
あり、ステータスコールバックイベントが特定されない場合、completed
イベントがデフォルトで送信されます。
一報APIを通じてアウトバウンドコールが生成されるとき、<Dial>
を使ってアウトバウンドコールはすぐさま開始され、キュー(queue)に入ることがありません。下記の返却されうるコールイベントのタイムラインです。異なるコールステータスが<Dial>
レグ(leg)で発生します。
イベント | 概要 |
---|---|
initiated | Twilioがダイヤリングを始めた時、initiated イベントが発動します。 |
ringing | 電話が鳴り始めると、ringing イベントが発動します。 |
answered | 通話を開始(受話)するとanswered イベントが発動します。 |
completed | completed イベントは端末の状態に関係なく(busy 、canceled 、completed 、failed 、no-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> で設定されている場合に追加され、その他の手段で開始された録音には含まれません。 RecordingUrl は completed イベント内にのみ存在します。 |
RecordingSid | この通話から発生した録音の一意なIDRecordingSid はcompleted のイベントでのみ発生します。 |
RecordingDuration | 録音されたオーディオの長さ (秒) です。 RecordingDuration は completed イベント内にのみ存在します。 無音部分を削除した後の正確な録音の長さの確定値を取得するには、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 Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.