API 接口文档

基础信息

• 基础地址：https://bot-admin.minapp.xin
• 鉴权参数：secret（放在 query string）
• 请求格式：Content-Type: application/json
• 兼容性：接口兼容企微官方机器人的 webhook

---

1. 发送消息

• 接口地址：POST /api/send
• 必填参数：secret、conversation_id
• 说明：消息内容放在 JSON body 中，msgtype 表示消息类型。

curl 'https://bot-admin.minapp.xin/api/send?secret=#{secret}&conversation_id=#{conversation_id}' \

  -H 'Content-Type: application/json' \

  -d '

{

  "msgtype": "text",

  "text": {

    "content": "hello world"

  }

}'

1.1 文本

{

  "msgtype": "text",

  "text": {

    "content": "hello world"

  }

}

1.2 链接卡片

{

  "msgtype": "link",

  "link": {

    "title": "标题",

    "url": "https://x.com",

    "image_url": "https://x.com/logo.png",

    "desc": "描述"

  }

}

1.3 图片

{

  "msgtype": "image",

  "image": {

    "url": "https://tuiguangdashi.com/template/eyou/pc/skin/images/logo.png"

  }

}

1.4 小程序

{

  "msgtype": "miniprogram",

  "miniprogram": {}

}

---

2. 获取会话列表

2.1 获取用户会话

• 接口地址：GET /api/users
• 必填参数：secret

https://bot-admin.minapp.xin/api/users?secret=#{secret}

• 返回数据：包含用户名称和 conversation_id 的列表。

2.2 获取群组会话

• 接口地址：GET /api/groups
• 必填参数：secret

https://bot-admin.minapp.xin/api/groups?secret=#{secret}

• 返回数据：包含群组名称和 conversation_id 的列表。

---

3. Agent 技能调用

• 接口地址：POST /api/skill
• 鉴权参数：secret（放在 query string）
• 请求格式：Content-Type: application/json
• 说明：给 Codex、Hermes 这类 Agent 统一调用，skill 表示技能名，params 表示参数。

curl 'https://bot-admin.minapp.xin/api/skill?secret=#{secret}' \

  -H 'Content-Type: application/json' \

  -d '

{

  "skill": "message.sendText",

  "params": {

    "conversation_id": "S:bot_user",

    "content": "hello world"

  }

}'

3.1 支持技能

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": "描述"

  }

}

contact.listUsers

{

  "skill": "contact.listUsers",

  "params": {}

}

contact.listGroups

{

  "skill": "contact.listGroups",

  "params": {}

}

3.2 返回格式

成功：

{

  "status": "success",

  "skill": "message.sendText",

  "data": {}

}

失败：

{

  "status": "error",

  "skill": "message.sendText",

  "error": "invalid_params",

  "message": "conversation_id and content required"

}

---

4. Webhook 回调

• 功能：后台填入 webhook 地址后，会收到所有会话信息通知。
• 支持类型：文本、图片、小程序、链接。
• 说明：每种消息类型字段不同，以 msgtype 区分。

4.1 文本消息

{

  "secret": "-",

  "msgtype": "text",

  "conversation_id": "",

  "sender": "",

  "text": {

    "content": ""

  }

}

4.2 图片消息

{

  "secret": "-",

  "msgtype": "image",

  "conversation_id": "",

  "sender": "",

  "image": {

    "cdn_type": "",

    "cdn": ""

  }

}

4.3 小程序消息

{

  "secret": "-",

  "msgtype": "miniprogram",

  "conversation_id": "",

  "sender": "",

  "miniprogram": {

    "appicon": "",

    "appid": "",

    "appname": "",

    "page_path": "",

    "title": ""

  }

}

4.4 链接消息

{

  "secret": "-",

  "msgtype": "link",

  "conversation_id": "",

  "sender": "",

  "link": {

    "title": "",

    "url": ""

  }

}