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 托管号码可执行的操作

操作	方法
外呼主叫号码	将号码作为 from_phone_number 传给 POST /call（参见 make-call）。
呼入 Agent 路由	通过 POST /inbound/setup 映射到 Agent（参见 setup-inbound）。
批量外呼	将号码作为 from_phone_numbers 之一传给 POST /batches（参见 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	已映射的呼入 Agent 的 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，请保存此 ID，以便进行呼入映射。

购买后 — 连接到呼入 Agent

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 时从钱包扣款。
• 通话费用另计 — 按分钟收取的电话服务费用（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 + Header 注册（RBI/SEBI 证书）+ Template 注册

请预留 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/month 月租将在下次续费时停止。
• 删除无法撤销 — 你需要重新购买号码。

删除前务必征得用户确认，尤其是号码已映射到活跃呼入 Agent 的情况（列表响应中的 agent_id 不为 null）。

Bolna 托管号码与自有服务商

方式	优点	缺点
Bolna 托管 DID	即时设置；一张账单；支持呼入和呼出	国家／地区选择有限
自有服务商（Twilio / Plivo / Vobiz / Exotel）	使用现有号码、享受协商费率	需要连接服务商，并管理两套账单
SIP 中继（BYOT）	复用中继；使用任意运营商提供的合规号码	Beta；需要进行运维设置

对于以上每种方式，只要有 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 — 将购买的号码映射到 Agent。
• make-call — 将号码用作呼出电话的 from_phone_number。
• setup-sip-trunk — 用于 BYOT 中继（生命周期不同，使用独立端点）。
• add-provider — 连接自有的 Twilio/Plivo/Vobiz/Exotel 并使用其号码。