系统集成文档

外部系统对接事半AI平台需要用到的全部接口——获取项目/数字员工信息、AI 外呼、AI 呼入、话术管理。通话结束后的话单回调请见 Webhook 参考。

目录

• 前置条件
• 一、获取基础信息
  • 1.1 获取项目列表
  • 1.2 获取项目下数字员工列表
  • 1.3 查询线路状态
  • 1.4 获取线路列表
  • 1.5 获取音色列表
• 二、AI 外呼
  • 2.1 线索导入（批量上传）
  • 2.2 查询线索字段定义
  • 2.3 线索导入（实时单条）
  • 2.4 启动项目
  • 2.5 查询线索通话结果
  • 2.6 拨打配置（可选）
  • 2.7 批量查询线索
  • 2.8 撤销线索
• 三、AI 呼入接入
  • 3.1 参数说明
  • 3.2 SIP Header 说明
  • 3.3 参数编码
  • 3.4 FreeSWITCH 转发示例
• 四、话术管理（可选）
  • 4.1 读取当前话术
  • 4.2 更新话术
• 错误码

前置条件

对接前您需要确认：

• API 地址：https://api.halfcall.cn
• SIP 地址：115.190.223.167:5080（AI 呼入接入用）
• 认证方式：所有请求在 Header 携带 Authorization: Bearer <api_key>，Key 在后台 API Key 管理 页创建
• 数据格式：JSON，Content-Type: application/json
• 权限隔离：每个 API Key 只能操作自己企业下的数据
• SIP 白名单：走 AI 呼入前，业务方服务器出口IP需发送给管理员加入系统白名单，否则 SIP 请求会被拒绝
• 话单回调：通话结束后系统主动推送话单，配置方式与签名规则见 Webhook 参考

下文示例中 sk_xxx、cmk...（项目 ID）、bot_xxx（数字员工 ID）均为占位符，替换成您自己企业下的真实值。

一、获取基础信息

对接前，需先通过 API 获取 programId（项目 ID）和 botId（数字员工 ID），后续所有操作依赖这两个ID。

1.1 获取项目列表

GET /api/v1/external/programs

curl "https://api.halfcall.cn/api/v1/external/programs" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "total": 2,
    "list": [
      {
        "programId": "cmkhndatf000jdulm6ez8ojyf",
        "name": "事半AI客服",
        "runState": "PAUSED",
        "executionMode": "Stream"
      }
    ]
  }
}

响应字段说明：

1.2 获取项目下数字员工列表

GET /api/v1/external/programs/:programId/bots

curl "https://api.halfcall.cn/api/v1/external/programs/cmk.../bots" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "bots": [
      {
        "botId": "bot_xxx",
        "name": "小智",
        "stage": 1,
        "isEnabled": true,
        "hotInitStatus": "NONE"
      }
    ]
  }
}

响应字段说明：

1.3 查询线路状态

GET /api/v1/external/programs/:programId/line-status

查询项目当前线路使用情况，可用于判断是否有空闲线路可发起外呼。

curl "https://api.halfcall.cn/api/v1/external/programs/cmk.../line-status" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "programId": "cmk...",
    "runState": "RUNNING",
    "maxConcurrency": 50,
    "currentConcurrency": 12,
    "idle": 38
  }
}

响应字段说明：

小程序集成建议：在发起外呼前先调用此接口，当 idle > 0 且 runState = "RUNNING" 时再推送线索。

1.4 获取线路列表

GET /api/v1/external/trunks

获取当前企业可读取到的线路——包含本企业名下的线路，以及对本企业开放的共享线路（不区分项目）。

curl "https://api.halfcall.cn/api/v1/external/trunks" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "trunkId": "trunk_xxx",
        "name": "北京-移动专线",
        "description": "示例线路",
        "status": "Normal",
        "trunkType": "SIP",
        "operators": "CMCC",
        "showPhoneType": "FixedLine",
        "outerCaller": "010xxxxxxx",
        "whitelistCity": "北京",
        "concurrency": 50,
        "callRate": 3000,
        "startTime": "2024-01-01T00:00:00.000Z",
        "endTime": "2024-12-31T23:59:59.000Z",
        "scope": "own"
      }
    ]
  }
}

响应字段说明：

1.5 获取音色列表

GET /api/v1/external/voices

获取当前企业可读取到的音色（TTS 模型）——包含全局共享音色，以及本企业专属克隆音色，用于配置数字员工时参考。

curl "https://api.halfcall.cn/api/v1/external/voices" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "total": 3,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "voiceModelId": "model_xxx",
        "name": "佳音",
        "model": "speech-2.8-hd",
        "voice": "voice_id_xxx",
        "price": 0.01,
        "status": "active",
        "scope": "shared",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "bots": [
          { "botId": "bot_xxx", "name": "小智" }
        ]
      }
    ]
  }
}

响应字段说明：

二、AI 外呼

线索排队与拨打机制说明（常见问题，建议先看一遍）：

• 同号覆盖：同一手机号在同一天内重复推送线索（无论批量上传还是 2.3 实时单条），会覆盖当天已有的线索记录并重新置为待拨状态——即使旧记录已经拨打完成，也会被重新拉回排队。如果同一天同一号码有多个独立通知都需要送达（比如同一人当天多场会议），目前无法在同一 programId 下同时保留多条待拨记录，请拆分到不同 programId 推送，或错开到不同自然日推送。
• 暂停期间推送：项目处于 PAUSED 时推送的线索会正常入队（状态 WAITING），不会丢失，也无需重推；项目恢复 RUNNING 后会自动开始拨打这些线索。
• 时段外排队：不在工作时段内推送的线索会保持排队，到下一个允许拨打时段自动补呼；目前没有过期时间（会一直排队到拨出或被撤销为止）。如果线索已经推送但临时不需要再拨了（比如会议被取消），可调用 2.8 撤销线索 撤回。
• 未接通重拨：平台内置随访重拨策略（默认关闭，需联系管理员开启），重拨的退避间隔与最大次数由平台侧配置，暂不支持通过 API 查询或修改。开启后，重拨产生的每一通电话都会作为独立记录出现在 2.5/2.7 查询接口返回的 calls[] 里。建议提前和平台确认好重拨策略由哪边负责，避免和自建的重推逻辑重复打扰用户。

2.1 线索导入（批量上传）

步骤一：下载该数字员工的线索 Excel 模板

GET /api/v1/external/programs/:programId/leads/template

curl -O -J "https://api.halfcall.cn/api/v1/external/programs/cmk.../leads/template?botId=bot_xxx" \
  -H "Authorization: Bearer sk_xxx"

返回 .xlsx 文件，第一行为表头（字段由数字员工话术配置决定），例如：

表头列名即为上传时的字段映射依据，请勿修改列名，否则上传会报字段不匹配错误。

步骤二：按模板填写数据后上传

POST /api/v1/external/programs/:programId/leads/upload

curl -X POST "https://api.halfcall.cn/api/v1/external/programs/cmk.../leads/upload" \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@/path/to/leads.xlsx" \
  -F "botId=bot_xxx" \
  -F "name=茅台外呼-第一批"

{
  "code": 0,
  "data": {
    "threadId": "thread_xxx",
    "name": "茅台外呼-第一批",
    "total": 980,
    "skipped": 20
  }
}

响应字段说明：

2.2 查询线索字段定义

GET /api/v1/external/programs/:programId/leads/fields

在推送线索之前先调用一次，拿到该数字员工 variables 需要传的准确字段 key（而不是 Excel 模板里看到的中文列名）。

curl "https://api.halfcall.cn/api/v1/external/programs/cmk.../leads/fields" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "programId": "cmk...",
    "botId": "bot_xxx",
    "fields": [
      { "key": "org_name", "name": "单位名称", "required": true },
      { "key": "contact_name", "name": "联络员姓名", "required": true },
      { "key": "meeting_title", "name": "会议主题", "required": true }
    ]
  }
}

key 就是 2.3 节 variables 里要用的字段名；name 只是给人看的中文标签，不要把 name 当 key 传（会被拒绝，见下方校验说明）。

2.3 线索导入（实时单条）

POST /api/v1/external/leads

适合用户实时触发场景（如刚填写表单），立即入队等待外呼。

curl -X POST "https://api.halfcall.cn/api/v1/external/leads" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "cmkhndatf000jdulm6ez8ojyf",
    "phone": "13800138000",
    "variables": { "org_name": "示例公司", "contact_name": "张三" }
  }'

{
  "code": 0,
  "threadId": "detail_xxx",
  "phone": "13800138000",
  "message": "Lead has been queued for processing"
}

响应字段说明：

字段校验：variables 会按该数字员工的字段定义校验——传了未知字段、或缺了必填字段，都会直接返回 400 并在 msg 里说明具体字段，线索不会入队。校验通过前后的 key 均按 2.2 节的 key 处理（若传的是 name 会被自动转换）。

2.4 启动项目

线索上传后，需启动项目才会开始外呼。

POST /api/v1/external/programs/:programId/run-state

curl -X POST "https://api.halfcall.cn/api/v1/external/programs/cmk.../run-state" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"action": "start"}'

{ "code": 0, "data": { "programId": "cmk...", "runState": "RUNNING" } }

响应字段说明：

2.5 查询线索通话结果

通话结束后，可主动查询线索的通话记录和意向分析结果。

GET /api/v1/external/leads

# 方式1：通过推送线索时返回的 threadId
curl "https://api.halfcall.cn/api/v1/external/leads?threadId=detail_xxx" \
  -H "Authorization: Bearer sk_xxx"

# 方式2：通过 programId + phone
curl "https://api.halfcall.cn/api/v1/external/leads?programId=cmk...&phone=13800138000" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "threadDetailId": "detail_xxx",
    "phone": "13800138000",
    "status": "COMPLETED",
    "stage": 1,
    "variables": { "name": "张三" },
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:01:30.000Z",
    "calls": [
      {
        "callId": "call_xxx",
        "reached": "REACHED",
        "duration": 120,
        "intention": "HIGH",
        "intentionRate": 85,
        "summary": "客户感兴趣，约好明天回电",
        "recordingUrl": "https://cdn.halfcall.cn/rec/xxx.mp3",
        "extractData": { "interested": true },
        "createdAt": "2024-01-01T00:01:00.000Z"
      }
    ]
  }
}

响应字段说明：

calls[].reached 枚举值（2026-08 更新，此前版本文档写的 REACHED/NO_ANSWER/BUSY/FAILED 已过时，请以下表为准；"平台展示"列是登录 Web 工作台查看通话记录时看到的中文文案，方便和客服对话时对齐口径）：

判断"是否接通"建议用 reached in [REACHED, AGENT_END, SEAT_END, USER_END]，或者用 duration > 0 兜底。

如果您同时登录了平台 Web 工作台查看通话记录，会看到"已接通"/"未接通"两个汇总筛选项——"已接通"就是上表"是否接通=是"的四个值汇总；"未接通"是除这四个值之外的全部其余状态（含 INIT/PREPARE/DIALED 这类还没结果的中间态），比 API 语境里习惯理解的"未接通"范围更宽，两边对数据时注意口径差异。

calls[].intention 枚举值：NONE=未分析或不适用，REACHED=已接通但尚未分类，HIGH=高意向，HESITATE=犹豫，LOW_DIFFICULTY/HIGH_DIFFICULTY=意向分类（原文档 LOW 已废弃，这两个新值的具体业务含义正在和研发确认，暂按字面理解，后续版本会补充准确释义），UNKNOW=未知。

通话刚挂断时 intention 可能短暂返回 UNKNOW（AI 需要基于转写文本做后置分析，有几秒延迟），过几秒重查即可拿到最终结果。

2.6 拨打配置（可选）

GET /api/v1/external/programs/:programId/dialing-config — 查询当前配置

PUT /api/v1/external/programs/:programId/dialing-config — 修改配置（字段均可选，只传需要修改的）

curl -X PUT "https://api.halfcall.cn/api/v1/external/programs/cmk.../dialing-config" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "maxConcurrency": 30,
    "workTimeConfig": {
      "callTimeSlots": [
        { "id": "slot-1", "start": 540, "end": 1080, "days": [1,2,3,4,5] }
      ]
    }
  }'

{
  "code": 0,
  "data": {
    "programId": "cmk...",
    "runState": "RUNNING",
    "maxConcurrency": 30,
    "priorityStrategy": "LIFO",
    "workTimeConfig": {
      "callTimeSlots": [
        { "id": "slot-1", "start": 540, "end": 1080, "days": [1,2,3,4,5] }
      ]
    },
    "blockStartTime": null,
    "blockEndTime": null
  }
}

字段说明：

2.7 批量查询线索

GET /api/v1/external/leads/batch

相比 2.5（每次只能查一条），本接口支持一次查询多条线索，或者按项目 + 日期批量拉取当天的拨打记录，适合替代逐条轮询、批量核对"哪些线索还没接通"。

# 方式1：按线索 ID 列表批量查询
curl "https://api.halfcall.cn/api/v1/external/leads/batch?threadIds=detail_1,detail_2,detail_3" \
  -H "Authorization: Bearer sk_xxx"

# 方式2：按项目 + 日期拉取当天的线索
curl "https://api.halfcall.cn/api/v1/external/leads/batch?programId=cmk...&date=2026-08-20" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "total": 128,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "threadDetailId": "detail_xxx",
        "phone": "13800138000",
        "programId": "cmk...",
        "status": "COMPLETED",
        "stage": 1,
        "createdAt": "2026-08-20T09:00:00.000Z",
        "updatedAt": "2026-08-20T09:03:00.000Z",
        "latestCall": {
          "callId": "call_xxx",
          "reached": "USER_END",
          "duration": 120,
          "intention": "HIGH",
          "intentionRate": 85,
          "summary": "客户感兴趣，约好明天回电",
          "createdAt": "2026-08-20T09:01:00.000Z"
        }
      }
    ]
  }
}

响应字段说明：

目前该接口没有额外的调用频率限制，但仍建议按需拉取（比如按 date 增量轮询），避免一次性拉取过大范围的数据。

2.8 撤销线索

POST /api/v1/external/leads/cancel

撤销尚未拨打（排队中）的线索，适合"线索已经推送，但情况有变不需要再打了"的场景（比如会议被取消）。只能撤销当前仍处于排队中的线索；已经开始拨打或已完成的线索不受影响，也不会报错。

# 撤销单条线索
curl -X POST "https://api.halfcall.cn/api/v1/external/leads/cancel" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "threadDetailId": "detail_xxx" }'

# 撤销某项目下全部排队中的线索
curl -X POST "https://api.halfcall.cn/api/v1/external/leads/cancel" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "programId": "cmk..." }'

{ "code": 0, "data": { "cancelled": 1 } }

响应字段说明：

注意事项：

• threadDetailId 和 programId 只能二选一。
• 按 threadDetailId 撤销时，如果该线索已经开始拨打或已结束（不再是排队中），接口会返回 409 并说明当前状态，不会误撤正在进行或已完成的通话。
• 按 programId 撤销时，只影响调用瞬间仍处于排队中的线索；如果撤销请求发出的同时某条线索恰好被自动拨号器拾取开始拨打，那一条会被跳过（不计入 cancelled）。
• 撤销后的线索不会再出现在自动拨号队列里，但历史记录仍可通过 2.5/2.7 查询到（status 会变化）。

三、AI 呼入接入

3.1 参数说明

AI 呼入支持通过 SIP Header 传入自定义参数，系统接收后在提示词中替换对应变量，实现个性化呼入体验。参数需提前在平台配置好字段定义，以下为示例（实际字段以平台配置为准）：

3.2 SIP Header 说明

3.3 参数编码

将所有参数组成 JSON 对象，整体做 Base64 编码后放入 sip_h_X-Call-Params：

function encodeCallParams(params) {
  return Buffer.from(JSON.stringify(params)).toString('base64')
}

const encoded = encodeCallParams({
  user_phone: "18888888888",
  variable3: "张三",
  variable10: "150.00",
  variable2: "200.00",
  variable4: "250.00",
  variable9: "18811111111",
})
// eyJ1c2VyX3Bob25lIjoiMTg4ODg4ODg4ODgiLCJ2YXJpYWJsZTMiOiLlvKDkuIkiLCJ2YXJpYWJsZTEwIjoiMTUwLjAwIiwidmFyaWFibGUyIjoiMjAwLjAwIiwidmFyaWFibGU0IjoiMjUwLjAwIiwidmFyaWFibGU5IjoiMTg4MTExMTExMTEifQ==

3.4 FreeSWITCH 转发示例

originate {
  ignore_early_media=true,
  origination_uuid=001
} user/1001 &bridge({
  sip_h_X-BotId=85488662,
  sip_h_X-Call-Params=eyJ1c2VyX3Bob25lIjoiMTg4ODg4ODg4ODgiLCJ2YXJpYWJsZTMiOiLlvKDkuIkiLCJ2YXJpYWJsZTEwIjoiMTUwLjAwIiwidmFyaWFibGUyIjoiMjAwLjAwIiwidmFyaWFibGU0IjoiMjUwLjAwIiwidmFyaWFibGU5IjoiMTg4MTExMTExMTEifQ==,
  sip_h_X-Call-ID=callid_20250720_083123,
  ignore_early_media=false,
  origination_uuid=001
} sofia/external/sip:85488662@115.190.223.167:5080)

sip_h_X-Call-ID 建议格式：callid_{yyyyMMdd}_{HHmmss}_{随机串}，通话结束后可凭此 ID 通过回调接收或主动查询结果。

话单回调：通话结束后系统会主动向业务服务器推送话单（含通话记录、意向结果、对话日志），推送地址/签名规则/请求体等说明见 Webhook 参考。

四、话术管理（可选）

如需通过 API 动态更新数字员工的话术内容，可使用以下接口。

4.1 读取当前话术

GET /api/v1/external/bots/:botId/script

curl "https://api.halfcall.cn/api/v1/external/bots/bot_xxx/script" \
  -H "Authorization: Bearer sk_xxx"

{
  "code": 0,
  "data": {
    "botId": "bot_xxx",
    "botName": "小智",
    "scriptId": "script_xxx",
    "scriptName": "茅台外呼话术",
    "scriptVersion": 5,
    "hotInitStatus": "NONE",
    "prompt": "你是一名茅台集团的销售代表..."
  }
}

响应字段说明：

4.2 更新话术

PUT /api/v1/external/bots/:botId/script

curl -X PUT "https://api.halfcall.cn/api/v1/external/bots/bot_xxx/script" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "你是一名茅台集团的销售代表..." }'

{ "code": 0, "msg": "success", "data": { "botId": "bot_xxx", "scriptId": "script_xxx" } }

注意： 话术更新后不会立即生效，需在平台手动触发"重新初始化"（hotInitStatus 变为 PENDING），AI 重新生成配置后新话术才会被使用。

错误码