API接口说明

基础信息

基础地址：http://aipm123.com:3100

内容类型：application/json

Supabase 数据接口：https://<SUPABASE_URL>/rest/v1

认证：apikey 与 Authorization: Bearer（不要在前端页面中硬编码密钥）

端点一览

POST /send
向企业微信客服发送消息
参数
open_kfid: 必填，客服账号ID（未在请求体提供时使用服务配置）
external_userid/touser: 必填，客户ID
msgtype: 必填，消息类型（如 text）
content: 必填（当 msgtype=text），文本内容
调用示例
curl -X POST http://aipm123.com:3100/send \
  -H 'Content-Type: application/json' \
  -d '{
    "open_kfid": "wk...",
    "external_userid": "wm...",
    "msgtype": "text",
    "content": "hello"
  }'
GET /db/messages
从数据库查询标准化消息
参数
conversation_id: 可选，会话ID
direction: 可选，消息方向（in/out）
external_userid: 可选，客户ID
open_kfid: 可选，客服账号ID
agent_id: 可选，Agent唯一标识（按绑定范围筛选客户消息）
limit: 可选，返回条数（默认100）
调用示例
curl 'http://aipm123.com:3100/db/messages?agent_id=agent-001&direction=in&limit=50'
GET /db/conversations
从数据库查询会话列表
参数
external_userid: 可选，客户ID
open_kfid: 可选，客服账号ID
agent_id: 可选，Agent唯一标识（按绑定范围筛选客户会话）
limit: 可选，返回条数（默认100）
调用示例
curl 'http://aipm123.com:3100/db/conversations?agent_id=agent-001&limit=50'
GET /db/send_receipts
从数据库查询发送回执
参数
open_kfid: 可选，客服账号ID
external_userid: 可选，客户ID
limit: 可选，返回条数（默认100）
调用示例
curl 'http://aipm123.com:3100/db/send_receipts?open_kfid=wk...&external_userid=wm...&limit=50'
GET /callback
接收来自企业微信的验证请求并返回 echostr
参数
msg_signature/signature: 必填，签名
timestamp: 必填，时间戳
nonce: 必填，随机数
echostr: 必填，回声字符串
调用示例
curl 'http://aipm123.com:3100/callback?msg_signature=...×tamp=...&nonce=...&echostr=...'
POST /callback
接收来自企业微信的回调消息，记录事件并触发同步
参数
Content-Type: 必填，请求体类型（application/xml 或 application/json）
Encrypt: 可选，加密字段
调用示例
curl -X POST 'http://aipm123.com:3100/callback?msg_signature=...×tamp=...&nonce=...' \
  -H 'Content-Type: application/json' \
  -d '{
    "Encrypt": "..."
  }'
GET /db/sessions
查询会话分段（表：public.kf_sessions）
参数
conversation_id: 可选，会话ID
external_userid/open_kfid: 可选，用户与客服ID
order: 可选，start_time.asc|start_time.desc
limit: 可选，默认100
调用示例
curl 'http://aipm123.com:3100/db/sessions?conversation_id=wk...__wm...&order=start_time.desc&limit=50'

注意事项

  • 接口返回均为北京时间字符串；调用方避免重复换算时区
  • /db/* 为只读查询端点，写入由服务内部完成
  • 消息幂等基于唯一键 msgid；会话基于 conversation_id 合并
  • 拉取策略限制页数为 5 页以内，优先事件 token；失败回退使用 cursor
  • 不在日志或响应中输出内部密钥，避免泄露敏感信息
  • Supabase REST/RPC 需携带 apikey 与用户令牌；不要在前端代码中硬编码
  • 自动超时结束策略由数据库任务调度执行；可用 RPC 端点进行手动触发