API 接口文档
目录
基础信息
- 基础地址：
http://qw.qingsongxuan.com - 鉴权参数：
secret，统一放在 query string 中。 - 请求格式：请求 body 使用
Content-Type: application/json。 - 时间格式：接口返回的时间为 ISO 8601 格式。
- 会话 ID：使用会话列表接口返回的
conversation_id；私聊通常以S:开头，群聊通常以R:开头。
消息通知
在后台配置 Webhook 地址并启用 API 服务后，机器人收到的会话消息会以 HTTP POST 请求通知到该地址。
- 通知范围：文本、图片、小程序、链接、名片、地理位置等消息。
- 鉴别字段：用
msgtype区分消息类型；不同类型携带对应对象。 - 安全建议：回调中的
secret可用于校验通知来源。
文本消息
{
"secret": "-",
"msgtype": "text",
"conversation_id": "S:16888xxx328682_7881302xx12998",
"sender": "78813xx98",
"text": {
"content": "你好"
}
}
图片消息
{
"secret": "-",
"msgtype": "image",
"conversation_id": "",
"sender": "",
"image": {
"cdn_type": "",
"cdn": ""
}
}
小程序消息
{
"secret": "-",
"msgtype": "miniprogram",
"conversation_id": "",
"sender": "",
"miniprogram": {
"appicon": "",
"appid": "",
"appname": "",
"page_path": "",
"title": ""
}
}
链接消息
{
"secret": "-",
"msgtype": "link",
"conversation_id": "",
"sender": "",
"link": {
"title": "",
"url": ""
}
}
地理位置消息
{
"secret": "-",
"msgtype": "location",
"conversation_id": "S:16888xxx328682_7881302xx12998",
"sender": "78813xx98",
"sender_name": "小邪",
"location": {
"title": "北京天安门广场",
"address": "北京市东城区东长安街",
"latitude": 39.903739928999997,
"longitude": 116.397827148,
"zoom": 15
}
}
消息发送
- 接口地址：POST
/api/send - 必填参数：
secret、conversation_id - 说明：消息内容放在 JSON body 中，
msgtype表示消息类型。
curl 'http://qw.qingsongxuan.com/api/send?secret=#{secret}&conversation_id=#{conversation_id}' \
-H 'Content-Type: application/json' \
-d '
{
"msgtype": "text",
"text": {
"content": "hello world"
}
}'
文本
{
"msgtype": "text",
"text": {
"content": "hello world"
}
}
链接卡片
{
"msgtype": "link",
"link": {
"title": "标题",
"url": "https://x.com",
"image_url": "https://x.com/logo.png",
"desc": "描述"
}
}
图片
{
"msgtype": "image",
"image": {
"url": "https://tuiguangdashi.com/template/eyou/pc/skin/images/logo.png"
}
}
名片
{
"msgtype": "contact",
"contact": {
"share_user_id": "7881300xxx093"
}
}
也兼容 msgtype: "card" 和顶层 share_user_id。
消息查询
查询指定会话已归档的双向消息，按消息时间倒序返回。只有开启会话消息存档后收到或发送的消息可被查询。
- 接口地址：GET
/api/messages - 必填参数：
secret、conversation_id - 可选参数：
page（默认1）、page_size（默认50，范围1–100）。 - 权限范围：
secret只能查询其绑定机器人的会话消息。
curl 'http://qw.qingsongxuan.com/api/messages?secret=#{secret}&conversation_id=#{conversation_id}&page=1&page_size=50'
成功响应：
{
"list": [
{
"id": "66c01234567890abcdef1234",
"conversation_id": "S:16888xxx328682_7881302xx12998",
"chat_type": "private",
"role": "user",
"type": 11001,
"sender": "78813xx98",
"receiver": "",
"content": "你好",
"message_at": "2026-07-13T08:30:00.000Z"
}
],
"pagination": {
"page": 1,
"page_size": 50,
"total": 1,
"total_pages": 1
}
}
字段说明：
role：user表示对方发送，assistant表示机器人发送。type：消息类型编号；可结合content展示文本、标题或描述。message_at：消息发生时间。
会话列表
先调用会话列表接口获取 conversation_id，再用于消息发送或消息查询。
获取用户会话
- 接口地址：GET
/api/users - 必填参数：
secret
curl 'http://qw.qingsongxuan.com/api/users?secret=#{secret}'
- 返回数据：包含用户名称和
conversation_id的列表。
获取群组会话
- 接口地址：GET
/api/groups - 必填参数：
secret
curl 'http://qw.qingsongxuan.com/api/groups?secret=#{secret}'
- 返回数据：包含群组名称和
conversation_id的列表。
Agent 技能调用
- 接口地址：POST
/api/skill - 鉴权参数：
secret（放在 query string） - 请求格式：
Content-Type: application/json - 说明：给 Codex、Hermes 这类 Agent 统一调用，
skill表示技能名，params表示参数。
curl 'http://qw.qingsongxuan.com/api/skill?secret=#{secret}' \
-H 'Content-Type: application/json' \
-d '
{
"skill": "message.sendText",
"params": {
"conversation_id": "S:bot_user",
"content": "hello world"
}
}'
支持技能
message.sendText
{
"skill": "message.sendText",
"params": {
"conversation_id": "S:bot_user",
"content": "hello world"
}
}
message.sendImage
{
"skill": "message.sendImage",
"params": {
"conversation_id": "R:123456",
"url": "https://example.com/demo.png"
}
}
message.sendLink
{
"skill": "message.sendLink",
"params": {
"conversation_id": "R:123456",
"title": "标题",
"url": "https://x.com",
"image_url": "https://x.com/logo.png",
"desc": "描述"
}
}
message.sendContact
{
"skill": "message.sendContact",
"params": {
"conversation_id": "S:168885xxxx82_78813022xxx998",
"share_user_id": "7881300xxx093"
}
}
contact.listUsers
{
"skill": "contact.listUsers",
"params": {}
}
contact.listGroups
{
"skill": "contact.listGroups",
"params": {}
}
返回格式
成功：
{
"status": "success",
"skill": "message.sendText",
"data": {}
}
失败：
{
"status": "error",
"skill": "message.sendText",
"error": "invalid_params",
"message": "conversation_id and content required"
}