外呼任务 API

简述

携带租户 API Key 请求 /api/v1/open/engagement，可管理：

• 外呼任务模板（字段、话术）
• 人工外呼任务（坐席手工拨打、分配对象）
• 自动外呼任务（IVR / 机器人 / 坐席预测式外呼）

数据与 触达中心 共用；API 创建的任务与发送对象不绑定员工账号。API Key 仅用于服务端，勿写入前端或 App。

适用场景

接入前准备

自动外呼依赖项对照：

若 execution_mode 为 bot，还需：

界面下拉框通常只显示名称；可在 客服工作台 → 触达中心 → 自动外呼任务 → 新建 选好各项后，从浏览器创建请求或 GET 任务详情中读取对应 ID。

接口前缀：

{OpenDesk地址}/api/v1/open/engagement

鉴权 Header（JSON 接口必填）：

Authorization: Bearer sk-odk-您的密钥
Content-Type: application/json

说明：

• 鉴权仅认 Authorization Header 中的 API Key。
• 数据限定在当前 Key 所属租户；跨租户 ID 返回 404。
• Key 无效 → 401；已禁用 → 403。
• API 创建的任务不关联具体员工。

概念说明

整体流程

人工外呼（推荐顺序）

① GET  外呼任务模板列表 → 确认 template_id
        ↓
② POST 创建人工外呼任务（draft 或 publish=true 直接激活）
        ↓
③ POST 批量添加发送对象（JSON bulk 或 Excel import）
        ↓
④ POST 发布任务（若创建时为 draft）
        ↓
⑤ GET  查询对象 / 外呼记录，对账进度
        ↓
⑥ POST 暂停 / 恢复 / 归档（运维控制）

自动外呼（推荐顺序）

① GET  外呼任务模板列表 → 确认 template_id
        ↓
② POST 创建自动外呼任务（status=draft，配置 execution_mode 与接待目标）
        ↓
③ POST 批量添加发送对象
        ↓
④ POST 启动任务 start
        ↓
⑤ GET  stats / monitor / records 监控与复盘
        ↓
⑥ POST 暂停 / 恢复 / 归档；draft 状态可 DELETE 删除

如何使用

第一步：创建 API Key

1. 超级管理员登录 管理后台 → 全局设置 → API Key。
2. 新建 Key（如「CRM 外呼同步」「营销自动外呼」），保存完整 sk-odk-...。
3. 在脚本或密钥管理系统中配置，勿提交至 Git。

第二步：准备外呼任务模板

查询已有模板：

curl "{OpenDesk地址}/api/v1/open/engagement/outbound-task-templates?page=1&per_page=20" \
  -H "Authorization: Bearer sk-odk-您的密钥"

若无合适模板，可新建（含自定义字段）：

curl -X POST "{OpenDesk地址}/api/v1/open/engagement/outbound-task-templates" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "会员到期提醒",
    "description": "CRM 同步用",
    "fields": [
      {
        "key": "member_name",
        "name": "会员姓名",
        "field_type": "text",
        "required": true,
        "show_in_list": true
      },
      {
        "key": "expire_date",
        "name": "到期日",
        "field_type": "date",
        "required": false,
        "show_in_list": true
      }
    ]
  }'

响应中的 id 即为后续创建任务时的 template_id。

话术（可选）： 模板可配置外呼话术树。单独维护话术时使用：

• GET/PUT .../outbound-task-templates/{template_id}/script

话术为树形结构：含 开始 / 话术 / 分支 / 结束 节点，创建任务时会 快照 至任务，后续改模板不影响已创建任务。

第三步：创建人工外呼任务并导入对象

创建任务（草稿）：

curl -X POST "{OpenDesk地址}/api/v1/open/engagement/outbound-tasks" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "3月会员回访",
    "template_id": 1,
    "description": "CRM 自动下发",
    "starts_at": "2026-03-01T09:00:00",
    "due_at": "2026-03-31T18:00:00",
    "allow_self_claim": true,
    "default_redial_interval_minutes": 120,
    "publish": false
  }'

批量添加发送对象（JSON，单次最多 5000 条）：

curl -X POST "{OpenDesk地址}/api/v1/open/engagement/outbound-tasks/{task_id}/targets/bulk" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {
        "phone_number": "13800138000",
        "assignee_id": null,
        "field_values": {
          "member_name": "张三",
          "expire_date": "2026-03-15"
        }
      }
    ]
  }'

Excel / CSV 导入（multipart）：

curl -X POST "{OpenDesk地址}/api/v1/open/engagement/outbound-tasks/{task_id}/targets/import" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -F "file=@targets.xlsx"

响应含 total、created、failed 及逐行 errors（最多返回 100 条错误明细）。

发布任务：

curl -X POST "{OpenDesk地址}/api/v1/open/engagement/outbound-tasks/{task_id}/publish" \
  -H "Authorization: Bearer sk-odk-您的密钥"

发布前须至少添加 1 个 发送对象；仅 草稿 或 已暂停 任务可发布。

第四步：创建并启动自动外呼任务

创建自动外呼任务（IVR 示例）：

curl -X POST "{OpenDesk地址}/api/v1/open/engagement/auto-outbound-tasks" \
  -H "Authorization: Bearer sk-odk-您的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "3月到期 IVR 提醒",
    "template_id": 1,
    "execution_mode": "ivr",
    "voice_flow_id": 12,
    "start_date": "2026-03-01",
    "end_date": "2026-03-31",
    "daily_time_windows": [
      {"start": "09:00", "end": "12:00"},
      {"start": "14:00", "end": "20:00"}
    ],
    "caller_number_id": "pn_1",
    "max_concurrency": 10,
    "daily_per_number_limit": 3
  }'

caller_number_id 为 号码管理 中号码的系统内部 ID（如 pn_1），不是界面显示的 400… 号码。

创建后任务为 草稿。导入发送对象后 启动：

curl -X POST "{OpenDesk地址}/api/v1/open/engagement/auto-outbound-tasks/{task_id}/start" \
  -H "Authorization: Bearer sk-odk-您的密钥"

启动前须至少 1 个 发送对象；仅 草稿 或 已暂停 可启动。

监控：

# 统计趋势、结果分布
curl "{OpenDesk地址}/api/v1/open/engagement/auto-outbound-tasks/{task_id}/stats" \
  -H "Authorization: Bearer sk-odk-您的密钥"

# 实时并发、坐席就绪、弃呼率等
curl "{OpenDesk地址}/api/v1/open/engagement/auto-outbound-tasks/{task_id}/monitor" \
  -H "Authorization: Bearer sk-odk-您的密钥"

任务状态与生命周期

人工外呼任务 status

状态流转：draft/paused → publish → active → pause → paused → resume → active；paused/completed → archive → archived。

自动外呼任务 status

发送对象状态（人工）

pending（待呼叫）· calling（呼叫中）· redial（待重拨）· completed（已完成）· do_not_call（勿呼）· invalid_number（无效号码）

发送对象状态（自动）

pending · calling · redial_pending · completed · invalid

接口速查

外呼任务模板

列表参数：page（默认 1）、per_page（默认 20）、q（名称搜索）。

人工外呼任务

任务列表参数：page、per_page（最大 200）、q、status、template_id。
对象列表参数：page、per_page、q、status、assignee_id。

批量分配请求体：

{
  "target_ids": [101, 102],
  "assignee_id": 5,
  "overwrite": false
}

overwrite=false 时跳过已有负责人的对象；assignee_id=null 表示取消分配。

自动外呼任务

自动外呼列表分页参数为 page、page_size（最大 200），另支持 q、status、mode（ivr / bot / agent）。

完整请求 / 响应 Schema 见 {OpenDesk地址}/docs（OpenAPI）。

错误与排查

外呼任务专项规则：

错误响应体示例：

{
  "code": "VALIDATION_ERROR",
  "message": "Please add outbound targets before publishing",
  "status": 400
}

安全与限制

1. API Key 仅部署在服务端；日志与监控不得打印完整 Key。
2. 生产 / 测试环境分离 Key；停用脚本后 禁用并删除 对应 Key。
3. 所有请求使用 HTTPS。
4. Open API 不走员工权限树；租户隔离完全由 Key 决定。
5. 本 API 不提供：坐席工作台实时外呼控制、WebRTC 签权、通话录音直链下载、短信群发（见触达中心其他能力）。

与其他功能的关系

• API Key（管理后台）：与本接口及《传递客户上下文》《知识库 API》共用鉴权凭证。
• 客服工作台 · 触达中心：API 写入的任务与发送对象在主管侧同一界面可见、可管理。
• 客服工作台 · 呼叫中心工作台：坐席在 我的外呼对象 执行人工外呼、填写业务字段与话术。
• 管理后台 · 流程设计 / 号码管理：自动外呼 IVR 模式依赖已配置的语音流程与主叫号码。
• CLI 工具：可使用 deepflow-opendesk-cli 的 outbound-templates 子命令维护模板；任务级 Open API 适合 CRM 批量集成。

对接示例

CRM 下发人工回访名单

每日凌晨将待回访手机号与会员字段写入人工外呼任务：

1. GET /outbound-task-templates?q=回访 取得 template_id
2. POST /outbound-tasks 创建草稿（若无进行中任务）
3. POST /outbound-tasks/{id}/targets/bulk 写入名单（每批 ≤5000）
4. POST .../publish 发布；后续批次继续 bulk 追加
5. GET .../targets?status=pending 对账剩余量

坐席在 呼叫中心工作台 → 我的外呼对象 中可见并外呼（须已发布且对象已分配或可认领）。

营销活动自动 IVR 外呼

1. POST /auto-outbound-tasks 配置 IVR、拨打窗口、并发
2. POST .../targets/import 上传 Excel
3. POST .../start 启动
4. 定时 GET .../stats 看接通率；异常则 POST .../pause
5. 结束 POST .../archive