基础查询

获取项目列表、数字员工列表、线路状态、音色列表，以及创建项目、关联数字员工。

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

1.1 获取项目列表

GET /api/v1/external/programs（所需权限：READ）

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（所需权限：READ）

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（所需权限：READ）

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

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（所需权限：READ）

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

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（所需权限：READ）

获取当前企业可读取到的音色（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",
        "previewUrl": "https://cdn.halfcall.cn/tts_preview/external/halfcall/model_xxx.mp3",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "bots": [
          { "botId": "bot_xxx", "name": "小智" }
        ]
      }
    ]
  }
}

响应字段说明：

1.6 创建项目

POST /api/v1/external/programs（所需权限：CONTROL）

注意： hashrateFee（算力费）/callFee（电话费）不支持通过 API 指定，创建时自动按贵企业所属渠道的配置价填入（渠道未配置则用平台默认价）——这两个字段线上是强管控的计费口径，不开放给外部调用方。

curl -X POST "https://api.halfcall.cn/api/v1/external/programs" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "国庆促销外呼",
    "trunkIds": ["trunk_xxx"],
    "bots": [{ "botId": "bot_xxx", "stage": 1 }]
  }'

{ "code": 0, "msg": "success", "data": { "programId": "prog_xxx", "name": "国庆促销外呼", "runState": "PAUSED" } }

1.7 关联数字员工

PUT /api/v1/external/programs/:programId/bots（所需权限：CONTROL）

整份替换：传入的 bots 数组会完全替换该项目当前的数字员工配置（先清空再按传入列表重建），不是增量添加/删除——如果项目已经关联了 3 个数字员工，这次只传 1 个，另外 2 个会被移除。需要"只加一个"的效果，请先用 1.2「获取项目下数字员工列表」读出现有配置，拼接后整份传入。

curl -X PUT "https://api.halfcall.cn/api/v1/external/programs/prog_xxx/bots" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "bots": [{ "botId": "bot_xxx", "stage": 1 }, { "botId": "bot_yyy", "stage": 2 }] }'

{ "code": 0, "msg": "success", "data": { "programId": "prog_xxx", "botCount": 2 } }