事半AI

随访外呼(小程序版)

医患随访场景的精简对接:查线路、提交随访任务、轮询通话结果与 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

请求参数

字段类型必填说明
programIdstring是项目 ID,创建项目时会分配
phonestring是患者手机号
variablesobject否患者附加信息,这些信息会在通话中被用到

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不需要跟进,或未接通、未分析
UNKNOWAI 分析尚未完成,过几秒重查即可

calls 数组里每个通话的字段

字段类型说明
callIdstring本次通话的唯一 ID
reachedstring接听状态,见上表
durationnumber通话时长(秒)
intentionstringAI 意向判断
intentionRatenumber意向评分(0-100)
recordingUrlstring通话录音地址(MP3),可直接播放
summarystringAI 生成的通话摘要
extractDataobjectAI 从对话中提取的结构化数据
mrsobjectmRS 评分结果,见下表;还没出结果或未接通时为 null
startTimestring开始拨打时间
connectTimestring接通时间(未接通则为 null)
endTimestring通话结束时间

mrs(mRS 评分)

根据通话内容自动给出的改良 Rankin 量表(mRS)评分。只对接通且有对话内容的通话评分,通话结束后约 1~3 分钟出结果。

字段类型说明
statusstring评分状态,见下表
scorenumbermRS 分值(0-6);status 不是 SUCCESS 时为 null。注意 0 分是正常结果,别当成没值
possibleRangestring可能的分值范围,例如 "1-2";没有时为 null
needsReviewboolean是否建议人工复核(对话信息不足、判断不确定时为 true)
basisstring评分依据(文字说明)
updatedAtstring评分时间
status说明
SUCCESS评分成功
UNASSESSABLE对话里信息不够,无法评分(score 为 null)
FAILED评分服务出错,且系统自动重试后仍失败(最终结果,不会再变)

mrs 为 null 时说明还在评分中(评分服务出错时系统会自动重试,重试期间也是 null),继续轮询即可。

mrs 只要不是 null(SUCCESS / UNASSESSABLE / FAILED 任一种),就是这通电话的最终评分结果,可以停止轮询。


接口四:批量查询

如果一次提交了很多随访任务,可以用这个接口批量查进度。

GET /api/v1/external/leads/batch

参数类型说明
threadIdsstring多个 threadId 用逗号隔开,最多 100 个
programIdstring按项目查,配合 date 和分页用
datestring日期过滤,格式 YYYY-MM-DD
pagenumber页码,默认 1
pageSizenumber每页数量,默认 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 单独查。


错误码

codeHTTP 状态码说明
0200/202成功
-1400参数不对,看 msg 里的具体提示
-1401API Key 不对或过期了
-1403没权限访问这个项目
-1404找不到对应的记录
-1500服务端出错了,联系我们排查

常见问题

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: 任务会自动排队,不需要重试。提交成功后系统会在有空闲线路时自动拨打。如果想给用户一个预期("当前线路繁忙,预计稍后拨打"),可以先查寻线路状态。

接下来是什么?

以下是建议的下一步操作:

接入概述
外部系统对接事半AI平台的前置条件、认证方式、权限范围与错误码说明。
阅读指南
基础查询
获取项目列表、数字员工列表、线路状态、音色列表,以及创建项目、关联数字员工。
阅读指南
AI 呼出
线索导入(批量/单条)、启停项目、查询通话结果、拨打配置、批量查询与撤销线索。
阅读指南