Step IVR 对接指南

Step IVR 是 RustPBX 的外部化 IVR 模式：每个呼叫步骤通过 HTTP POST 调用你的 Provider API，由外部系统决定下一步操作。适用于需要动态逻辑、数据库查询、AI 决策等场景。

1. 工作原理

来电进入 IVR
    │
    ▼
RustPBX 调用 POST /ivr/start（通知新会话）
    │
    ▼
RustPBX 调用 POST /ivr/step（携带事件）
    │
    ▼
Provider 返回 ActionNode（下一步操作）
    │
    ├── prompt（播放提示音/TTS）→ 等待事件 → 再次 POST /ivr/step
    ├── dtmf_menu（收集按键）→ 等待 DTMF → POST /ivr/step
    ├── collect_dtmf（收集多位按键）→ POST /ivr/step
    ├── input_voice（语音输入）→ POST /ivr/step
    ├── api（调用外部 API）→ POST /ivr/step（携带 api_response）
    ├── torecord（录音）→ POST /ivr/step（携带 recording_complete）
    ├── transfer（转接）→ 结束
    ├── hangup（挂断）→ 结束
    └── queue/voicemail（进队列/信箱）→ 结束

结束时会调用 POST /ivr/end（fire-and-forget）。

2. 配置

2.1 路由配置

在路由规则中将呼叫指向 Step IVR：

[[route]]
name = "to-ivr"
action = "application"
application = "ivr:smart-ivr"

[route.match]
to_user = "^4000$"

2.2 IVR 定义

创建 config/ivr/smart_ivr.toml：

[ivr]
name = "smart-ivr"
ivr_mode = "step"

[ivr.provider]
url = "http://10.0.0.50:8080/ivr/step"
max_retries = 3
retry_delay_ms = 1000
timeout_secs = 10

[ivr.provider.headers]
Authorization = "Bearer my-secret-key"
X-App-Id = "my-ivr-app"

# 可选：TTS 配置（用于 tts_text 字段）
[ivr.tts]
enabled = true

2.3 Provider 配置参数

2.4 兜底恢复与本地 Step 端点（0.5+）

兜底恢复：当外部 Provider 无法继续服务(不可达、连续失败)时,RustPBX 可以把呼叫转入本地 IVR,而不是直接挂断。规则按 priority 降序评估,匹配语义与拨号路由一致:

[proxy.ivr_fallback]
default = "default"

[[proxy.ivr_fallback.rules]]
name = "vip"
priority = 100
match = { "from.user" = "^9" }
target = "builtin_vip_step"

部署本地 Step 端点：IVR Provider 的 URL 可以指向部署自身(主机占位符本地解析),同一套 IVR 树无需修改即可运行在任意节点。

TTS 提示音别名：第三方 IVR 树可以按别名(tts_text 名称)引用提示音,由部署的 TTS 配置解析,不再硬编码引擎专属字符串。

3. 协议详解

3.1 ProviderContext（RustPBX → Provider）

每次 POST 请求体：

{
  "session_id": "call_abc123",
  "caller": "1001",
  "callee": "4000",
  "direction": "inbound",
  "tenant_id": "default",
  "ivr_id": "smart-ivr",
  "variables": { "key": "value" },
  "sip_headers": { "X-Custom": "value" },
  "event": { "type": "session_start" }
}

3.2 ProviderEvent 类型

resume:是继续,不是重新进入（0.5+）

当 Step 流程在 voip_bridge（如咨询转）上挂起、呼叫返回且无缓冲按键时,RustPBX 发送显式的 resume 事件并携带 resume_from_step_id——而不是重放第二次 session_start。逻辑流程的 session_start 只在其真正的首次进入时发出一次;Provider 必须从引用的步骤恢复(还原变量),而不是重播菜单。这堵住了“菜单重放“漏洞——呼叫者不会重复听到欢迎语、之前的输入也不会被再次询问。

end 追踪还携带结构化的 end_reason,Provider 无需靠“事件缺失“去猜测流程为何终止(完成/转接/失败)。

3.3 ActionNode（Provider → RustPBX）

终端动作（执行后 IVR 结束）

非终端动作（执行后等待事件，再次调用 Provider）

3.4 动作链（next 字段）

非终端动作可通过 next 字段链式组合，减少 HTTP 往返：

{
  "type": "prompt",
  "tts_text": "请稍候",
  "next": {
    "type": "api",
    "url": "http://crm/query",
    "next": {
      "type": "dtmf_menu",
      "tts_text": "查询完成，按1继续",
      "timeout_ms": 5000
    }
  }
}

3.5 变量替换

ActionNode 中的字符串支持 $var_name$ 变量替换：

{
  "type": "transfer",
  "target": "$collected_number$"
}

变量来源：

• collect_dtmf / input_phone 设置的 variable
• torecord 设置的 variable（录音 URL）
• api 的响应存入 api_response 变量

4. 会话生命周期端点

除了主 url，RustPBX 还会调用两个通知端点（fire-and-forget）：

这两个端点都是 POST，请求体与主端点相同。Provider 可以在此初始化/清理会话状态。

5. 错误处理

Provider 不可达时的行为：

重试耗尽后执行 fallback 动作（如未配置则挂断）。

6. Python Provider 示例

from http.server import HTTPServer, BaseHTTPRequestHandler
import json, time

class IvrProvider(BaseHTTPRequestHandler):
    sessions = {}

    def do_POST(self):
        body = json.loads(self.rfile.read(int(self.headers.get("Content-Length", 0))))
        sid = body.get("session_id", "")

        if self.path.endswith("/start"):
            self.sessions[sid] = {"step": "welcome"}
            self._json(200, {"status": "ok"})
            return

        if self.path.endswith("/end"):
            self.sessions.pop(sid, None)
            self._json(200, {"status": "ok"})
            return

        # Main step endpoint
        event = body.get("event", {"type": "session_start"})
        session = self.sessions.get(sid, {"step": "welcome"})
        ev_type = event.get("type", "")

        if session["step"] == "welcome":
            session["step"] = "menu"
            self._json(200, {
                "type": "prompt",
                "tts_text": "欢迎致电，按1查询余额，按2转人工",
                "interruptible": True
            })
        elif ev_type == "dtmf" and event["digit"] == "1":
            self._json(200, {"type": "play_and_hangup", "tts_text": "您的余额为100元"})
        elif ev_type == "dtmf" and event["digit"] == "2":
            self._json(200, {"type": "transfer", "target": "agent"})
        else:
            self._json(200, {"type": "hangup"})

    def _json(self, status, data):
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(json.dumps(data).encode())

HTTPServer(("0.0.0.0", 8080), IvrProvider).serve_forever()

6.1 测试

# 模拟 session_start
curl -X POST http://localhost:8080/ivr/step \
  -H "Content-Type: application/json" \
  -d '{"session_id":"test","event":{"type":"session_start"},"caller":"1001","callee":"4000"}'

# 模拟按键 1
curl -X POST http://localhost:8080/ivr/step \
  -H "Content-Type: application/json" \
  -d '{"session_id":"test","event":{"type":"dtmf","digit":"1"},"caller":"1001","callee":"4000"}'

7. 与 Tree 模式对比