API 接口文档

基础信息

基础地址：https://kf.wanshi.xn--fiqs8s
鉴权参数：secret，统一放在 query string 中。后台会同时提供机器人级 secret 和会话级 send_secret、message_secret。
请求格式：请求 body 使用 Content-Type: application/json。
时间格式：接口返回的时间为 ISO 8601 格式。
会话 ID：使用会话列表接口返回的 conversation_id；私聊通常以 S: 开头，群聊通常以 R: 开头。
独立开关：后台可分别开启或关闭发送消息接口、消息查询接口，也可按会话单独开关；会话级接口默认关闭，机器人后台设置的运营者微信可在对应会话发送“开启接口”开启。

MCP

MCP 与现有 HTTP API 使用同一个开放 API secret 和权限配置。MCP 地址为：


POST https://kf.wanshi.xn--fiqs8s/mcp

请求使用 Bearer 形式传递现有 API secret：


curl 'https://kf.wanshi.xn--fiqs8s/mcp' \

  -H 'Authorization: Bearer #{secret}' \

  -H 'Accept: application/json, text/event-stream' \

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

  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

当前提供以下工具：

list_users
list_groups
get_messages
send_message

MCP 不新增账号、Token 或权限体系；发送和消息查询仍受现有 API 总开关及会话级开关控制。现有 /api/* 接口的路径、参数、响应和鉴权方式不变。

消息通知

在后台配置 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": "",

        "username": "",

        "page_path": "",

        "title": "",

        "file_id": "",

        "aes_key": "",

        "md5": "",

        "size": 0,

        "cdn_type": 2,

        "cdn": {

            "file_id": "",

            "aes_key": "",

            "md5": "",

            "size": 0

        }

    }

}

链接消息


{

    "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

    }

}

视频号消息


{

    "secret": "-",

    "msgtype": "vlog",

    "conversation_id": "S:16888xxx328682_7881302xx12998",

    "sender": "78813xx98",

    "sender_name": "小邪",

    "vlog": {

        "avatar": "https://wx.qlogo.cn/finderhead/example/0",

        "cover_url": "https://wxapp.tc.qq.com/example-cover",

        "thumb_url": "https://wxapp.tc.qq.com/example-thumb",

        "nickname": "视频号名称",

        "desc": "视频号描述",

        "url": "https://channels.weixin.qq.com/web/pages/feed?eid=example",

        "feed_type": 4,

        "extras": "视频号协议数据"

    }

}

消息发送

接口地址：POST /api/send
必填参数：secret、conversation_id
权限范围：支持机器人级 secret 和会话级 send_secret。推荐使用会话列表返回的 send_secret；它只能向对应 conversation_id 发送消息，且需要先开启该会话接口。
说明：消息内容放在 JSON body 中，msgtype 表示消息类型。


curl 'https://kf.wanshi.xn--fiqs8s/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"

    }

}

小程序

发送小程序卡片时，基础字段为 appid、appname、page_path、title；封面图建议直接复用消息查询接口返回的 miniprogram 对象。封面图参数支持顶层 file_id/aes_key/md5/size，也支持 cdn: { file_id, aes_key, md5, size }。


{

    "msgtype": "miniprogram",

    "miniprogram": {

        "appid": "wx123",

        "appname": "示例小程序",

        "username": "gh_xxx@app",

        "appicon": "https://example.com/icon.png",

        "page_path": "pages/index/index.html",

        "title": "小程序标题",

        "file_id": "306b...",

        "aes_key": "6C75...",

        "md5": "059b34e084cf19a38a92a677177863d2",

        "size": 11122,

        "cdn_type": 2,

        "cdn": {

            "file_id": "306b...",

            "aes_key": "6C75...",

            "md5": "059b34e084cf19a38a92a677177863d2",

            "size": 11122

        }

    }

}

名片


{

    "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 和会话级 message_secret。推荐使用会话列表返回的 message_secret；它只能查询对应 conversation_id 的消息，且需要先开启该会话接口。


curl 'https://kf.wanshi.xn--fiqs8s/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": "你好",

            "raw_data": {

                "content": "你好"

            },

            "msgtype": "text",

            "text": {

                "content": "你好"

            },

            "message_at": "2026-07-13T08:30:00.000Z"

        },

        {

            "id": "66c01234567890abcdef1235",

            "conversation_id": "S:16888xxx328682_7881302xx12998",

            "chat_type": "private",

            "role": "user",

            "type": 11066,

            "sender": "78813xx98",

            "receiver": "",

            "content": "小程序标题",

            "raw_data": {

                "appid": "wx123",

                "appname": "示例小程序",

                "appicon": "https://example.com/icon.png",

                "username": "gh_xxx@app",

                "page_path": "pages/index/index.html",

                "title": "小程序标题",

                "cdn_type": 2,

                "cdn": {

                    "file_id": "306b...",

                    "aes_key": "6C75...",

                    "md5": "059b34e084cf19a38a92a677177863d2",

                    "size": 11122

                }

            },

            "msgtype": "miniprogram",

            "miniprogram": {

                "appid": "wx123",

                "appname": "示例小程序",

                "appicon": "https://example.com/icon.png",

                "username": "gh_xxx@app",

                "page_path": "pages/index/index.html",

                "title": "小程序标题",

                "file_id": "306b...",

                "aes_key": "6C75...",

                "md5": "059b34e084cf19a38a92a677177863d2",

                "size": 11122,

                "cdn_type": 2,

                "cdn": {

                    "file_id": "306b...",

                    "aes_key": "6C75...",

                    "md5": "059b34e084cf19a38a92a677177863d2",

                    "size": 11122

                }

            },

            "message_at": "2026-07-13T08:31:00.000Z"

        }

    ],

    "pagination": {

        "page": 1,

        "page_size": 50,

        "total": 1,

        "total_pages": 1

    }

}

字段说明：

role：user 表示对方发送，assistant 表示机器人发送。
type：消息类型编号；可结合 content 展示文本、标题或描述。
raw_data：归档时保存的原始消息数据。
msgtype 及同名对象：发送接口可复用的结构化消息内容，例如 text、image、link、miniprogram、contact。
message_at：消息发生时间。

会话列表

先调用会话列表接口获取 conversation_id，再用于消息发送或消息查询。

获取用户会话

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


curl 'https://kf.wanshi.xn--fiqs8s/api/users?secret=#{secret}'

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

获取群组会话

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


curl 'https://kf.wanshi.xn--fiqs8s/api/groups?secret=#{secret}'

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

API 文档