随访外呼(小程序版)
医患随访场景的精简对接:查线路、提交随访任务、轮询通话结果与 mRS 评分。
本页是面向随访小程序的精简版,只覆盖 4 个接口。完整的线索导入、批量上传、启停项目等能力见 AI 呼出,认证与错误码见 接入概述。
接口地址: https://api.halfcall.cn
认证方式: 所有接口 Header 里带 Authorization: Bearer <api_key>
数据格式: JSON
典型调用流程
小程序 服务端
| |
| 1. GET /line-status |
| ────────────────────────────────────> | 检查有没有空闲线路
| <──────────────────────────────────── | { idle: 38 }
| |
| 2. POST /leads |
| ────────────────────────────────────> | 提交随访任务(手机号+患者信息)
| <──────────────────────────────────── | { threadId: "xxx" }
| |
| 3. GET /leads?threadId=xxx |
| ────────────────────────────────────> | 轮询任务状态(建议 10 秒一次)
| <──────────────────────────────────── | { status: "PROCESSING" }
| ...轮询... |
| <──────────────────────────────────── | { status: "COMPLETED" }
| |
| 4. GET /leads?threadId=xxx |
| ────────────────────────────────────> | 拿结果(录音+对话文本+AI分析)
| <──────────────────────────────────── | { calls: [{ recordingUrl, summary, ... }] }
| |
| 5. GET /leads?threadId=xxx(继续轮询) |
| ────────────────────────────────────> | 等 mRS 评分出来(通话结束后约 1~3 分钟)
| <──────────────────────────────────── | { calls: [{ ..., mrs: { score: 2, ... } }] }
mRS 评分是通话结束后单独跑的,比录音/摘要晚一点出来。所以
status变成COMPLETED后,如果接通的通话mrs还是null,继续按原频率轮询,直到mrs有值(最多等 30 分钟)。
接口一:查询线路状态
打电话之前先看看有没有空闲线路,有空闲再提交任务。
GET /api/v1/external/programs/{programId}/line-status
请求示例
curl "https://api.halfcall.cn/api/v1/external/programs/你的项目ID/line-status" \
-H "Authorization: Bearer 你的apikey"
返回示例
{
"code": 0,
"data": {
"programId": "cmk...",
"runState": "RUNNING",
"maxConcurrency": 50,
"currentConcurrency": 12,
"idle": 38
}
}
字段说明
| 字段 | 说明 |
|---|---|
| runState | 项目状态,RUNNING 表示正常运行,PAUSED 表示已暂停 |
| maxConcurrency | 最大能同时打多少路电话 |
| currentConcurrency | 现在正在通话的数量 |
| idle | 空闲线路数,大于 0 就可以提交任务 |
建议:
idle > 0且runState = "RUNNING"时再提交随访任务。
接口二:提交随访任务
传入手机号和患者信息,系统会自动发起外呼。
POST /api/v1/external/leads
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| programId | string | 是 | 项目 ID,创建项目时会分配 |
| phone | string | 是 | 患者手机号 |
| variables | object | 否 | 患者附加信息,这些信息会在通话中被用到 |
variables 里可以传患者姓名、性别、科室、诊断等等,具体有哪些字段取决于话术配置,比如:
{
"name": "张三",
"sex": "男",
"age": "45",
"department": "心内科",
"diagnosis": "冠心病",
"doctor": "李主任"
}
请求示例
curl -X POST "https://api.halfcall.cn/api/v1/external/leads" \
-H "Authorization: Bearer 你的apikey" \
-H "Content-Type: application/json" \
-d '{
"programId": "你的项目ID",
"phone": "13800138000",
"variables": {
"name": "张三",
"sex": "男",
"department": "心内科",
"diagnosis": "冠心病"
}
}'
返回示例
{
"code": 0,
"msg": "success",
"threadId": "clxxxxxxxxxxxxx",
"phone": "13800138000",
"message": "Lead has been queued for processing"
}
返回的
threadId要保存下来,后面查状态和结果都要用。同一个手机号重复提交不会报错,会复用之前的记录重新排队拨打。
接口三:查询任务状态和结果
提交任务后,轮询这个接口看通话有没有完成。建议每 10 秒查一次。
通话完成后,同一个接口直接就能拿到录音、对话摘要、AI 分析结果和 mRS 评分。
GET /api/v1/external/leads
查询方式(二选一)
| 参数 | 说明 |
|---|---|
| threadId | 提交任务时返回的 threadId |
| programId + phone | 项目 ID + 手机号 |
请求示例
# 用 threadId 查(推荐)
curl "https://api.halfcall.cn/api/v1/external/leads?threadId=clxxxxxxxxxxxxx" \
-H "Authorization: Bearer 你的apikey"
# 或者用项目ID + 手机号查
curl "https://api.halfcall.cn/api/v1/external/leads?programId=你的项目ID&phone=13800138000" \
-H "Authorization: Bearer 你的apikey"
返回示例
{
"code": 0,
"data": {
"threadDetailId": "clxxxxxxxxxxxxx",
"phone": "13800138000",
"status": "COMPLETED",
"stage": 1,
"variables": {
"name": "张三",
"department": "心内科"
},
"createdAt": "2025-04-21T10:00:00.000Z",
"updatedAt": "2025-04-21T10:05:00.000Z",
"calls": [
{
"callId": "task_detail_xxx",
"reached": "USER_END",
"duration": 120,
"intention": "HIGH",
"intentionRate": 85,
"recordingUrl": "https://cdn.halfcall.cn/rec/xxx.mp3",
"summary": "患者表示术后恢复良好,无明显不适,按时服药",
"extractData": {
"recovery_status": "良好",
"medication_compliance": true
},
"mrs": {
"status": "SUCCESS",
"score": 2,
"possibleRange": "1-2",
"needsReview": false,
"basis": "患者能独立行走,日常生活可自理,但无法完成病前全部工作",
"updatedAt": "2025-04-21T10:05:30.000Z"
},
"createdAt": "2025-04-21T10:01:00.000Z",
"startTime": "2025-04-21T10:01:05.000Z",
"connectTime": "2025-04-21T10:01:15.000Z",
"endTime": "2025-04-21T10:03:15.000Z"
}
]
}
}
status(任务状态)
| 值 | 说明 |
|---|---|
| WAITING | 排队中,还没开始打(含未接通后等待重拨) |
| PROCESSING | 正在拨打 |
| COMPLETED | 已完成 |
| TRANSFERED | 已转人工 |
| FAILED | 拨打失败 |
| IGNORED | 已跳过 / 已取消 |
reached(接听状态)
| 值 | 说明 | 是否接通 |
|---|---|---|
| USER_END | 已接通,患者/家属挂断 | 是 |
| AGENT_END | 已接通,AI 挂断 | 是 |
| SEAT_END | 已接通,转人工后坐席挂断 | 是 |
| REACHED | 已接通,通话还没结束(中间态) | 是 |
| UNREACHED | 响铃未接 | 否 |
| CALL_REJECTED | 拒接 | 否 |
| EMPTY_PHONE | 空号 | 否 |
| SHUTDOWN | 关机或空号 | 否 |
| UN_CONNECT | 无法接通(停机等) | 否 |
| INVALID | 其他原因未接通 | 否 |
| CALLER_ABNORMAL | 我方线路异常未接通 | 否 |
| INIT / PREPARE / DIALED | 拨打中,还没有结果 | - |
判断是否接通请用
reached属于USER_END / AGENT_END / SEAT_END / REACHED四个值之一(或duration > 0),不要只判断reached == "REACHED"——通话结束后大多数接通的电话是USER_END或AGENT_END。
intention(意向判断)
本项目的"有意向" = AI 判断患者需要医院再次跟进(与 extractData 里的"需医生跟进"一致)。
| 值 | 说明 |
|---|---|
| HIGH | 需要医院再次跟进 |
| HESITATE | 模糊(本项目一般不会出现) |
| NONE | 不需要跟进,或未接通、未分析 |
| UNKNOW | AI 分析尚未完成,过几秒重查即可 |
calls 数组里每个通话的字段
| 字段 | 类型 | 说明 |
|---|---|---|
| callId | string | 本次通话的唯一 ID |
| reached | string | 接听状态,见上表 |
| duration | number | 通话时长(秒) |
| intention | string | AI 意向判断 |
| intentionRate | number | 意向评分(0-100) |
| recordingUrl | string | 通话录音地址(MP3),可直接播放 |
| summary | string | AI 生成的通话摘要 |
| extractData | object | AI 从对话中提取的结构化数据 |
| mrs | object | mRS 评分结果,见下表;还没出结果或未接通时为 null |
| startTime | string | 开始拨打时间 |
| connectTime | string | 接通时间(未接通则为 null) |
| endTime | string | 通话结束时间 |
mrs(mRS 评分)
根据通话内容自动给出的改良 Rankin 量表(mRS)评分。只对接通且有对话内容的通话评分,通话结束后约 1~3 分钟出结果。
| 字段 | 类型 | 说明 |
|---|---|---|
| status | string | 评分状态,见下表 |
| score | number | mRS 分值(0-6);status 不是 SUCCESS 时为 null。注意 0 分是正常结果,别当成没值 |
| possibleRange | string | 可能的分值范围,例如 "1-2";没有时为 null |
| needsReview | boolean | 是否建议人工复核(对话信息不足、判断不确定时为 true) |
| basis | string | 评分依据(文字说明) |
| updatedAt | string | 评分时间 |
| status | 说明 |
|---|---|
| SUCCESS | 评分成功 |
| UNASSESSABLE | 对话里信息不够,无法评分(score 为 null) |
| FAILED | 评分服务出错,且系统自动重试后仍失败(最终结果,不会再变) |
mrs为 null 时说明还在评分中(评分服务出错时系统会自动重试,重试期间也是 null),继续轮询即可。
mrs只要不是 null(SUCCESS/UNASSESSABLE/FAILED任一种),就是这通电话的最终评分结果,可以停止轮询。
接口四:批量查询
如果一次提交了很多随访任务,可以用这个接口批量查进度。
GET /api/v1/external/leads/batch
| 参数 | 类型 | 说明 |
|---|---|---|
| threadIds | string | 多个 threadId 用逗号隔开,最多 100 个 |
| programId | string | 按项目查,配合 date 和分页用 |
| date | string | 日期过滤,格式 YYYY-MM-DD |
| page | number | 页码,默认 1 |
| pageSize | number | 每页数量,默认 20,最大 100 |
请求示例
# 按 threadId 批量查
curl "https://api.halfcall.cn/api/v1/external/leads/batch?threadIds=id1,id2,id3" \
-H "Authorization: Bearer 你的apikey"
# 按项目 + 日期查
curl "https://api.halfcall.cn/api/v1/external/leads/batch?programId=你的项目ID&date=2025-04-21&page=1&pageSize=20" \
-H "Authorization: Bearer 你的apikey"
返回示例
{
"code": 0,
"data": {
"total": 50,
"page": 1,
"pageSize": 20,
"list": [
{
"threadDetailId": "clxxxxxxxxxxxxx",
"phone": "13800138000",
"programId": "你的项目ID",
"status": "COMPLETED",
"stage": 1,
"createdAt": "2025-04-21T10:00:00.000Z",
"latestCall": {
"callId": "task_detail_xxx",
"reached": "USER_END",
"duration": 120,
"intention": "HIGH",
"intentionRate": 85,
"summary": "患者术后恢复良好",
"mrs": {
"status": "SUCCESS",
"score": 2,
"possibleRange": "1-2",
"needsReview": false,
"basis": "患者能独立行走,日常生活可自理,但无法完成病前全部工作",
"updatedAt": "2025-04-21T10:05:30.000Z"
},
"createdAt": "2025-04-21T10:01:00.000Z"
}
}
]
}
}
批量查询每条记录只返回最近一次通话的摘要信息。如果需要完整的通话详情(录音、全部通话记录),再用接口三按 threadId 单独查。
错误码
| code | HTTP 状态码 | 说明 |
|---|---|---|
| 0 | 200/202 | 成功 |
| -1 | 400 | 参数不对,看 msg 里的具体提示 |
| -1 | 401 | API Key 不对或过期了 |
| -1 | 403 | 没权限访问这个项目 |
| -1 | 404 | 找不到对应的记录 |
| -1 | 500 | 服务端出错了,联系我们排查 |
常见问题
Q: 提交任务后多久会打电话? A: 一般几秒内就会发起外呼。如果线路全占满了会排队,有空闲线路就自动打。
Q: 同一个手机号可以重复提交吗? A: 可以。系统会自动识别,复用之前的记录重新排队拨打。
Q: 通话录音能保存多久? A: 录音文件存在服务器,长期保留。
Q: variables 里的字段是固定的吗? A: 不是,取决于话术怎么配的。对接前会告诉你具体需要传哪些字段。
Q: 轮询频率有限制吗? A: 建议 10 秒一次就够了。别太频繁(比如 1 秒一次),没必要。
Q: 状态已经是 COMPLETED 了,为什么 mrs 还是 null? A: mRS 评分要等通话结束后单独跑,一般晚 1~3 分钟;评分服务繁忙需要重试时会更久。继续轮询就行,最多等 30 分钟,超过还是 null 就按"没有评分"处理,可以联系我们排查。没接通的通话不会有 mRS 评分。
Q: 如果线路满了怎么办? A: 任务会自动排队,不需要重试。提交成功后系统会在有空闲线路时自动拨打。如果想给用户一个预期("当前线路繁忙,预计稍后拨打"),可以先查寻线路状态。