setup-inbound

Bolna 呼入电话

呼入电话 = 将电话号码映射到 Agent，使拨打该号码的来电自动接听。还可选择添加 IVR 菜单、来电者身份识别、垃圾来电控制和多语言切换。

只有两个端点

端点	用途
POST /inbound/setup	将电话号码映射到 Agent（可选配置 IVR）
POST /inbound/unlink	取消映射

两者均需：Authorization: Bearer $BOLNA_API_KEY、Content-Type: application/json。

phone_number_id 的来源

号码来源	如何获取 ID
Bolna 托管（在控制面板购买）	GET /phone-numbers/all — 参见 manage-phone-numbers
已连接的服务提供商（你的 Twilio、Plivo、Vobiz、Exotel）	连接服务提供商后，列出电话号码时返回
你自己的 SIP 中继（BYOT）	由 POST /sip-trunks/trunks/{id}/numbers 返回 — 参见 setup-sip-trunk

无论来源如何，映射流程都相同。

基本映射

curl -X POST https://api.bolna.ai/inbound/setup \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "phone_number_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

响应：

{
  "url": "https://api.bolna.ai/inbound_call?agent_id=...&user_id=...",
  "phone_number": "+19876543210",
  "id": "3c90c3cc0d444b5088888dd25736052a"
}

基本设置就完成了。现在，拨打 +19876543210 的任何来电都会由该 Agent 接听。

一个号码对应一个 Agent。 将号码重新映射到其他 Agent 时，之前的关联会被静默取消。若要解除关联而不重新映射，请使用 /inbound/unlink。

IVR（菜单路由）

适用于“按 1 联系销售，按 2 联系支持”或通话前收集数据的场景。仅支持 Plivo。

curl -X POST https://api.bolna.ai/inbound/setup \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @assets/ivr_department_routing.json

资源文件：

{
  "agent_id": "default-agent-uuid",
  "phone_number_id": "phone-number-uuid",
  "ivr_config": {
    "enabled": true,
    "voice": "Polly.Aditi",
    "welcome_message": "Welcome to Acme Corp.",
    "timeout": 5,
    "max_retries": 2,
    "default_agent_id": "default-agent-uuid",
    "steps": [
      {
        "step_id": "department",
        "type": "menu",
        "prompt": "Press 1 for Sales. Press 2 for Support. Press 3 for Billing.",
        "field_name": "department",
        "options": [
          { "digit": "1", "label": "Sales",   "agent_id": "sales-agent-uuid" },
          { "digit": "2", "label": "Support", "agent_id": "support-agent-uuid" },
          { "digit": "3", "label": "Billing", "agent_id": "billing-agent-uuid" }
        ]
      }
    ]
  }
}

步骤类型

类型	用途
menu	显示选项，并根据按下的数字进行路由。
collect	收集多位数字输入（账号、PIN）。

IVR 顶层字段

字段	默认值	说明
enabled	false	总开关。
voice	Polly.Joanna	IVR 提示词使用的 Polly 语音。印地语-英语使用 Polly.Aditi。
welcome_message	—	连接后、第一步之前播放一次。
timeout	5	每个步骤等待来电者输入的秒数。
max_retries	2	每个步骤遇到无效输入时的重试次数。
invalid_input_message	"Invalid input. Please try again."	按键错误时播放。
no_input_message	"No input received. Goodbye."	超时后播放。
steps[]	必填	IVR 流程。
default_agent_id	—	未设置选项级 agent_id 时的备用 Agent。

步骤导航

字段	行为
next_step	线性导航：当前步骤结束后转到此步骤。
conditional_next	按数字分支：{"1": "menu_en", "2": "menu_hi"}。
两者皆无	IVR 结束。路由到所选的 agent_id 或 default_agent_id。

带分支的多语言 IVR

{
  "step_id": "language",
  "type": "menu",
  "prompt": "For English press 1. Hindi ke liye 2 dabayein.",
  "field_name": "language",
  "options": [
    { "digit": "1", "label": "English" },
    { "digit": "2", "label": "Hindi" }
  ],
  "conditional_next": { "1": "menu_en", "2": "menu_hi" }
}

完整的多语言部门路由流程请参见 assets/ivr_multilingual.json。

Agent 可见内容

IVR 完成后，收集的字段会作为 recipient_data 提供：

{
  "department": "Sales",
  "account_number": "123456",
  "language": "English",
  "ivr_completed_at": "2026-05-19T10:30:00Z"
}

在 Agent 提示词中使用这些字段："Customer selected {department}. Account number: {account_number}."

禁用 IVR

curl -X POST https://api.bolna.ai/inbound/setup \
  ... \
  -d '{ "agent_id": "...", "phone_number_id": "...", "ivr_config": { "enabled": false } }'

完整的 IVR 参考（菜单和收集步骤示例、条件分支）请参见 references/ivr-config.md。

来电者身份识别（ingest_source_config）

根据来电者身份预填 Agent 的提示词变量。此项在 Agent 上配置，而非在 /inbound/setup 上配置。共有三种方式：

来源	最适用场景
内部 API	已有 CRM 或客户数据库的团队。实时、完全动态。
CSV 上传	小型团队、低通话量、无代码场景。静态数据 — 更新时需重新上传。
Google Sheet	无需编码即可实时同步。工作表必须可公开访问。

内部 API 来源

Bolna 会向你的端点发送 GET 请求，并附带：

GET https://your-api.example.com/customers
    ?contact_number=+19876543210
    &agent_id=<agent_uuid>
    &execution_id=<execution_uuid>

身份验证：Bearer 令牌（按 Agent 配置）。

响应 JSON 会合并到 recipient_data 中。在提示词中使用：

You are speaking with {first_name} {last_name}. They are on the {plan} plan,
last contacted on {last_contacted_at}.

CSV / Google Sheet 来源

两者都需要包含 contact_number 列（含国家代码）。其他所有列都会成为提示词变量。

contact_number,first_name,last_name,plan,last_contacted_at
+19876543210,Priya,Sharma,Enterprise,2026-05-12
+918765432109,Rahul,Verma,Pro,2026-05-14

各来源的完整设置说明请参见 references/caller-identification.md。

垃圾信息和滥用控制

这些设置位于 Agent 的 task_config 中，而不在入站映射本身。

字段	说明
inbound_limit	每个接收方电话号码的最大呼叫次数。-1 = 不限。可用于防止单个号码导致费用不断增加。
whitelist_phone_numbers[]	始终绕过任何限制／未知来电者规则的 E.164 格式号码。
disallow_unknown_numbers	布尔值。为 true 时，拒绝未出现在 Agent 的 ingest_source_config 查询中的来电者。需要设置 ingest_source_config。

{
  "task_config": {
    "inbound_limit": 3,
    "whitelist_phone_numbers": ["+919876543210", "+19876543210"],
    "disallow_unknown_numbers": true
  }
}

如果 disallow_unknown_numbers: true 且未配置 ingest_source_config，所有入站呼叫都会被拒绝。请务必先配置来电者识别。

多语言自动切换

Bolna 可以在约 3 轮对话后自动检测来电者的语言，并将系统消息（挂断、用户在线检查、工具等待）切换为该语言。请在 Agent 中配置语言变体：

{
  "check_user_online_message": {
    "en": "Hey, are you still there?",
    "hi": "क्या आप अभी भी वहाँ हैं?",
    "ta": "வணக்கம், நீங்கள் இன்னும் இணைப்பில் இருக்கிறீர்களா?"
  },
  "call_hangup_message": {
    "en": "Thank you for calling. Goodbye!",
    "hi": "कॉल करने के लिए धन्यवाद। अलविदा!"
  }
}

回退顺序：检测到的语言 → en → 第一个可用项。**请务必将 en 配置为安全回退选项。**请参阅 references/auto-switch-messages.md。

取消关联

curl -X POST https://api.bolna.ai/inbound/unlink \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "123e4567-e89b-12d3-a456-426614174000" }'

该号码仍归你所有（在你的提供商／SIP 中继／Bolna 库存中）。此操作只会移除与 Agent 的关联。

深入了解

文件	内容
references/ivr-config.md	所有步骤类型、导航、语音和高级模式。
references/caller-identification.md	API、CSV、Google Sheet — 设置指南和提示词变量配置。
references/auto-switch-messages.md	多语言消息包、回退顺序和支持的代码。
assets/ivr_department_routing.json	简单的部门路由 IVR。
assets/ivr_multilingual.json	语言选择 → 部门菜单，每种语言使用单独的 Agent。
assets/ivr_account_verification.json	在 Agent 接入前执行两步 collect 流程（账号 + PIN）。
scripts/setup_inbound.py	使用简单设置和 IVR 设置选项封装 POST /inbound/setup。

故障排查

现象	原因	解决方法
电话响铃但无人接听	phone_number_id 尚未映射	重新运行 POST /inbound/setup；使用 GET /phone-numbers/all 验证
IVR 返回 400	在非 Plivo 号码上使用 IVR	IVR 仅适用于 Plivo；改用 Plivo 路由或跳过 IVR
提示词中的 recipient_data 为空	未设置 ingest_source_config，或 contact_number 不匹配	确认数据源中包含来电号码；查看 Bolna 日志中的查询 HTTP 状态
所有来电者都被拒绝	设置了 disallow_unknown_numbers: true，但未配置 ingest_source_config	先添加数据源，或将 disallow_unknown_numbers 设为 false
自动切换后的挂断消息使用了错误的语言	检测需要 3 轮，但通话时长不足	配置 en 回退；预计前一两轮仍会使用主要语言
Agent 接听后，入站 SIP 音质很差	ulaw 编解码器不匹配	Bolna 会为 SIP 路由的入站呼叫设置 ulaw；请确认你的中继允许使用 ulaw

另请参阅

• manage-phone-numbers — 购买或列出 Bolna 号码（phone_number_id 的来源）。
• setup-sip-trunk — 将 BYOT 号码接入 Bolna。
• create-agent — Agent 请求体中的 task_config（垃圾信息控制）和 ingest_source_config。
• setup-tools/references/dtmf.md — 通话中的按键输入（不同于 IVR 菜单路由）。
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md — 使用受监管的印度号码时适用的 DLT / 140 / 160 系列规则。