灵当 AI 智能客服 开放接口说明

一、文档说明

本文档面向需要与灵当 AI 智能客服对接的第三方系统开发人员，说明对外开放的接口的调用方式。

二、接入准备

2.1 获取 API Key

由贵司管理员在系统中创建：

1. 进入「设置 → API接口」，点击创建 API Key，填写用途名称。
2. 密钥以 kb_ 开头，仅在创建成功时完整显示一次，请立即复制保存；关闭后无法再次查看。
3. 如创建入口不可用，说明当前授权计划未包含接口访问能力，请联系我们开通。

2.2 请求地址

所有接口的地址为「服务地址 + 接口路径」。本文档中统一以 {BASE} 表示贵司的服务地址。

2.3 鉴权方式

所有接口统一在请求头中携带 API Key：

2.4 安全须知（请务必阅读）

• ●只能在贵司服务端使用。切勿写入网页前端、移动端 App、小程序或任何最终用户可以获取到的代码与配置中。
• ●务必通过 HTTPS 调用；不要把密钥放在 URL 参数、日志、截图或工单中传递。
• ●建议为每个对接系统单独创建一把密钥，便于区分来源、按需单独吊销。
• ●密钥一旦疑似泄露，请立即在同一页面撤销并重新创建，撤销后旧密钥立刻失效。
• ●建议在网络层限制可发起调用的服务器来源，缩小暴露面。
• ●接口调用会计入贵司的用量统计，请避免无节制的轮询。

三、通用约定

项目	说明
编码	UTF-8，请求体与响应体均为 JSON
分页参数	page（页码，从 1 开始）、page_size（每页条数，默认 50，最大 200）
分页响应	返回 total 表示满足条件的总条数
日期格式	YYYY-MM-DD（如 2026-08-20）
时间格式	ISO 8601（如 2026-08-20T10:30:00+00:00）
部分更新	PATCH 接口只需传要修改的字段，未传字段保持原值

状态码说明

状态码	含义	处理建议
200	请求成功	—
201	创建成功	—
400	参数有误	按响应中的 detail 提示修正请求
401	鉴权失败	检查 API Key 是否正确、是否已被撤销
403	无权限	该密钥对应的账号无此数据权限，或授权计划不含该能力
404	资源不存在	检查单据 ID 是否正确
422	字段校验不通过	按响应中的字段名修正类型或必填项
429	调用过于频繁	降低频率后重试
500	服务端异常	稍后重试；持续出现请联系我们并提供请求时间

错误响应统一格式：

四、AI 对话接口

用于在第三方系统中直接调用智能客服问答能力。

4.1 获取可用机器人列表

发起对话前先取得机器人 ID。

响应示例：

4.2 发起对话（一次性返回）

等待完整回答后一次性返回，适合后台批处理、消息转发等场景。

请求字段：

字段	类型	必填	说明
query	string	是	用户提问内容
bot_id	string	否	指定机器人；不传则使用默认机器人
conversation_id	string	否	会话 ID。首次不传，服务端返回后在后续提问中回传即可保持上下文
image_urls	string[]	否	图片地址列表，取自 4.4 的上传接口，用于图片相关提问
accountid	string	否	外部系统的客户标识或客户名称，用于让回答结合该客户资料
video_urls	string[]	否	视频地址列表，取自 4.4 的上传接口；每次提问最多 2 个
file_urls	string[]	否	文档附件引用列表，取自 4.4 的上传接口；每次提问最多 3 份

请求示例：

响应字段：

字段	类型	说明
answer	string	回答正文
sources	array	引用到的知识来源，含文档名称与片段；未引用知识时为空数组
conversation_id	string	本次会话 ID，续问时回传
msg_id	number	本次回答的消息 ID

响应示例：

4.3 发起对话（流式返回）

按字返回，适合需要打字机效果的界面。请求字段与 4.2 完全一致。

响应为 Server-Sent Events（Content-Type: text/event-stream），每行以 data: 开头：

事件 type	说明
meta	开始事件，包含本次回答的基础信息
delta	增量正文片段，字段 content，需按到达顺序拼接
done	结束事件，包含 sources 与 msg_id

响应示例：

4.4 上传图片、视频与文档附件

提问时若要携带图片、视频或文档，需先调用下面的上传接口换取引用地址，再把返回值填进 4.2 / 4.3 的 image_urls、video_urls、file_urls 字段。上传接口一律使用 multipart/form-data，表单字段名固定为 file，鉴权方式与其它接口相同。

接口	支持格式	大小上限	成功返回
POST {BASE}/api/chat/upload-image	JPG、PNG、GIF、WEBP、BMP	20 MB	{"image_url": "…", "image_id": "…"}
POST {BASE}/api/chat/upload-video	MP4、MOV、AVI、WEBM、MKV	100 MB	{"video_url": "…", "video_id": "…"}
POST {BASE}/api/chat/upload-file	Word、Excel、PPT、PDF、TXT、Markdown	20 MB	{"file_url": "…"}

上传后把返回的地址填进提问请求，示例：

说明：

• ●图片与视频由模型读取画面内容作答；文档会抽取正文后作为本次提问的参考资料，扫描件等抽不出文字的文件不会报错，但模型只能看到文件名。
• ●视频需由模型从公网拉取，本地部署未配置公网访问域名时该接口会返回 400。
• ●上传的文件按贵司的存储配置保存，随对话记录一并留存。

五、服务记录单接口

服务记录单用于沉淀一次服务过程。支持外部系统写入与读取。

5.1 新增服务记录单

外部系统写入服务记录单的专用接口，字段精简。成功返回 201。

字段	类型	必填	说明
title	string	是	记录单标题
description	string	否	详细描述
ticket_type	string	否	类型，见枚举值；默认「咨询」
priority	string	否	优先级，见枚举值；默认「中」
customer_name	string	否	客户名称
contact_name	string	否	联系人姓名
contact_phone	string	否	联系人电话
contact_email	string	否	联系人邮箱
source_type	string	否	来源标识，便于区分是哪个系统写入的

请求示例：

5.2 查询服务记录单列表

分页返回。

参数	说明
status	按状态筛选，见枚举值
ticket_type	按类型筛选
priority	按优先级筛选
date_from / date_to	按服务日期区间筛选，格式 YYYY-MM-DD
link_status	linked（已关联客户）/ unlinked（未关联）
q	关键字搜索
page / page_size	分页参数

5.3 查询单条详情

返回单条记录单的完整字段。

在完整字段基础上，附带关联的服务工单与会话记录。

主要返回字段：

字段	说明
id	记录单 ID
record_no	记录单编号
title / description	标题与描述
ticket_type / priority / status	类型 / 优先级 / 状态
customer_name / contact_name / contact_phone / contact_email	客户与联系人信息
handler	处理人信息
service_date	服务日期
solution	解决方案
customer_rating / customer_feedback	客户评分与反馈
source_type	来源
created_at / updated_at	创建与更新时间

5.4 修改服务记录单

只传需要修改的字段。

可修改字段：title、description、ticket_type、priority、status、customer_name、contact_name、contact_phone、contact_email、solution、customer_rating、customer_feedback、service_date。

六、服务工单接口

服务工单用于跟踪需要派工处理的事项。接口结构与服务记录单一致。

6.1 新增服务工单

请求字段与 5.1 完全一致。成功返回 201。

6.2 查询服务工单列表

分页返回。

参数	说明
status	按状态筛选
ticket_type	按类型筛选
priority	按优先级筛选
q	关键字搜索
page / page_size	分页参数

6.3 查询工单详情

返回单条工单完整字段，含工单编号 ticket_no。

6.4 修改服务工单

只传需要修改的字段，可修改字段与 5.4 一致。

七、销售线索接口

销售线索用于承接客户留下的联系方式与购买意向。支持外部系统写入与读取。

7.1 新增销售线索

外部系统写入一条销售线索。成功返回 201。

请求字段：

字段	类型	必填	说明
lead_name	string	否	线索名称（主题）
name	string	否	联系人姓名
phone_number	string	否	手机号
phone_prefix	string	否	手机号国际区号，默认 +86
telephone	string	否	电话
email	string	否	邮箱
position	string	否	职位
company_name	string	否	公司名称
industry	string	否	行业
company_size	string	否	公司规模
region	string	否	地区
note	string	否	备注
status	string	否	状态，默认「未处理」，取值见枚举值一章

请求示例：

7.2 查询销售线索列表

分页返回。

参数	说明
page	页码，从 1 开始，默认 1
page_size	每页条数，默认 50，最大 200
q	关键字，模糊匹配手机号、联系人姓名、线索名称、公司名称、邮箱、来源名称
status	按状态筛选
source_type	按来源筛选

返回 leads 数组与 total 总数。

7.3 查询单条线索详情

返回单条线索的完整字段。线索不存在返回 404。

主要返回字段：

字段	说明
id	线索 ID
lead_name	线索名称
name / phone / email	联系人姓名、手机号（含区号）、邮箱
company_name / industry / company_size / region	公司信息
source_type / source_name	来源类型与来源名称
first_message	客户的第一句提问
status	状态
note	备注
visit_count	接触次数
owner	跟进人
crm_sync_status	同步到灵当CRM 的结果：为空=未同步，synced=已同步，failed=同步失败
created_at / updated_at / last_contact_at	创建、更新、最近接触时间

7.4 修改销售线索

只传需要修改的字段，未传的保持不变。

可修改字段：lead_name、name、phone_number、phone_prefix、telephone、email、position、company_name、industry、company_size、region、status、note。

status 传了枚举之外的值返回 422。修改不会再次推送灵当CRM。

八、客户管理接口

客户用于沉淀已建立合作关系的单位信息。支持外部系统写入与读取。

8.1 新增客户

外部系统写入一个客户。成功返回 201；同名客户已存在时不重复创建，返回既有客户，状态码 200。

请求字段：

字段	类型	必填	说明
name	string	是	客户名称。为空返回 400
customer_type	string	否	客户类型，默认「企业」
customer_level	string	否	客户等级
status	string	否	客户状态，默认「潜在」
industry	string	否	所属行业
company_size	string	否	公司规模
address	string	否	地址
website	string	否	网址
region	string	否	地区
customer_source	string	否	客户来源
customer_stage	string	否	客户阶段
follow_up_status	string	否	跟进状态
note	string	否	备注
contacts	array	否	联系人列表，每项含 name、phone、email、position、is_primary

请求示例：

8.2 查询客户列表

分页返回。

参数	说明
page	页码，从 1 开始，默认 1
page_size	每页条数，默认 50，最大 200
q	关键字，模糊匹配客户名称等
status	按客户状态筛选
customer_type	按客户类型筛选

返回 customers 数组与 total 总数。

8.3 查询客户详情

返回客户完整字段，含联系人列表。客户不存在返回 404。

主要返回字段：

字段	说明
id / name	客户 ID 与名称
customer_type / customer_level / status	类型、等级、状态
industry / company_size / address / website / region	工商与地址信息
customer_source / customer_stage / follow_up_status	来源、阶段、跟进状态
follow_up_count / first_contact_at / last_follow_up_at	跟进次数与时间
contacts	联系人列表
owner	跟进人
note	备注
crm_sync_status	同步到灵当CRM 的结果：为空=未同步，synced=已同步，failed=同步失败
created_at / updated_at	创建与更新时间

8.4 修改客户

只传需要修改的字段，未传的保持不变。修改不会再次推送灵当CRM。

九、枚举值

字段	可选值
ticket_type（类型）	维修、咨询、投诉、其他
priority（优先级）	高、中、低
status（状态）	待处理、处理中、解决、关闭
线索 status（状态）	未处理、跟进中、已转客户、无效
线索 source_type（来源）	kb_share 知识库访客、bot_chat 机器人对话、manual 手动添加
客户 customer_type（类型）	企业、个人
客户 customer_level（等级）	A、B、C
客户 status（状态）	潜在、成交、流失
客户 customer_stage（阶段）	潜在、商机、成交
客户 customer_source（来源）	线索、活动、推荐、手动
客户 follow_up_status（跟进）	跟进中、暂停

十、对接建议

• 先在测试环境用一把独立的 API Key 跑通全流程，再切到生产密钥。
• 创建类接口建议在贵司侧做幂等控制（例如以贵司单号做去重），避免网络重试造成重复单据。
• 轮询查询请控制在合理频率；数据量大时使用日期区间配合分页拉取。
• 对话接口的响应时间受问题复杂度影响，建议客户端超时设置不低于 60 秒，流式接口按事件到达处理。
• 如需新增字段或开放其他能力，请与我们联系，勿自行调用未在本文档中列出的接口——这些接口不承诺兼容性，可能随版本变化。