Milky 协议

Waylay 支持 Milky 协议，提供 HTTP API 调用和 WebSocket/SSE/Webhook 事件推送。

启用

设置 MILKY_HTTP_PORT 环境变量：

environment:
  - MILKY_HTTP_PORT=8082

连接方式

HTTP API

POST http://host:8082/api/:action
Content-Type: application/json
Authorization: Bearer your_token

{ "group_id": "123456", "message": [...] }

响应格式：

{
  "status": "ok",
  "retcode": 0,
  "data": { ... }
}

SSE 事件流

GET http://host:8082/event
Authorization: Bearer your_token

服务端推送：

event: message_receive
data: {"event_type":"message_receive","time":1712640000,"self_id":"123456789","data":{...}}

WebSocket 事件流

ws://host:8082/event?access_token=your_token

收到的每条消息是一个 JSON 事件对象。

Webhook

配置 MILKY_WEBHOOK_URLS 环境变量，Waylay 会将事件 POST 到指定 URL：

environment:
  - MILKY_WEBHOOK_URLS=["http://your-server:8080/webhook"]

鉴权

设置 MILKY_TOKEN 后，所有请求需携带 Bearer Token：

Authorization: Bearer your_token

或通过 URL 参数：

?access_token=your_token

API 列表

系统

API	说明
get_login_info	获取登录信息
get_impl_info	获取实现信息
get_user_profile	获取用户资料

消息

API	参数	说明
send_private_message	user_id, message	发送私聊消息
send_group_message	group_id, message	发送群消息
recall_private_message	user_id, message_seq	撤回私聊消息
recall_group_message	group_id, message_seq	撤回群消息
get_message	message_seq	获取消息详情

好友

API	参数	说明
get_friend_list	—	获取好友列表
get_friend_info	user_id	获取好友信息
send_friend_nudge	user_id	好友戳一戳
accept_friend_request	request_id	接受好友请求
reject_friend_request	request_id	拒绝好友请求

群组

API	参数	说明
get_group_list	—	获取群列表
get_group_info	group_id	获取群信息
get_group_member_list	group_id	获取群成员列表
get_group_member_info	group_id, user_id	获取群成员信息
set_group_name	group_id, group_name	设置群名
set_group_member_card	group_id, user_id, card	设置群名片
set_group_member_admin	group_id, user_id, is_admin	设置管理员
set_group_member_mute	group_id, user_id, duration	禁言成员
set_group_whole_mute	group_id, is_mute	全体禁言
kick_group_member	group_id, user_id	踢出成员
quit_group	group_id	退群
send_group_nudge	group_id, user_id	群戳一戳
accept_group_join_request	request_id	接受加群请求
reject_group_join_request	request_id, reason	拒绝加群请求

事件列表

消息事件

message_receive

{
  "event_type": "message_receive",
  "time": 1712640000,
  "self_id": "123456789",
  "data": {
    "message_seq": 42,
    "message_scene": "group",
    "peer_id": "614990477",
    "sender": {
      "user_id": "123456",
      "nickname": "用户名",
      "card": "群名片"
    },
    "message": [
      { "type": "text", "data": { "text": "Hello" } }
    ],
    "time": 1712640000
  }
}

message_scene 取值：friend（好友）、group（群聊）、temp（临时会话）

message_recall

{
  "event_type": "message_recall",
  "data": {
    "message_seq": 42,
    "message_scene": "group",
    "peer_id": "614990477",
    "operator_id": "123456"
  }
}

好友事件

事件	说明
friend_request	好友请求
friend_nudge	好友戳一戳
friend_file_upload	好友文件上传

群组事件

事件	说明
group_join_request	加群请求
group_invited_join_request	被邀请入群
group_admin_change	管理员变动
group_member_increase	成员增加
group_member_decrease	成员减少
group_mute	成员禁言
group_nudge	群戳一戳
group_file_upload	群文件上传

消息段类型

接收

类型	字段	说明
text	text	纯文本
mention	user_id	@成员
mention_all	—	@全体成员
face	face_id	QQ 表情
reply	message_seq	回复消息
image	file_id, url, file_name, file_size	图片
record	file_id, url	语音
video	file_id, url	视频
file	file_id, name, size	文件
forward	forward_id	合并转发
market_face	emoji_id, emoji_package_id, summary, url	商城表情
light_app	app_name, json_data	JSON 卡片
xml	xml_data	XML 消息

发送

类型	字段	说明
text	text	纯文本
mention	user_id	@成员
mention_all	—	@全体成员
face	face_id	QQ 表情
reply	message_seq	回复消息
image	url 或 file_id	图片（URL/base64/本地路径）
record	url 或 file_id	语音
video	url 或 file_id	视频
light_app	json_data	JSON 卡片

示例

发送群消息

curl -X POST http://localhost:8082/api/send_group_message \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "614990477",
    "message": [
      { "type": "text", "data": { "text": "Hello from Milky!" } }
    ]
  }'

发送带图片和 @ 的群消息

curl -X POST http://localhost:8082/api/send_group_message \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "614990477",
    "message": [
      { "type": "mention", "data": { "user_id": "123456" } },
      { "type": "text", "data": { "text": " 看看这张图" } },
      { "type": "image", "data": { "url": "https://example.com/image.png" } }
    ]
  }'

获取群列表

curl -X POST http://localhost:8082/api/get_group_list