Twilio との接続ガイド

お申し込みと、接続に使う情報のやりとり

お申し込み後に、クラコールから接続に使う情報をお渡しします。お客様からは、Twilio 側の情報をお知らせください。

お問い合わせの本文に「BYOC 接続」とお書きのうえ、お送りください。BYOC では、着信・発信とも、INVITE の宛先（Request-URI）・To・From の電話番号を +81 から始まる E.164 形式にしてください（例：03-1234-5678 → +81312345678）。

BYOC Trunk を作り、発信先にクラコールを登録する

Twilio の BYOC Trunking（Elastic SIP Trunking ではありません）で、次の3つを順に作ります。トランク（BYOC Trunk）は1つだけ作ってください。

• Origination Connection Policy（発信先の設定）：Twilio からクラコールへの発信先をまとめるものです。
• Origination URI（API では Target）：お客様専用のドメインを登録します。Priority・Weight・Enabled の項目もあります。
• BYOC Trunk：上の発信先の設定（ConnectionPolicySid）と、着信の受け側（VoiceUrl）を結びつけます。

Twilio の API で作る場合の例です（認証は環境変数から読みます）。

ターミナル（curl）：1. 発信先の設定（Origination Connection Policy）を作る

curl -X POST "https://voice.twilio.com/v1/ConnectionPolicies" \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

ターミナル（curl）：2. 発信先にクラコール（お客様専用のドメイン）を登録する

curl -X POST "https://voice.twilio.com/v1/ConnectionPolicies/NYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/Targets" \
  --data-urlencode "Target=sip:xyz.customer.clocall.jp" \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

ターミナル（curl）：3. BYOC Trunk を作る（発信先の設定と、着信の受け側を結びつける）

curl -X POST "https://voice.twilio.com/v1/ByocTrunks" \
  --data-urlencode "FriendlyName=clocall" \
  --data-urlencode "ConnectionPolicySid=NYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "VoiceUrl=https://example.com/twilio/voice" \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

• $TWILIO_ACCOUNT_SID・$TWILIO_AUTH_TOKEN：Twilio のアカウント SID と認証トークンを入れた環境変数です（コマンドに直接書かないでください）。
• NYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx：1.の応答に入っている NY で始まる SID です。
• Target：sip: で始めます（sips: には対応していません）。xyz.customer.clocall.jp は例です。手順1でお渡しするドメインに置き換えてください。
• VoiceUrl：着信を受けたときに Twilio が呼び出す、お客様のアプリの URL（Webhook）です。通話の扱いを TwiML で指示します。Console では Application Configuration の A Call Comes In にあたります。
• 3.の応答に入っている BY で始まる SID（BYOC Trunk の SID）は、手順4の発信で使います。
• Twilio CLI でも作れます：twilio api:voice:v1:connection-policies:create、twilio api:voice:v1:connection-policies:targets:create、twilio api:voice:v1:byoc-trunks:create

Twilio は、BYOC の発信でユーザー名・パスワードによる認証に対応していません。クラコールも、ユーザー名・パスワードによる認証は使いません。認証は、お客様専用のドメインと発信者番号（caller ID）で行います。

着信の設定：クラコールの SBC から受ける口を作る

手順2の BYOC Trunk に、着信を受けるドメイン（Termination SIP Domain）を結びつけます。Twilio の Console で、次の順に進めます。

1. Voice > BYOC Trunks で、手順2のトランクを開きます（新しく作らないでください）。
2. Termination SIP Domains で、ドメインを選ぶか、横の「+」で新しく作ります。
3. Termination SIP URI を決めます。東京（Asia Pacific Tokyo）の URI は {example}.sip.jp1.twilio.com の形です（{example} の部分はお客様が決める名前です）。
4. IP Access Control Lists（許可リスト）に、手順1の SBC の IP アドレスをすべて登録します（CIDR 形式の CIDR Network Address で入れます）。クラコールは、パスワード（Credentials Lists）は使いません。

音声の形式は G.711 μ-law（PCMU）です。

発信の設定：BYOC Trunk を指定して、クラコール経由でかける

発信では、かけるたびに手順2の BYOC Trunk（BY で始まる SID）を指定します。指定すると、そのトランクの発信先（お客様専用のドメイン）へ送られ、クラコールの SBC から日本の電話へつながります。指定しないと、Twilio の通常の回線から発信され、クラコールを通りません。

どちらの方法でも、指定するのは2つです。BYOC Trunk（クラコールを通すため）と、発信者番号（相手に表示される、お客様のクラコールの番号）です。

TwiML：<Dial> の callerId で発信者番号、<Number> の byoc で BYOC Trunk を指定する

<Response>
  <Dial callerId="+81312345678">
    <Number byoc="BYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">+81355550000</Number>
  </Dial>
</Response>

ターミナル（curl）：Calls API の From で発信者番号、Byoc で BYOC Trunk を指定する

# Byoc に手順2の BYOC Trunk の SID を入れると、クラコール経由で発信されます
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \
  --data-urlencode "Byoc=BYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "From=+81312345678" \
  --data-urlencode "To=+81355550000" \
  --data-urlencode "Url=https://example.com/twiml" \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

• BYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx：手順2で作った BYOC Trunk の SID です。
• callerId（TwiML）・From（Calls API）：発信者番号です。お客様のクラコールの番号（例：+81312345678）を入れます。クラコールへ送られる SIP の From ヘッダーに入り、クラコールはこの番号で発信を認証します。P-Asserted-Identity には対応していません。
• TwiML で callerId を省くと、Twilio は元の通話の番号を発信者番号に使います。クラコールの番号にならないと発信は拒否されるため、必ず指定してください。
• Twilio では、発信者番号に使えるのは Twilio で買った番号か、Twilio で確認（Verified Caller IDs）した番号です。クラコールの番号は、下の「番号認証」で先に確認してください。
• <Number> の中・To（宛先番号）：かける相手の番号（例：+81355550000）。どちらも +81 から始まる E.164 形式にしてください。
• Url：通話が始まったあとの指示（TwiML）を返す、お客様のアプリの URL です。

つながることを確認する

• 着信：クラコールの電話番号へ携帯電話などからかけ、お客様のアプリ（VoiceUrl）に電話が届くことを確認します。
• 発信：手順4の方法で携帯電話などの日本の番号へかけ、電話が鳴ること、相手に発信者番号（+81 から始まる E.164 形式）が表示されることを確認します。
• 両方の向きで、相手の声が聞こえることを確認します。