话术与配置

通过 API 远程读写数字员工的话术提示词、音色、提取字段与意向推送配置。

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

4.1 读取当前话术

GET /api/v1/external/bots/:botId/script（所需权限：READ）

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": "你是一名茅台集团的销售代表...",
    "greeting": "您好，我是茅台系列酒运营中心的...",
    "clueItems": [
      { "key": "user_phone", "name": "电话号码", "description": "必填，会根据用户信息", "cannotEdit": true, "required": true },
      { "key": "phone4", "name": "手机尾号", "description": "当前用户手机号码后四位", "cannotEdit": true },
      { "key": "current_time", "name": "当前时间", "description": "Agent 自动获取本地时间", "cannotEdit": true },
      { "key": "company_name", "name": "公司名称", "description": "本平台对外品牌名称" }
    ],
    "transferEnabled": true,
    "transferItems": [
      { "key": "transfer_phone", "name": "转接手机号", "description": "转接目标用户的手机号" }
    ]
  }
}

响应字段说明：

字段	说明
scriptVersion	话术版本号，每次更新自动 +1，可用于判断是否有变更
hotInitStatus	AI 配置状态：`NONE`=正常可用，`PENDING`=等待重新初始化，`UPGRADING`=初始化中，`FAILED`=初始化失败
prompt	话术原始提示词，即数字员工对话策略的源头文本
greeting	欢迎语（开场白），通话/对话开始时先播报的固定文本，不是 AI 生成的
clueItems	线索数据：供 `prompt`/`greeting` 里 `{key}` 模板变量引用的输入字段定义。`cannotEdit=true` 是系统内置字段（user_phone/phone4/current_time），不可通过 API 修改/删除；其余是可自定义增删的字段。注意跟 4.4/4.5 的提取配置是两回事——这里是通话/对话开始前就有的输入变量，提取配置是通话结束后从对话内容里提取出的数据
transferEnabled	是否开启转人工线索收集
transferItems	转接用户线索字段定义（如 transfer_phone）

4.2 更新话术

PUT /api/v1/external/bots/:botId/script（所需权限：SCRIPT）

Body 字段全部可选，至少传一个：

字段	类型	说明
prompt	string	话术提示词
greeting	string	欢迎语（开场白），只覆盖第一句欢迎语；多句欢迎语的话术暂不支持通过 API 修改
clueItems	array	线索数据字段 `[{key, name, description, required?}]`。系统内置字段（user_phone/phone4/current_time）不受影响，会自动保留；这里只整份替换自定义字段部分
transferEnabled	boolean	是否开启转人工线索收集
transferItems	array	转接用户线索字段 `[{key, name, description, required?}]`，整份替换

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": "你是一名茅台集团的销售代表...",
    "greeting": "您好，我是茅台系列酒运营中心的...",
    "clueItems": [
      { "key": "company_name", "name": "公司名称", "description": "本平台对外品牌名称" }
    ]
  }'

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

注意： 更新会立即生效（写库后同步刷新缓存），无需在平台手动触发"重新初始化"。

4.3 配置音色

PUT /api/v1/external/bots/:botId/voice（所需权限：SCRIPT）

Body 字段全部可选，至少传一个：

字段	类型	说明
voiceModelId	string	音色 ID，取自 1.5 获取音色列表返回的 `voiceModelId`
speed	number	语速
volume	number	音量
pitch	number	音调
emotion	string	情绪（是否支持、可选值由所选音色的供应商决定）

curl -X PUT "https://api.halfcall.cn/api/v1/external/bots/bot_xxx/voice" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "voiceModelId": "voice_xxx", "speed": 1.1, "volume": 1.0, "pitch": 0 }'

{ "code": 0, "msg": "success", "data": { "botId": "bot_xxx", "voiceModelId": "voice_xxx", "speed": 1.1, "volume": 1.0, "pitch": 0 } }

注意： voiceModelId 必须是当前企业可见的音色（全局共享音色，或本企业专属音色），传入其它企业的专属音色会返回 400。更新会立即生效，无需手动重新初始化。

4.4 读取提取配置

GET /api/v1/external/bots/:botId/extract（所需权限：READ）

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

{
  "code": 0,
  "data": {
    "botId": "bot_xxx",
    "scriptId": "script_xxx",
    "prompt": "从对话中提取客户的...",
    "items": [
      { "key": "company", "name": "公司名称", "description": "客户所在公司名称" }
    ],
    "pushType": "wechat",
    "pushOnlyIntent": true,
    "pushTitle": "高意向客户提醒",
    "pushWebhook": "wxid_xxx",
    "pushTarget": "person"
  }
}

响应字段说明：

字段	说明
prompt	提取提示词，指导 AI 从对话中提取哪些信息
items	待提取字段列表，每项 `{key, name, description}`
pushType	意向推送方式：`none`/`feishu`/`wechat`/`dingtalk`/`api`
pushOnlyIntent	是否只推送高意向数据
pushTitle	推送标题
pushWebhook	推送目标（企微/飞书/钉钉机器人 webhook 地址，或微信场景下的群 ID / 好友 wxid）
pushTarget	微信渠道专用，推送到 `group`（群）还是 `person`（个人好友）

4.5 更新提取配置

PUT /api/v1/external/bots/:botId/extract（所需权限：SCRIPT）

Body 字段全部可选，至少传一个，只更新传入的字段：

字段	类型	说明
prompt	string	提取提示词
items	array	待提取字段列表 `[{key, name, description}]`
pushType	string	`none`/`feishu`/`wechat`/`dingtalk`/`api`
pushOnlyIntent	boolean	是否只推送高意向数据
pushTitle	string	推送标题
pushWebhook	string	推送目标
pushTarget	string	`group`/`person`（微信渠道专用）
pushAppKey	string	推送签名/凭证（视渠道而定）
feishuAppId / feishuAppSecret / feishuSignSecret	string	飞书推送凭证（pushType=feishu 时需要）
dingtalkSecret	string	钉钉加签密钥（pushType=dingtalk 时需要）

curl -X PUT "https://api.halfcall.cn/api/v1/external/bots/bot_xxx/extract" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "从对话中提取客户的公司名称和预算",
    "items": [{ "key": "company", "name": "公司名称", "description": "客户所在公司名称" }],
    "pushType": "wechat",
    "pushOnlyIntent": true,
    "pushTarget": "person",
    "pushWebhook": "wxid_xxx"
  }'

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

注意： 本接口只覆盖"提取字段"和"意向推送配置"这两部分；推送重试机制、推送时间窗口、话单推送、用户推送（短信/加微）等其它配置暂不支持通过 API 修改，需在平台上手动配置。更新会立即生效，无需手动重新初始化。