AI 外呼 Open API 对接文档

文档版本：v5.2
API Base URL：https://api.dxbcrm.cn/open_api/ai_call

1. 概述

1.1 功能说明

通过本接口可完成 AI 电话机器人外呼全流程：

• 获取 线路、Agent 列表
• 创建 / 修改 / 删除 外呼任务
• 导入号码、启动 / 暂停 外呼
• 注册话单回调、主动 拉取话单、查询 话费余额

Agent 在 BOSS 后台 配置并审核通过后，对接方通过 API 选择资源、创建任务、启停外呼并接收话单。

1.2 Agent 类型（agent_type）

1.3 接口清单

2. 鉴权与通用规范

2.1 开通凭证

商务开通后，对接方将获得以下凭证：

线路与 Agent 由运营在后台为业务账户配置；对接方通过 task_options 接口查询可用资源。

2.2 请求头

所有接口均需在 HTTP Header 中携带以下字段：

2.3 签名算法

TOKEN = MD5(secret + OID + T).toUpperCase()

Python 示例

import hashlib
import time

secret = "your_secret_key"
oid = "12345"
tid = "65804"
t = str(int(time.time()))
token = hashlib.md5(f"{secret}{oid}{t}".encode()).hexdigest().upper()

headers = {
    "OID": oid,
    "TID": tid,
    "T": t,
    "TOKEN": token,
    "Content-Type": "application/json",
}

cURL 示例

OID="12345"
TID="65804"
SECRET="your_secret_key"
T=$(date +%s)
TOKEN=$(echo -n "${SECRET}${OID}${T}" | md5sum | awk '{print toupper($1)}')

curl -s "https://api.dxbcrm.cn/open_api/ai_call/call_balance" \
  -H "OID: ${OID}" \
  -H "TID: ${TID}" \
  -H "T: ${T}" \
  -H "TOKEN: ${TOKEN}"

2.4 统一响应格式

{
  "code": 0,
  "msg": "操作成功",
  "data": {}
}

3. 对接流程

1. 商务开通 OID / secret / TID；在 BOSS 配置 Agent，运营配置线路
2. POST /register_callback_url（register_type=realtime）注册话单回调
3. GET  /task_options → 获取 line_id、agent_id、agent_type
4. POST /task_manage → 创建外呼任务
5. POST /import_phone → 导入号码（可设 auto_run=1 自动启动）
6. 或通过 PATCH /task_manage 设置 target_status=5 启动、=6 暂停
7. 接收 Webhook 话单推送，或 POST /call_record 主动拉取

4. 接口详情

4.1 获取线路与 Agent 资源

GET /open_api/ai_call/task_options

Query 参数

响应示例

{
  "code": 0,
  "msg": "",
  "data": {
    "line_data": [
      { "id": 101, "line_name": "机器人线路A" }
    ],
    "team_max_concurrent": 50,
    "agent_data": [
      {
        "agent_id": 2001,
        "agent_name": "销售话术",
        "agent_type": 1,
        "note": "",
        "dialog_id": 68429,
        "is_tts": 0,
        "actor_id": 1243
      },
      {
        "agent_id": 10086,
        "agent_name": "销售助手",
        "agent_type": 2,
        "note": ""
      }
    ]
  }
}

4.2 创建 / 修改任务

POST /open_api/ai_call/task_manage

请求示例（推荐）

{
  "task_name": "外呼任务",
  "agent_type": 2,
  "agent_id": 10086,
  "max_concurrency": 10,
  "line_id": 101,
  "valid_week": [1, 2, 3, 4, 5],
  "work_time": ["09:00:00", "20:00:00"],
  "push_willing_level": [1, 2, 3, 4]
}

兼容请求（向量相似度老对接方）

仅使用向量相似度算法（agent_type=1）时，可不传 agent_type，改用 dialog_res_id：

{
  "task_name": "外呼任务",
  "max_concurrency": 10,
  "line_id": 101,
  "task_type": 3,
  "dialog_res_id": 2001,
  "valid_week": [1, 2, 3, 4, 5],
  "work_time": ["09:00:00", "20:00:00"],
  "push_willing_level": [1, 2, 3, 4]
}

字段说明

响应示例

{
  "code": 0,
  "msg": "操作成功",
  "data": {
    "task_id": 98765,
    "agent_type": 2
  }
}

4.3 启动 / 暂停任务

PATCH /open_api/ai_call/task_manage

请求示例

{
  "task_id": 98765,
  "target_status": 5
}

话费余额不足时返回错误码 838。

4.4 删除任务

DELETE /open_api/ai_call/task_manage

请求示例

{ "task_id": 98765 }

4.5 任务列表

GET /open_api/ai_call/task_list

Query 参数

响应示例

{
  "code": 0,
  "msg": "",
  "data": {
    "total": 1,
    "task_list": [
      {
        "task_id": 98765,
        "task_name": "外呼任务",
        "task_status": 5,
        "phone_count": 100,
        "uncalled_count": 60,
        "percent": "40.0%",
        "agent_type": 2,
        "agent_id": 10086,
        "agent_name": "销售助手"
      }
    ]
  }
}

4.6 导入号码

POST /open_api/ai_call/import_phone

请求示例

{
  "task_id": 98765,
  "phone_list": [
    {
      "phone_number": "13800138000",
      "name": "张三",
      "company": "某某公司",
      "note": "",
      "address": "",
      "variables": { "product": "年卡" }
    }
  ],
  "auto_run": 1,
  "is_async": 1
}

字段说明

同一批次内按 phone_number 自动去重，重复号码仅保留第一条。

4.7 拉取话单

POST /open_api/ai_call/call_record

请求示例

{
  "page": 1,
  "task_id": 98765,
  "phone_number": "",
  "call_time": ["2026-07-01", "2026-07-10"]
}

响应示例

{
  "code": 0,
  "msg": "",
  "data": {
    "total": 1,
    "result": [
      {
        "phone_number": "13800138000",
        "c_name": "张三",
        "call_status": 1,
        "call_len": 45,
        "call_time": "2026-07-10 14:30:00",
        "willing_id": 1,
        "task_id": 98765,
        "record_url": "https://api.dxbcrm.cn/nas/playback/xxx.mp3?call_date=2026-07-10",
        "agent_type": 2,
        "agent_id": 10086,
        "agent_name": "销售助手"
      }
    ]
  }
}

4.8 话费余额

GET /open_api/ai_call/call_balance

响应示例

{
  "code": 0,
  "msg": "查询成功",
  "data": {
    "user_balance": [
      { "name": "话费余额", "balance": "128.50元" }
    ]
  }
}

4.9 注册回调

POST /open_api/ai_call/register_callback_url

请求示例

{
  "callback_url": "https://partner.example.com/webhook/cdr",
  "register_type": "realtime"
}

按 OP 维度注册，同类型重复注册将覆盖旧地址。

5. 回调推送（平台 → 对接方）

对接方需提供可公网访问的 HTTPS 地址，并在收到推送后 5 秒内 返回：

{ "code": 0, "msg": "ok" }

5.1 实时话单（realtime）

推送 Body 示例

{
  "callback_type": "realtime",
  "tid": 65804,
  "task_id": 98765,
  "phone_number": "13800138000",
  "c_name": "张三",
  "company": "某某公司",
  "note": "",
  "address": "",
  "call_status": 1,
  "call_len": 45,
  "call_time": "2026-07-10 14:30:00",
  "dialog_round": 6,
  "willing_id": 1,
  "record_url": "https://api.dxbcrm.cn/nas/playback/xxx.mp3?call_date=2026-07-10",
  "dialog_name": "销售助手",
  "actor_name": "",
  "agent_type": 2,
  "agent_id": 10086,
  "agent_name": "销售助手",
  "is_complete": 1,
  "topic_info": [],
  "dialog_txt": [
    { "seq_id": 1, "speaker": 0, "text": "您好..." },
    { "seq_id": 2, "speaker": 1, "text": "你好" }
  ]
}

主要字段说明

5.2 任务完成 / 导入完成

任务完成（task_result）

{ "callback_type": "task_result", "task_id": 98765, "tid": 65804 }

号码导入完成（task_upload）

{ "callback_type": "task_upload", "task_id": 98765, "tid": 65804 }

6. 错误码

7. 附录

7.1 任务状态 task_status

7.2 意向等级 willing_id

7.3 Agent 类型 agent_type