manage-phone-numbers

Bolna の電話番号

Bolna を通じて専用 DID を購入、一覧表示、管理できます。米国の番号は Twilio から、インドの番号は Plivo（カルナータカ州、マハーラーシュトラ州）または Vobiz（カルナータカ州、グジャラート州、NCR）から提供されます。番号ごとのレンタル料金は月額一律 $5/month で、ウォレットから請求されます。

ご自身の SIP トランク（Twilio Elastic、Plivo Zentrunk、Telnyx など）で取得した番号については、setup-sip-trunk をご覧ください。

エンドポイント

メソッド	パス	目的
GET	/phone-numbers/all	アカウント内のすべての番号を一覧表示
GET	/phone-numbers/search	購入可能な番号を検索（国、パターン、地域で絞り込み）
POST	/phone-numbers/buy	番号を購入
DELETE	/phone-numbers/{phone_number_id}	削除（着信ルーティングと月額料金の請求を停止）

認証：Authorization: Bearer $BOLNA_API_KEY。

Bolna ホストの番号でできること

操作	方法
発信者番号	番号を POST /call の from_phone_number に渡します（make-call を参照）。
着信エージェントへのルーティング	POST /inbound/setup でエージェントに紐付けます（setup-inbound を参照）。
一括発信	番号を POST /batches の from_phone_numbers のいずれかとして渡します（create-batch を参照）。

電話番号の一覧表示

curl https://api.bolna.ai/phone-numbers/all \
  -H "Authorization: Bearer $BOLNA_API_KEY"

各レスポンス項目の重要なフィールド：

フィールド	意味
id	電話番号の UUID。setup-inbound と DELETE で使用します。
phone_number	E.164 形式の番号。
agent_id	着信エージェントに紐付けられている場合はその UUID、そうでない場合は null。
price	月額レンタル料金。Bolna ホストの場合は $5.0。
telephony_provider	twilio / plivo / vobiz。
rented	Bolna 経由でレンタルした場合は true、BYOT／接続済みプロバイダーの場合は false。
created_at / renewal_at	ライフサイクルの日付。

購入前に検索する

# US numbers in the 718 area code
curl "https://api.bolna.ai/phone-numbers/search?country=US&pattern=718" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

# India - Plivo - Karnataka (80)
curl "https://api.bolna.ai/phone-numbers/search?country=IN&provider=plivo&region=80" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

# India - Vobiz - NCR (11)
curl "https://api.bolna.ai/phone-numbers/search?country=IN&provider=vobiz&region=11" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

地域コード

国	プロバイダー	地域	コード
インド	Plivo	カルナータカ州	80
インド	Plivo	マハーラーシュトラ州	22
インド	Vobiz	カルナータカ州	80
インド	Vobiz	グジャラート州	79
インド	Vobiz	NCR（デリー）	11

米国の番号には地域フィルターがありません。代わりに pattern（市外局番のプレフィックス）を使用してください。

購入

curl -X POST https://api.bolna.ai/phone-numbers/buy \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "phone_number": "+17182718146",
    "provider": "twilio"
  }'

インドの場合：

curl -X POST https://api.bolna.ai/phone-numbers/buy \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "IN",
    "phone_number": "+918012345678",
    "provider": "plivo"
  }'

レスポンスには新しい id が含まれます。着信の紐付けに使うため、保存してください。

購入後 — 着信エージェントに接続する

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'"
  }'

（詳細は setup-inbound/SKILL.md をご覧ください。）

料金

• 番号ごとに月額 $5。renewal_at にウォレットから請求されます。
• 通話料金は別途かかります — 1 分あたりの電話料金（Twilio／Plivo／Vobiz）に加えて、Bolna のプラットフォーム料金がかかります。
• ウォレットが料金の支払いに使われます。残高が少ない場合、POST /call は balance-low になります。GET /user/me で確認してください。

インド：140／160 系列の番号

これらは一般的な番号ではありません。インドで商用通話を販売するには、次の要件を満たす必要があります。

系列	用途	コンプライアンス要件
140 系列	プロモーション／テレマーケティング	TATA Teleservices ポータルでの DLT 登録、KYC、₹5,900 の支払い、PE ID、TM ID
160 系列	トランザクション／サービス（BFSI、アラート）	DLT ＋ ヘッダー登録（RBI／SEBI の証明書）＋ テンプレート登録

開通まで2〜4 週間を見込んでください。手順の詳細は https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md をご覧ください。

コンプライアンス手続きを完了する前に /phone-numbers/buy から 140／160 番号を購入することはできません。通信事業者が割り当てを拒否します。ユーザーからインドの規制対象番号を求められた場合は、この前提条件を最初に伝えてください。

削除

curl -X DELETE "https://api.bolna.ai/phone-numbers/$PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

削除すると：

• 紐付けられている場合、着信ルーティングがすぐに停止します。
• 次回の更新時に月額 $5 のレンタル料金が停止します。
• 削除は取り消せません。新しい番号を購入する必要があります。

削除する前に、必ずユーザーに確認してください。特に、その番号が有効な着信エージェントに紐付けられている場合（一覧レスポンスの agent_id が null 以外の場合）は、必ず確認してください。

Bolna ホスト型と独自プロバイダー

方法	メリット	デメリット
Bolna ホスト型 DID	すぐに設定可能。請求が一本化されます。着信と発信に対応しています	選択できる国・地域が限られています
独自プロバイダー（Twilio / Plivo / Vobiz / Exotel）	既存の番号や、交渉済みの料金を利用できます	プロバイダーへの接続が必要です。請求の窓口が2つになります
SIP トランク（BYOT）	トランクを再利用でき、任意のキャリアの規制対象番号を使用できます	ベータ版です。運用チームによる設定が必要です

いずれの方法でも、phone_number_id が存在すれば、setup-inbound のフローは同じです。

詳細を見る

ファイル	内容
scripts/search_numbers.py	国・地域・パターンのフラグを指定して GET /phone-numbers/search を呼び出します。
scripts/buy_number.py	POST /phone-numbers/buy を呼び出します。
scripts/list_numbers.py	GET /phone-numbers/all を呼び出します。
https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md	140 / 160 番号系列の完全な DLT プロセスです。

関連項目

• setup-inbound — 購入した番号をエージェントに割り当てます。
• make-call — 発信時に番号を from_phone_number として使用します。
• setup-sip-trunk — BYOT トランク向けです（ライフサイクルが異なり、エンドポイントも別です）。
• add-provider — 独自の Twilio/Plivo/Vobiz/Exotel を接続し、その番号を使用します。