setup-sip-trunk

Bolna SIP トランク（BYOT）

標準に準拠した任意の SIP トランク（Twilio Elastic SIP、Plivo Zentrunk、Telnyx、Vonage、Zadarma、DIDWW、または独自のキャリア）を使用して、Bolna エージェントが処理する着信と発信の両方に対応できます。

ベータ版。 SIP トランキングにはエンタープライズアクセスが必要です。コードを変更する前に、API 呼び出しでアクセスエラーが返される場合は [email protected] までお問い合わせください。

BYOT を利用する理由

理由	詳細
既存のキャリアとの関係を維持できます	番号ポーティングは不要で、請求も別途発生しません。
交渉済みの料金	Bolna が通話時間に上乗せ料金を請求することはありません。
番号ポータビリティ	すでに所有している番号を利用できます。
コンプライアンス／地域キャリア	現地の規制により特定のキャリアが義務付けられている場合に必要です。

概要フロー

1. Provider portal:    Whitelist 13.200.45.61, set origination URI to sip.bolna.ai
2. POST /sip-trunks/trunks                       → create trunk in Bolna
3. POST /sip-trunks/trunks/{id}/numbers          → register your DIDs on the trunk
4. PATCH /v2/agent/{id} telephony_provider=sip-trunk   (for outbound)
5. POST /inbound/setup                           → link DID ↔ agent (for inbound)
6. POST /call with from_phone_number = your DID  → outbound dial

ステップ 0 — SIP プロバイダーのポータルでの設定

Bolna の IP を許可リストに登録する

13.200.45.61

これをプロバイダーの許可 IP／ACL／信頼済み IP リストに追加してください。追加しない場合、Bolna の発信 INVITE パケットと RTP パケットが破棄されます。

ip-based 認証では、これはトランクが Bolna を識別するための IP でもあります。

オリジネーション URI を設定する（着信の場合）

トランクのトランスポート	オリジネーション URI
UDP または TCP	sip:sip.bolna.ai:5060
TLS	sip:sip.bolna.ai:5061;transport=tls

プロバイダーが IP アドレスしか受け付けない場合は、UDP/TCP では sip:13.200.45.61:5060 を使用してください。TLS による着信では、キャリアが Bolna の TLS 証明書を検証できるよう、ホスト名が必要です。

プロバイダーに応じて、DID ごと、またはトランク全体に設定してください。

コーデック

デフォルトでは G.711 ulaw を使用します。少なくとも ulaw を許可し（できれば alaw も許可してください）、G.729 などの圧縮コーデックは避けてください。

エンドポイント

メソッド	パス	用途
POST	/sip-trunks/trunks	トランクを作成する
GET	/sip-trunks/trunks	トランクの一覧を取得する
GET	/sip-trunks/trunks/{trunk_id}	トランクを 1 つ取得する
PATCH	/sip-trunks/trunks/{trunk_id}	トランクを更新する
DELETE	/sip-trunks/trunks/{trunk_id}	トランクを削除する
POST	/sip-trunks/trunks/{trunk_id}/numbers	DID を追加する
GET	/sip-trunks/trunks/{trunk_id}/numbers	DID の一覧を取得する
DELETE	/sip-trunks/trunks/{trunk_id}/numbers/{phone_number_id}	DID を削除する
POST	/inbound/setup	DID の phone_number_id をエージェントに紐付ける
POST	/inbound/unlink	紐付けを解除する

すべてのパスのベース URL は https://api.bolna.ai です。認証には Authorization: Bearer $BOLNA_API_KEY を使用します。

設定例：Twilio Elastic SIP（userpass）

curl -X POST https://api.bolna.ai/sip-trunks/trunks \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Twilio Production",
    "provider": "twilio",
    "description": "Main Twilio Elastic SIP trunk",
    "auth_type": "userpass",
    "auth_username": "<your-sip-username>",
    "auth_password": "<your-sip-password>",
    "gateways": [
      { "gateway_address": "your-trunk.pstn.twilio.com", "port": 5060, "priority": 1 }
    ],
    "transport": "transport-udp",
    "allow": "ulaw,alaw",
    "disallow": "all",
    "inbound_enabled": true,
    "outbound_leading_plus_enabled": true
  }'

レスポンスにはトランクの id が含まれます。保存してください。

設定例：Plivo Zentrunk（ip-based）

curl -X POST https://api.bolna.ai/sip-trunks/trunks \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plivo Zentrunk",
    "provider": "plivo",
    "auth_type": "ip-based",
    "gateways": [
      { "gateway_address": "21467306465797919.zt.plivo.com", "port": 5060, "priority": 1 }
    ],
    "ip_identifiers": [
      { "ip_address": "15.207.90.192/31" },
      { "ip_address": "204.89.151.128/27" },
      { "ip_address": "13.52.9.0/25" }
    ],
    "transport": "transport-udp",
    "inbound_enabled": true
  }'

ip_identifiers はキャリアの送信元 IP です。Plivo、Telnyx などが公開しています。

設定例：TLS + SDES（メディアの暗号化）

シグナリングとメディアの暗号化に対応したキャリアでは、次のように設定します。

curl -X POST https://api.bolna.ai/sip-trunks/trunks \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Twilio Production (encrypted)",
    "provider": "twilio",
    "auth_type": "userpass",
    "auth_username": "<u>",
    "auth_password": "<p>",
    "gateways": [
      { "gateway_address": "your-trunk.pstn.twilio.com", "port": 5061, "priority": 1 }
    ],
    "transport": "transport-tls",
    "media_encryption": "sdes",
    "media_encryption_optimistic": false,
    "inbound_enabled": true
  }'

設定項目	内容
transport: "transport-tls"	SIP シグナリングを暗号化します。ポートは 5061 です。
media_encryption: "sdes"	SDP でキーを交換する SRTP です。TLS トランスポートが必要です。
media_encryption_optimistic: true	キャリアが暗号化を提供しない場合、平文の RTP にフォールバックします。テストに便利です。

キャリア側でも SDES/SRTP が有効になっている必要があります。有効でない場合、SIP 通話は確立しますがメディアは確立されず、無音の通話になります。

トランクに DID 番号を追加する

curl -X POST "https://api.bolna.ai/sip-trunks/trunks/$TRUNK_ID/numbers" \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "919876543210",
    "name": "Mumbai Support Line"
  }'

レスポンスには phone_number_id が含まれます。着信の紐付けに使用する ID です。保存してください。 Bolna は番号の文字列をそのまま保存します。照合時には + の有無を許容しますが、表記を統一してください。

トランクから発信する

Bolna がトランク経由でルーティングするよう、エージェントにパッチを適用します。

curl -X PATCH "https://api.bolna.ai/v2/agent/$AGENT_ID" \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_config":{"telephony_provider":"sip-trunk"}}'

その後、通常どおり通話を発信します。from_phone_number には、トランクに登録済みの DID を指定する必要があります。

curl -X POST https://api.bolna.ai/call \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'$AGENT_ID'",
    "recipient_phone_number": "+918800001234",
    "from_phone_number": "+919876543210"
  }'

トランクへの着信を受ける

DID を登録した後、エージェントに紐付けます。

curl -X POST https://api.bolna.ai/inbound/setup \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'$AGENT_ID'",
    "phone_number_id": "'$PHONE_NUMBER_ID'"
  }'

Bolna は、SIP 経由でルーティングされる通話に関する Asterisk の要件に合わせて、エージェントの音声形式を自動的に ulaw に設定します。

1 つの番号につき 1 つのエージェントです。 DID を新しいエージェントに再紐付けすると、以前のエージェントとの紐付けは自動的に解除されます。再紐付けせずに解除するには、同じ本文を指定して POST /inbound/unlink を使用します。

Create-trunk フィールドリファレンス

フィールド	型	必須	デフォルト	備考
name	string	はい	—	アカウント内で一意である必要があります。
provider	string	はい	—	twilio、plivo、telnyx、vonage、custom など。
description	string	いいえ	null	内部用です。
auth_type	string	はい	—	userpass または ip-based。
auth_username / auth_password	string	条件付き	—	auth_type == "userpass" の場合に必須です。
gateways[]	array	はい	—	1 つ以上の {gateway_address, port, priority}。
ip_identifiers[]	array	条件付き	[]	auth_type == "ip-based" の場合に必須です。{ip_address} のリストです。
allow	string	いいえ	"ulaw,alaw"	CSV 形式のコーデックです。必ず ulaw を含めてください。
disallow	string	いいえ	"all"	CSV 形式のコーデックです。
transport	enum	いいえ	"transport-udp"	transport-udp、transport-tcp、transport-tls。
media_encryption	enum	いいえ	"no"	no または sdes。sdes には transport-tls が必要です。
media_encryption_optimistic	bool	いいえ	false	キャリアが暗号化を提供しない場合、暗号化されていない RTP にフォールバックします。
inbound_enabled	bool	いいえ	false	着信通話を有効にする場合はオンにします。
outbound_leading_plus_enabled	bool	いいえ	true	発信時に先頭へ + を付加します。キャリアによっては + を拒否します。
direct_media	bool	いいえ	false	false のままにしてください。
rtp_symmetric	bool	いいえ	true	NAT に必要です。
force_rport	bool	いいえ	true	NAT に必要です。
qualify_frequency	int	いいえ	60	SIP OPTIONS の ping 間隔（秒）です。0 で無効になります。
phone_numbers[]	array	いいえ	[]	作成時に設定できる任意の初期 DID です。

トラブルシューティング

着信通話はつながるが、片通話になる／音声が聞こえない

最も一般的な原因は、Bolna とキャリア間の SRTP の不一致 です。

• キャリアで SRTP が無効なのに、Bolna で media_encryption: "sdes" が設定されている → media_encryption: "no" に設定するか、キャリア側の設定を合わせます。
• 簡単なテスト：media_encryption_optimistic: true にすると、暗号化されていない RTP にフォールバックします。
• 通話のセットアップが機能するまで暗号化を完全にスキップします：transport-udp + media_encryption: "no"。

422 media_encryption='sdes' requires transport='transport-tls'

SDES キーは SDP 内を通るため、シグナリングを暗号化する必要があります。次のいずれかを行います。

• transport を transport-tls に切り替えます（ゲートウェイでは port: 5061 を指定します）。
• または、media_encryption: "no" に設定します。

発信 INVITE が鳴り続ける／特定のキャリアで応答なしに失敗する

UDP の断片化が原因です。キャリアが INVITE に大きなヘッダー（長い Diversion、複数の Route、P-Asserted-Identity）を追加し、UDP パケットが MTU を超えています。

解決方法：transport: "transport-tcp" にします。TLS は不要です。TCP だけで断片化を回避できます。

着信がまったく届かない

以下を順番に確認します。

1. キャリアの発信元 URI は sip:sip.bolna.ai:5060（または :5061;transport=tls）に設定されていますか？
2. DID は POST /sip-trunks/trunks/{id}/numbers でトランクに追加されていますか？
3. トランクで inbound_enabled: true が設定されていますか？
4. DID は POST /inbound/setup でエージェントに割り当てられていますか？
5. キャリアで Bolna の IP 13.200.45.61 がホワイトリストに登録されていますか？
6. INVITE の Request-URI または To ヘッダーは、保存されている電話番号の形式（+ の有無）と一致していますか？

発信時に from_phone_number が拒否される

• from_phone_number は、トランクに登録された DID（/sip-trunks/trunks/{id}/numbers）である必要があります。
• エージェントの telephony_provider を sip-trunk に更新する必要があります。
• トランクで is_active: true が設定されている必要があります。
• キャリアによってはダイヤル先の番号の先頭にある + を拒否します。outbound_leading_plus_enabled を合わせて切り替えてください。

userpass の認証に失敗する

キャリアのポータルで SIP 認証情報をもう一度確認してください。アカウントの認証情報とは別のものです。Twilio Elastic SIP では、SIP REGISTER 認証専用の「Credential List」を使用します。

安全性

トランクを削除すると、ゲートウェイ、IP 識別子、番号マッピングも連鎖的に削除されます。着信および発信の処理はすぐに停止します。DELETE /sip-trunks/trunks/{id} を実行する前に、必ずユーザーに確認してください。

詳細を見る

ファイル	内容
references/twilio-elastic.md	キャリア側の画面を正確に示した、Twilio Elastic SIP のエンドツーエンド設定です。
references/plivo-zentrunk.md	ip_identifiers を含む Plivo Zentrunk の設定です。
scripts/create_sip_trunk.py	POST /sip-trunks/trunks をラップします。
scripts/add_trunk_number.py	POST /sip-trunks/trunks/{id}/numbers をラップします。
scripts/diagnose_trunk.py	トラブルシューティング用に、トランク、番号、アクティブなマッピングを読み取ります。

関連項目

• setup-inbound — DID からエージェントへのマッピング（Bolna ホスト型と SIP トランクの DID を同じ方法で扱います）。
• make-call — 発信 API。telephony_provider を sip-trunk に設定すれば、同じように動作します。
• manage-phone-numbers — Bolna ホスト型 DID（BYOT の代替手段）。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md — 自社トランクでも、番号には引き続き DLT 要件が適用されます。