立刻智能体平台 API 文档

概述

立刻智能体平台提供多组开放 HTTP API，覆盖 AI 会话、人工客服轮询、知识库写入、合作客商写入、服务绩效议题同步和推送通知。外部系统可按需选择接口，使用 API Key 鉴权发起请求；各接口的参数与响应以对应章节为准。

接入流程

Base URL

https://agent.likelic.com/api/v1

认证方式

所有 API 请求必须在 HTTP Headers 中携带以下两个认证字段，且两个凭证必须属于同一企业：

认证校验规则

智能对话接口 Core

POST /api/v1/chat

向智能体发送问题并获取 AI 回答。支持指定提示词模板和流式/非流式输出模式。

请求参数 (JSON Body)

关键词转人工（企业微信）

若企业已在控制台配置「企业微信 → 人工客服转接」（开启转人工推送并填写群机器人 Webhook、触发词），则开放 API 与网页组件、控制台 Chat 共用同一套触发词：当用户 question 中包含任一条触发词时，本次请求不会调用大模型，而是创建/续接人工会话，并向企微群推送卡片。

• session_id：首条转人工请求可不传，响应中的 session_id 须保存；后续用户与人工沟通过程中请继续传入同一 session_id，追问会推送到同一企微群线程。
• 响应：data.human_mode === true 表示已进入人工模式；data.answer 为提示文案；data.human_session_db_id 为内部会话主键（与群内卡片「会话记录ID」一致，供排障或对接工单）。
• 退出人工：用户发送结束类话术（与控制台人工会话一致）且传入当前 session_id 时，可结束会话并回到 AI。
• 流式：转人工在流式、非流式下均在调用模型之前判定；命中转人工时返回普通 JSON（非 SSE）。
• 按 API Key 控制：专业版及以上在「API 设置 → 管理密钥权限」中可关闭某密钥的转人工，或指定仅使用某条企微「人工客服转接」配置（多配置时避免串线）。基础版（Lite）无企业微信菜单，亦不展示该项，开放 API 侧沿用默认转人工策略（若企业未配企微则不会命中）。

非流式输出 (stream: false)

完整等待模型生成后一次性返回结果，适用于后台任务、批处理等场景。

请求示例（首次对话）

curl -X POST https://agent.likelic.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "你们的退货政策是什么？",
    "template_id": "Abc123Def456GhiJkl789Mnop"
  }'

请求示例（多轮对话，续接会话）

curl -X POST https://agent.likelic.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "那退款需要多长时间到账？",
    "template_id": "Abc123Def456GhiJkl789Mnop",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

响应示例

{
  "success": true,
  "data": {
    "answer": "根据我们的退货政策，您可以在收到商品后 7 天内申请无理由退货...",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sources": [
      {
        "question": "退货政策有什么规定？",
        "score": 0.92
      }
    ],
    "model": "qwen-plus",
    "tokensUsed": 486,
    "responseTime": 1523
  }
}

响应字段说明

流式输出 (stream: true)

以 SSE (Server-Sent Events) 格式实时推送生成内容，适用于前端实时展示打字效果等交互场景。

请求示例（流式 + 首次会话，需传入 session_id 以记录连续对话）

curl -X POST https://agent.likelic.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "如何申请退款？",
    "template_id": "Abc123Def456GhiJkl789Mnop",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "stream": true
  }'

流式响应格式

响应 Content-Type 为 text/event-stream，数据以 SSE 格式逐行推送：

data: {"content":"根据"}

data: {"content":"我们"}

data: {"content":"的退货"}

data: {"content":"政策，"}

data: {"content":"..."}

data: [DONE]

JavaScript 流式调用示例

// 若需记录连续会话，流式首次请求需传入 session_id（流式响应不包含 session_id）
const sessionId = crypto.randomUUID();
const response = await fetch('https://agent.likelic.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Customer-Code': 'your_customer_code',
    'X-API-Key': 'sk-your-api-key-here'
  },
  body: JSON.stringify({
    question: '如何申请退款？',
    template_id: 'Abc123Def456GhiJkl789Mnop',
    session_id: sessionId,
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let result = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ') && line !== 'data: [DONE]') {
      const json = JSON.parse(line.slice(6));
      result += json.content;
      console.log(json.content); // 实时输出
    }
  }
}

Python 调用示例

import requests
import json

url = "https://agent.likelic.com/api/v1/chat"
headers = {
    "Content-Type": "application/json",
    "X-Customer-Code": "your_customer_code",
    "X-API-Key": "sk-your-api-key-here"
}

# 非流式调用（首次对话，不传 session_id）
resp = requests.post(url, headers=headers, json={
    "question": "你们的退货政策是什么？",
    "template_id": "Abc123Def456GhiJkl789Mnop"
})
data = resp.json()["data"]
session_id = data["session_id"]  # 保存用于后续多轮对话
print(data["answer"])

# 多轮对话（传入首次返回的 session_id）
resp = requests.post(url, headers=headers, json={
    "question": "那退款需要多长时间到账？",
    "template_id": "Abc123Def456GhiJkl789Mnop",
    "session_id": session_id
})
print(resp.json()["data"]["answer"])

# 流式调用（若需记录连续会话，首次请求需传入 session_id，因流式响应不包含 session_id）
import uuid
stream_session_id = str(uuid.uuid4())
resp = requests.post(url, headers=headers, json={
    "question": "还有其他注意事项吗？",
    "template_id": "Abc123Def456GhiJkl789Mnop",
    "session_id": stream_session_id,
    "stream": True
}, stream=True)

for line in resp.iter_lines():
    if line:
        decoded = line.decode("utf-8")
        if decoded.startswith("data: ") and decoded != "data: [DONE]":
            data = json.loads(decoded[6:])
            print(data["content"], end="", flush=True)

人工客服回复轮询 HUMAN

GET /api/v1/human-replies

在 human_mode 为 true 且拿到与 /chat 相同的 session_id 后，可用本接口轮询企微群内回复。鉴权与 Chat 一致：X-Customer-Code、X-API-Key。human_mode 的触发方式见 AI 会话接口「关键词转人工（企业微信）」。

查询参数

响应 data.messages[]

请求示例

curl -G "https://agent.likelic.com/api/v1/human-replies" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  --data-urlencode "session_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --data-urlencode "since_id=0"

知识库写入接口 KB

POST /api/v1/knowledge/entries

从外部系统向本企业知识库新增一条问答对，鉴权与 Chat 相同（X-Customer-Code + X-API-Key）。校验通过后先写入 MySQL并立即返回成功；向量嵌入与 Qdrant 同步在后台异步执行（与控制台 Excel 批量导入的第二阶段一致），稍后在智能对话中即可检索到该条。

请求参数 (JSON Body)

本接口请求体上限 512 KB（大于通用 v1 的 100 KB）。

成功响应示例

{
  "success": true,
  "data": {
    "id": 12345,
    "category": "产品说明",
    "created_by": "crm_sync",
    "updated_by": null,
    "vector_sync": "queued",
    "message": "Entry saved to database. Vector embedding sync runs asynchronously; ..."
  }
}

配额不足示例（403）

{
  "success": false,
  "message": "Knowledge base entry limit reached for your plan (...)",
  "data": { "limit": 10000, "current": 10000, "remaining": 0 }
}

分类名对不上示例（400）

category 在分类目录中不存在、或该分类已停用时返回：

{
  "success": false,
  "message": "category \"未知分类\" does not exist as an enabled category in this customer's category catalog. Use one of data.existing_categories, or create the category in the console first.",
  "data": {
    "existing_categories": ["默认", "产品说明"]
  }
}

请求示例

curl -X POST https://agent.likelic.com/api/v1/knowledge/entries \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "如何重置密码？",
    "answer": "请在登录页点击「忘记密码」并按邮件指引操作。",
    "category": "账户与安全",
    "keywords": "password,reset,login",
    "answer_image": "https://example.com/help/screenshot.png"
  }'

更新单条知识（PUT）

PUT /api/v1/knowledge/entries/:id

使用创建接口返回的 data.id 作为路径参数 :id，更新同一条问答。请求体字段与 POST 相同，但 created_by 会被忽略（创建人不可改，响应回库中原值）；请用可选字段 updated_by（最大 100 字符）作为本次修改人标识。若不传 answer_image，则保留该条原有配图。

更新成功响应示例

{
  "success": true,
  "data": {
    "id": 12345,
    "category": "产品说明",
    "created_by": "crm_sync",
    "updated_by": "operator_a",
    "vector_sync": "queued",
    "message": "Entry updated. Vector embedding sync runs asynchronously; ..."
  }
}

curl -X PUT https://agent.likelic.com/api/v1/knowledge/entries/12345 \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "如何重置密码？",
    "answer": "请在登录页点击「忘记密码」并按邮件指引操作。",
    "category": "账户与安全",
    "keywords": "password,reset",
    "updated_by": "operator_a"
  }'

合作客商写入 WEWORK PARTNER

POST /api/v1/wework/partner-companies/import

从外部系统批量写入合作客商主数据，鉴权与 Chat 相同（X-Customer-Code + X-API-Key）。按 (租户, company_code) upsert：company_code 已存在则合并更新，不存在则新增。行为与控制台「导入合作公司」Excel 导入完全一致。

请求参数 (JSON Body)

顶层字段 rows 为数组，非空且不超过 5000 行；每行字段如下：

行级校验

缺少 company_code 或 company_name、或 company_status 非法的行会被跳过并计入 data.skipped，跳过原因逐条列在 data.errors（不影响其余有效行写入）。

请求示例

curl -X POST https://agent.likelic.com/api/v1/wework/partner-companies/import \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "rows": [
      {
        "company_code": "C1001",
        "company_name": "示例科技有限公司",
        "company_short_name": "示例科技",
        "sales_name": "张三",
        "tracker_name": "李四",
        "company_status": "已合作"
      },
      {
        "company_code": "C1002",
        "company_name": "另一家公司",
        "company_status": "trial"
      }
    ]
  }'

成功响应示例

{
  "success": true,
  "data": {
    "inserted": 1,
    "updated": 1,
    "skipped": 0,
    "errors": []
  }
}

含跳过行的响应示例

{
  "success": true,
  "data": {
    "inserted": 2,
    "updated": 0,
    "skipped": 1,
    "errors": ["第 3 行：缺少公司代码"]
  }
}

错误示例

// 未启用 wework_partner，或调用方 Key 未获授权 → 403
{ "success": false, "message": "开放 API「合作客商写入」未在系统设置中启用" }
{ "success": false, "message": "当前 API Key 未被授权调用「合作客商写入」接口" }

// rows 缺失/非数组，或超过 5000 行 → 400
{ "success": false, "message": "缺少 rows 数组" }
{ "success": false, "message": "单次最多导入 5000 行" }

服务绩效议题同步 WEWORK QA

GET /api/v1/wework/qa/issues

供外部系统（如部门管理系统）轮询拉取已评分的绩效议题，写入自有业务库。鉴权与 Chat / 知识库相同（X-Customer-Code + X-API-Key），无需 IP 白名单。

查询参数（列表）

列表按 sync_at ASC, id ASC 排序，便于增量游标推进。响应 meta 含 page、limit、total、retention_from（生效保留起始日）；传入 sync_since 时另回显 meta.sync_since。

列表响应 data[] 字段

列表响应示例

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "channel": "wework",
      "company_name": "示例科技有限公司",
      "company_status": "已合作",
      "summary": "客户反馈产品无法登录",
      "start_time": "2026-06-24T10:30:00",
      "customer_name": "张三",
      "status": "resolved",
      "score_total": 85,
      "assess_status": "success",
      "primary_staff_name": "李四",
      "staffs": [
        { "name": "李四", "effective_reply_count": 3 },
        { "name": "王五", "effective_reply_count": 1 }
      ],
      "created_at": "2026-06-24T10:35:00",
      "sync_at": "2026-06-24T10:40:00"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 128,
    "retention_from": "2026-05-25",
    "sync_since": "2026-06-24T10:00:00"
  }
}

推荐同步流程

1. 首次全量：不传 sync_since，按 page 分页直至 data 为空；每条以 id upsert。
2. 增量轮询（建议 5–15 分钟）：sync_since = 上次 max(sync_at) - 1 分钟（重叠防漏）；同一 id 再次出现则 UPDATE。
3. 停服恢复：沿用旧 sync_since 即可补回期间变更。
4. 多页：同一 sync_since 下若 total > limit，继续 page=2,3,... 直至拉完本批。

请求示例（增量拉取）

curl -G "https://agent.likelic.com/api/v1/wework/qa/issues" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  --data-urlencode "sync_since=2026-06-24T10:00:00" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100"

单条详情 GET /api/v1/wework/qa/issues/:id

GET /api/v1/wework/qa/issues/:id

返回字段与列表项相同，用于按 ID 补拉或校验。路径参数 :id 为议题 ID。

curl "https://agent.likelic.com/api/v1/wework/qa/issues/12345" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here"

成功返回 { "success": true, "data": { ... } }；不存在、未评分或超出保留期返回 404。

推送通知 OUTBOUND

推送通知让你的业务系统（ERP、CRM、计费系统等）通过开放 API，经企微机器人或 QQ 机器人向客户所在的企微群 / QQ 群发送通知，例如「贵司服务将于 30 天后到期」。业务系统只管提交，平台负责找到目标群、按时段排队、控制发送节奏，并提供逐群回执。本能力共四个接口：

适用场景

• 合同 / 服务到期前的续费提醒（如到期前 30 / 15 / 7 / 1 天各提醒一次）。
• 账单、发货、单证等业务状态变化时通知客户群。
• 需要在消息里 @ 对接人（如「如需续费请联系@张三 」）。

只发群，不发私聊；支持纯文本，以及最多 3 个附件（图片、文件、链接卡片）；一次请求提交一条通知，不支持批量或修改；尚未发出的部分可以撤回。

启用方式

1. 准备 API 密钥：在控制台「外部拓展 → API 设置」创建一个 sk- 开头的密钥，建议单独给推送通知使用。密钥只能放在你自己的后端，切勿写进前端代码。
2. 授权 Key：在「系统设置 → 开放 API 权限」中打开「推送通知」，并勾选允许调用的 API Key，保存。
3. 设置允许推送时段（可选）：在「系统设置 → 允许推送时段」中配置（北京时间）。默认 09:00–11:00 与 14:00–17:00 两段；清空全部时段表示不限时段、随时可发。
4. 绑定群与公司（按公司发送时需要）：在「合作管理 → 群管理」给客户群填上公司代码（可先导入合作公司再自动匹配）。只按群 ID 发送时可跳过这一步。
5. QQ 群需群主开通主动推送：群主在群内打开「机器人主动在群聊内发言」，否则发往该群的通知会被跳过。

之后若在系统设置里关闭「推送通知」，已受理但还没发出的通知也会一并停止发送（回执中落 failed，原因 scope_disabled），重新开启后不会自动恢复，需要业务系统重新下发。

通用约定

接口一：查询群清单 GET /api/v1/rooms

GET /api/v1/rooms

拉取本企业全部可作为通知目标的企微群与 QQ 群。常用于：① 在自己系统里做「客户 ↔ 群」绑定（用于按群 ID 发送）；② 核对哪些群还没绑公司、哪些群当前推不出去。

查询参数（均可选）

取值非法时返回 400 validation_error，不会静默忽略。结果固定按 channel → room_name → room_id 升序排列，翻页不会漏项或重复。没有任何群时返回 200、data 为空数组、meta.total 为 0。

请求示例

curl -G "https://agent.likelic.com/api/v1/rooms" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  --data-urlencode "company_code=ACME01" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

响应示例

{
  "success": true,
  "data": [
    {
      "channel": "wework",
      "instance_id": 3,
      "instance_name": "售后企微机器人",
      "room_id": "10696049xxxxxxxxx",
      "room_name": "艾克米物流售后群",
      "member_count": 12,
      "company_code": "ACME01",
      "company_name": "艾克米物流",
      "company_match_status": "auto",
      "push_state": "ready",
      "push_blocked_reason": null
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1 }
}

响应 data[] 字段

企微群与 QQ 群字段完全一致，只靠 channel 区分；没有值的字段返回 null，不会省略。

可推送状态 push_state

push_state 与是否绑定公司无关：未绑公司但可推送的群仍是 ready，可以按群 ID 直接发送。已删除的机器人实例下的群不会出现在清单里。

接口二：下发通知 POST /api/v1/notifications

POST /api/v1/notifications

提交一条通知。平台当场解析目标群、生成逐群投递单并返回 202；实际发送由平台按时段与节奏在后台完成，本接口不返回发送结果，请用接口三查询回执。

请求参数 (JSON Body)

target 的四种形态

• 同时给了两种形态，或一种都没给 → 400 validation_error。
• 按公司全称匹配到多家同名公司时不会自动挑选，返回 409 company_name_ambiguous 并在 data.candidates 列出每家的 company_code 与 company_name，请改用公司代码重发。
• 同一个群被多个机器人收录时只发一次：按公司发送时，平台按群去重，同一个企微群（或 QQ 群）即使被本企业多个机器人实例收录，也只生成一条投递单，由其中推送状态最好的实例发送。

附件（attachments）

一条通知最多带 3 个附件，写在请求体的 attachments 数组里；带附件时 text 可省略（无正文也无附件则返回 400 validation_error，field 为 text）。每项按 type 取下列字段：

• image / file 的 url 与 base64 不能同时给、也不能都不给，否则 400 validation_error（field 形如 attachments[1].url）。
• 平台在受理时把图片与文件转存到自己的存储再发送；url 须能被公网访问，转存时的抓取最多等待 30 秒。
• 图片支持 jpg / jpeg / png / gif / webp / bmp，单个不超过 10MB；文件支持 pdf / doc / docx / xls / xlsx / ppt / pptx / txt / csv / zip / rar，单个不超过 20MB。
• 类型按文件实际内容判定，改扩展名无效；可执行文件（Windows / Linux / macOS 可执行程序、带解释器声明的脚本）一律拒绝。

附件被拒绝时返回 400 attachment_rejected，并带 index（第几个附件，从 0 计）与 reason；被拒绝的请求不占用 biz_msg_id，修正后可用同一个键重新提交。

附件在两个渠道里的呈现

• 企微群：正文在前，然后逐条发出原生的图片、文件和链接卡片。
• QQ 群：正文与全部附件合成一条消息——图片与文件写成下载链接，链接卡片写成「标题：链接」；下载得到的文件名为你给的 file_name。
• QQ 合成长度校验：目标含 QQ 群时，平台按合成后的纯文本计算长度，超过 2000 字受理时即返回 400 qq_message_too_long（带实际长度 length 与上限 limit），不截断正文、不丢附件，也不占用 biz_msg_id；目标只含企微群时不做此校验。
• 部分送达（例如企微里正文已发出、后面的附件失败）按失败处理，回执里 parts_delivered / parts_total 记录送达进度；重投或续发只补发未送达的部分。

带附件的完整请求示例

curl -X POST https://agent.likelic.com/api/v1/notifications \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "biz_msg_id": "renew-ACME01-2026-10-24-d7",
    "target": { "company_code": "ACME01" },
    "text": "贵司服务将于 7 天后到期，续费资料见附件。",
    "attachments": [
      { "type": "file", "url": "https://example.com/quote.pdf", "file_name": "续费报价单.pdf" },
      { "type": "link", "title": "在线续费", "url": "https://example.com/renew" }
    ]
  }'

会话串定位与开头 @（target.conversation）

除按公司、按群外，还可以用会话串直接指定群，并在消息开头 @ 成员：

• 企微群：R:{群ID}@{成员ID}@{成员ID}
• QQ 群：{group_openid}@{成员ID}（不带 R: 前缀）

示例（均为占位 ID，请换成你自己的）：{ "conversation": "R:1078xxxxxxxxxxxx@1688xxxxxxxxxxxx" }。规则：

• 平台按格式标记判定渠道（有 R: 为企微，无前缀为 QQ）；可以另给 channel，但与格式矛盾时报错。
• 成员最多 20 个；成员之间不能有空段、重复或空白；总长不超过 512。非法写法（如 R:1078@a@@b、显式给了 channel: "qq" 却以 R: 开头、21 个成员）返回 400 validation_error，field 为 target.conversation。没写 channel 时，以 R: 开头一律按企微群处理：把 QQ 群串误加了 R: 会被当成企微群查找，通常返回 404 room_not_found，而不是 400。
• conversation 与公司代码、公司全称、按群三种定位方式互斥，同时出现返回 400。
• 该群在本企业所有未删除的实例下都没有收录时返回 404 room_not_found；实例由平台按群自动定位。

会话串里的成员会在正文那一条消息的开头依次被 @（企微在群内 @，QQ 按出站提及格式），之后紧接正文，只发一条。正文里的 @姓名 照常解析，同一成员只 @ 一次；成员 ID 不在群内时消息照常发送，并在回执 warnings 里记一条；QQ 实例关闭 markdown 时放弃提及。带附件时 @ 只附在正文那一条上，没有正文时开头只含 @。

请求体大小与并发限制

• 下发接口的请求体上限为 85MB（带 base64 附件时留意体积），超限返回 413 payload_too_large。
• 同一租户同时处理的大请求（超过 2MB）最多 4 个，超出返回 429 too_many_large_requests，请稍后重试。
• 同一个 biz_msg_id 并发提交时，后到的请求可能返回 409 notification_in_progress，稍等片刻用接口三查询回执即可。

以上 400 / 413 / 429 都表示整条不受理，不生成投递单，也不占用 biz_msg_id。

请求示例

curl -X POST https://agent.likelic.com/api/v1/notifications \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "biz_msg_id": "renew-ACME01-2026-10-24-d30",
    "target": { "company_code": "ACME01" },
    "text": "您好，贵司的 XXX 服务将于 2026 年 10 月 24 日到期，您请看是否安排续费，如需续费请联系@张三 ，谢谢您的支持！"
  }'

首次受理响应示例（202）

{
  "success": true,
  "data": {
    "notification_id": 1024,
    "biz_msg_id": "renew-ACME01-2026-10-24-d30",
    "duplicate": false,
    "summary": { "total": 2, "queued": 1, "skipped": 1 },
    "deliveries": [
      {
        "delivery_id": 5001,
        "channel": "wework",
        "instance_id": 3,
        "room_id": "10696049xxxxxxxxx",
        "room_name": "艾克米物流售后群",
        "company_code": "ACME01",
        "company_name": "艾克米物流",
        "status": "pending",
        "skip_reason": null,
        "scheduled_at": "2026-09-28T09:37:00.000+08:00"
      },
      {
        "delivery_id": 5002,
        "channel": "qq",
        "instance_id": 12,
        "room_id": "C9F3A2xxxxxxxxxxxxxxxxxxxxxxxxxx",
        "room_name": "艾克米物流服务群",
        "company_code": "ACME01",
        "company_name": "艾克米物流",
        "status": "skipped",
        "skip_reason": "proactive_push_disabled",
        "scheduled_at": null
      }
    ]
  }
}

• summary 满足 queued + skipped = total；deliveries 固定按 delivery_id 升序。
• 受理时即可判定发不进去的群（bot_not_in_room、proactive_push_disabled）直接落 skipped，不会进入发送队列；实例离线不算跳过，照常排队。
• 全部目标群都被跳过时返回 409 all_targets_skipped，data.deliveries 逐条列出群与 skip_reason，本次不受理、不占用 biz_msg_id——群主开通或机器人重新进群、并在合作管理中完成检测后，可用同一个 biz_msg_id 重新提交。
• 任何 4xx 都表示整条不受理，一条投递单都不会生成，修正后重发即可。

推送时段与排期

• 受理时若当前时刻（北京时间）落在允许推送时段内，scheduled_at 即为当前时刻；若在时段外，则排到下一个时段内的随机时刻（按分钟），同一批通知的发送时刻会被自然打散，不会半夜打扰客户，也不会在同一时刻集中发出。
• urgent: true 时不受时段限制，scheduled_at 为受理时刻；但每日发送上限等保护照常生效——urgent 只放宽「什么时候发」，不放宽「能不能发」。
• 平台会在同一个机器人的相邻两条消息之间自动留出间隔，并与消息群发共用企微实例的每日发送上限。当天额度用完、或时段配置变更后已不在时段内时，投递单保持 pending，scheduled_at 顺延到之后的时段，不会因此失败。因此 scheduled_at 是计划时刻，可能随排队情况后移。

幂等与重复提交

• biz_msg_id 在本企业内唯一。重复提交相同的 biz_msg_id 返回 200、duplicate: true，并回吐首次生成的 notification_id 与投递单当前状态（字段同接口三的 deliveries），不会新建投递单，也不会用本次请求的其他字段覆盖首次内容。并发重复提交同样只会受理一次。summary 为首次受理时的快照（排队 / 跳过计数不随投递进展变化），不能用来判断是否已发出；实时状态以 deliveries[].status 或接口三 GET /api/v1/notifications/{biz_msg_id} 为准。
• biz_msg_id 比较时不区分大小写、忽略尾随空格：例如 Order-a1 与 order-A1 视为同一个键。请不要依赖大小写或尾随空格来区分不同的通知，否则后一条会被当作重复提交而不会发出。
• 建议用「业务对象 + 业务日期 + 提醒轮次」拼出稳定的键，例如 renew-ACME01-2026-10-24-d30；重试或跑批重复执行时沿用同一个键即可，客户不会收到两条相同提醒。

@ 提及的书写约定

正文里写 @姓名 可以在群里 @ 到对应的人（被 @ 的人会收到提醒），常用于「如需续费请联系@张三 」：

• @姓名 后必须加一个空格（或换行），如 请联系@张三 ，谢谢。平台取 @ 到下一个空白之间的整段文字作为姓名、并要求完全相等，所以 @张三，谢谢、@张三您好 这类连写不会被识别；群里同时有「张三」和「张三丰」时，@张三 只会 @ 到「张三」。
• @ 可以出现在正文任意位置。找不到这个人、或本群有多个同名的人时，平台不会乱 @，@姓名 按纯文本原样发出，消息照常送达，并在该投递单的 warnings 中说明。
• 优先匹配本企业员工（员工需在控制台「成员与权限」绑定企微 / QQ 身份），其次匹配群成员；被 @ 的人必须在该群内。
• 不支持 @所有人，不支持按手机号或工号 @ 人。

QQ 群的额外限制（渠道差异，不是故障）：

• QQ 只能 @ 在本群有发言记录的人。QQ 实例默认的「仅 @ 回复」模式下，机器人只收到 @ 它的消息，所以只有在本群 @ 过机器人的人才 @ 得到，命中率低；把实例改为「全量消息作上下文，仅 @ 回复」后命中率会明显提升。
• 客户看到的是对方的 QQ 群昵称，不是正文里写的姓名。
• 员工的 QQ 身份按机器人绑定，换一个 QQ 机器人须重新绑定。
• 链接后面紧跟文字时，平台会在链接末尾自动补一个空格，否则 QQ 会把后面的文字并入链接、点开是错误地址。这是正文「原样发出」的唯一例外。
• 行首缩进不会显示；带 ? & # 等参数的链接可能无法点击，但文字逐字正确、可以复制。

接口三：查询回执 GET /api/v1/notifications/{biz_msg_id}

GET /api/v1/notifications/{biz_msg_id}

用下发时的 biz_msg_id 查询这条通知发到了哪些群、是否发出（biz_msg_id 放进 URL 路径时请做 URL 编码）。biz_msg_id 在本企业下不存在时返回 404 notification_not_found。

请求示例

curl "https://agent.likelic.com/api/v1/notifications/renew-ACME01-2026-10-24-d30" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here"

响应示例

{
  "success": true,
  "data": {
    "notification_id": 1024,
    "biz_msg_id": "renew-ACME01-2026-10-24-d30",
    "target_kind": "company_code",
    "target_value": "ACME01",
    "text": "您好，贵司的 XXX 服务将于 2026 年 10 月 24 日到期，您请看是否安排续费，如需续费请联系@张三 ，谢谢您的支持！",
    "urgent": false,
    "accepted_at": "2026-09-27T20:15:03.000+08:00",
    "attachments": [],
    "cancelled_at": null,
    "cancel_source": null,
    "cancel_reason": null,
    "status": "sent",
    "summary": { "total": 2, "queued": 0, "sent": 1, "failed": 0, "skipped": 1, "cancelled": 0 },
    "deliveries": [
      {
        "delivery_id": 5001,
        "channel": "wework",
        "instance_id": 3,
        "instance_name": "售后企微机器人",
        "room_id": "10696049xxxxxxxxx",
        "room_name": "艾克米物流售后群",
        "company_code": "ACME01",
        "company_name": "艾克米物流",
        "status": "sent",
        "skip_reason": null,
        "scheduled_at": "2026-09-28T09:37:00.000+08:00",
        "sent_at": "2026-09-28T09:37:04.000+08:00",
        "attempts": 0,
        "parts_total": 1,
        "parts_delivered": 1,
        "last_error_code": null,
        "warnings": null,
        "retry_of_delivery_id": null,
        "source": "open_api"
      },
      {
        "delivery_id": 5002,
        "channel": "qq",
        "instance_id": 12,
        "instance_name": "QQ 服务机器人",
        "room_id": "C9F3A2xxxxxxxxxxxxxxxxxxxxxxxxxx",
        "room_name": "艾克米物流服务群",
        "company_code": "ACME01",
        "company_name": "艾克米物流",
        "status": "skipped",
        "skip_reason": "proactive_push_disabled",
        "scheduled_at": null,
        "sent_at": null,
        "attempts": 0,
        "parts_total": 1,
        "parts_delivered": 0,
        "last_error_code": null,
        "warnings": null,
        "retry_of_delivery_id": null,
        "source": "open_api"
      }
    ]
  }
}

响应 data 字段

deliveries[] 每项字段

群名、实例名、公司名记录的是发送当时的名称，之后改名不影响回执。pending 不区分排队原因（等时段、等间隔、当天额度已满、实例离线、发送中都是 pending），但 scheduled_at 会反映顺延后的时刻。

聚合状态与轮询

整条通知的 status 与 summary 以每个目标群的最终结果为单位统计：同一个群被控制台重投过时只看最后一次投递，console_probe 来源的投递单不参与统计。summary.total 等于目标群数（重投不增加），恒有 queued + sent + failed + skipped + cancelled = total。

指令头 status 按以下顺序判定：queued > 0 → pending；全部已发送 → sent；有群已发送 → partially_sent；有失败 → failed；有已撤回 → cancelled；其余 → failed。因此只有在没有任何群发送成功时，才会与 v11 的判定结果不同（撤回后为 cancelled）。

例如一条通知命中群 A、群 B，A 发送成功、B 失败：status 为 partially_sent，summary 为 { total: 2, queued: 0, sent: 1, failed: 1, skipped: 0, cancelled: 0 }；运营重投 B 且成功后，deliveries 共 3 条，status 变为 sent，summary 为 { total: 2, queued: 0, sent: 2, failed: 0, skipped: 0, cancelled: 0 }。

失败码（last_error_code）

投递单为 failed 时，last_error_code 必为以下 11 个值之一：

机器人实例临时掉线、平台限流等可恢复的情况不会直接判失败，投递单保持 pending 并自动延后重试。

跳过原因（skip_reason）

skipped 是终态，平台不会自动补发。阻塞解除后，可由运营在投递记录中重投，或业务系统用新的 biz_msg_id 重新下发。

在控制台查看与重投

运营可在控制台「合作管理 → 投递记录」按公司名、群名或 biz_msg_id 查看每个群的投递结果，并对失败或已跳过的记录手工重投：

• 重投新建一条投递单（source 为 console_retry，retry_of_delivery_id 指向原记录），原记录保留不变，会同时出现在回执的 deliveries 中；同一条记录只能重投一次。
• 重投按允许推送时段排队，不继承 urgent。
• 重投后整条通知的回执 status 会回到 pending，直至新投递单有结果；带附件的通知重投时只补发未送达的部分。
• 运营点某行的小眼睛可打开通知预览（正文、附件、各群投递与送达进度、撤回记录），并在预览里撤回整条通知；已撤回通知的失败行显示「不可重投」，重投会返回 409 notification_cancelled。
• 运营在群管理对 QQ 群做「实时检测」时发出的测试消息属于控制台检测（console_probe），不会出现在开放 API 的回执中。

接口四：撤回通知 POST /api/v1/notifications/{biz_msg_id}/cancel

POST /api/v1/notifications/{biz_msg_id}/cancel

撤回一条通知尚未发出的部分。只取消排队中的群，已发出的群无法撤回；撤回即整条作废，不可恢复——其中失败的群也不能再由控制台重投。biz_msg_id 放进 URL 路径时请做 URL 编码；本企业下不存在时返回 404 notification_not_found。

请求参数 (JSON Body)

请求示例

curl -X POST "https://agent.likelic.com/api/v1/notifications/renew-ACME01-2026-10-24-d7/cancel" \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{ "reason": "客户已续约，通知作废" }'

响应示例（200）

{
  "success": true,
  "data": {
    "biz_msg_id": "renew-ACME01-2026-10-24-d7",
    "status": "partially_sent",
    "cancelled_at": "2026-09-28T10:05:00.000+08:00",
    "cancelled_count": 1,
    "results": [
      { "delivery_id": 5001, "channel": "wework", "room_id": "10696049xxxxxxxxx", "room_name": "艾克米物流售后群", "outcome": "cancelled" },
      { "delivery_id": 5002, "channel": "qq", "room_id": "C9F3A2xxxxxxxxxxxxxxxxxxxxxxxxxx", "room_name": "艾克米物流服务群", "outcome": "sent" }
    ]
  }
}

• status 是撤回后按上文规则重新聚合的整条通知状态；cancelled_count 为本次实际撤回的群数。
• 幂等：对已撤回的通知再次撤回返回 200，cancelled_count 为 0 并带 message: "无可撤回项"，撤回时刻与原因保持第一次的记录。
• 部分送达的投递被撤回后保留已送达进度（parts_delivered 不变），状态为 cancelled。
• 撤回后用同一个 biz_msg_id 再次提交下发，只会返回原来的回执，不会重新发送；要重发请换一个新的 biz_msg_id。

错误码（推送通知）

以下情况发生在进入本能力之前，响应不带 code，与其他开放 API 一致：401（缺少鉴权 Header 或格式错误）、403 且无 code（Key 无效、已停用、已过期或与企业代码不匹配）、429（超过该 Key 的速率限制）、400 / 413（请求体不是合法 JSON 或超过大小限制；下发接口超过 85MB 时例外，返回带 code 的 payload_too_large）。

错误响应示例

// 按公司全称匹配到多家同名公司 → 409
{
  "success": false,
  "code": "company_name_ambiguous",
  "message": "...",
  "data": {
    "candidates": [
      { "company_code": "ACME01", "company_name": "艾克米物流" },
      { "company_code": "ACME02", "company_name": "艾克米物流" }
    ]
  }
}

错误码说明

推送通知接口的失败响应另带 code 字段，请按 HTTP 状态码 + code 联合判断；各 code 出现在哪个接口、投递失败码与跳过原因见 推送通知 · 错误码。

错误响应格式

{
  "success": false,
  "message": "具体错误描述"
}

频率限制

为保障服务稳定性，每个 API Key 拥有独立的频率限制配置。系统在认证通过后，根据该 Key 的设定进行限流：

限流规则

限流响应头

每次 API 请求的响应中都会包含以下 Headers，方便客户端感知当前额度：

最佳实践

安全建议

调用建议