v1.0.0

星云API开发文档

星云API 官方开发文档 —— 覆盖登录、联系人、消息、群聊、朋友圈、文件等企业微信 API 接口的说明、请求参数、返回字段、代码示例与在线调试，帮助你快速接入。

REST APIJSONWebhook 多实例托管高并发支持企业级稳定

📱

多端云设备

支持 iPad 云端设备实例登录，iPad 设备支持三端同时在线。

三端在线

🌐

登录代理方案

提供网络代理（按省份定位）、自定义 SOCKS5 代理、本地代理（Aid 辅助工具）三种登录方案，保证设备网络环境稳定。

网络稳定

🔗

统一 API 规范

所有接口统一通过 POST 请求，以语义化路径区分操作。统一的请求/响应格式，降低对接成本。

统一规范

快速开始

创建实例

注册账号并创建企业微信实例

获取 API Key

在控制台获取你的专属 API Key

调用接口

使用 API Key 调用第一个接口

配置 Webhook

接收事件推送与回调通知

正式上线

完成集成，开始使用星云API

发送第一条消息（示例）

curlPythonJavaNode.jsGoPHPC#

curl -X POST 'https://api.xingyapi.com/api/message/sendText' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "instance_guid": "inst_xxxx",
    "conversationId": "会话ID（对方或群标识）",
    "content": "你好，欢迎了解星云。"
  }'

📊

300+

企业实例

服务各行各业客户

🧩

开放接口

覆盖企业微信核心能力

✅

365天

持续稳定运行

7×24 小时不间断服务

⚡

99.9%

服务可用性

毫秒级响应，稳定可靠

开始使用 › 请求规范与公共参数

请求规范与公共参数

在调用 API 前，建议先了解本页面中的统一请求规范。除特殊接口另有说明外，各接口均遵循这里定义的基础调用规则。

💡提示：各接口可能存在独立参数要求，具体调用参数请以对应接口页面说明为准。

01 · 基础请求信息

项目	当前项目实际值
Base URL	https://api.xingyapi.com
请求协议	HTTPS
请求方式	POST（当前全部接口均为 POST；具体以各接口页面标注为准）
Content-Type	application/json
字符编码	UTF-8

02 · 请求地址组成

接口完整地址 = Base URL + 接口路径（Path）。以「发送文本消息」为例：

POSThttps://api.xingyapi.com/api/message/sendText

03 · 请求 Header

参数	类型	说明
X-Nebula-Key必填	string	API 鉴权凭证，值为控制台「API Key」页的 Key（形如 `nb_live_xxxx`），无 Bearer 前缀。也可改用 Authorization: Bearer <API Key> 传递
Content-Type必填	string	固定为 `application/json`

04 · 公共参数

以下参数放在请求 Body（JSON）中，几乎所有业务接口都需要：

参数	类型	说明
instance_guid必填	string	星云实例标识（`inst_xxxx`），标识本次操作的账号 / 设备实例。除「创建设备」等个别接口外，各业务接口均需传入

ℹ其余参数（如 conversationId、content、roomId、userId、fileName、base64 等）为各接口的业务参数，仅在对应接口使用，请查看接口详情页。

05 · POST 请求规范

请求体统一使用 JSON，请求头带 Content-Type: application/json。
业务参数放在 Body；鉴权凭证放在 Header（X-Nebula-Key）。
字符串用双引号包裹；数字、布尔按 JSON 原生类型传递（如 true / false、数字不加引号）。
标记「必填」的字段不能缺省或为空。
Body 必须是合法的 JSON 对象；若请求体不是 JSON 对象将返回 40001。

06 · 请求示例

cURLPythonNode.js

curl -X POST 'https://api.xingyapi.com/api/message/sendText' \
  -H 'X-Nebula-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "instance_guid": "YOUR_INSTANCE_GUID",
    "conversationId": "会话ID（对方或群标识）",
    "content": "你好，欢迎使用星云 API！"
  }'

import requests

resp = requests.post(
    "https://api.xingyapi.com/api/message/sendText",
    headers={"X-Nebula-Key": "YOUR_API_KEY"},
    json={
        "instance_guid": "YOUR_INSTANCE_GUID",
        "conversationId": "会话ID",
        "content": "你好，欢迎使用星云 API！",
    },
)
print(resp.json())

const resp = await fetch("https://api.xingyapi.com/api/message/sendText", {
  method: "POST",
  headers: {
    "X-Nebula-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    instance_guid: "YOUR_INSTANCE_GUID",
    conversationId: "会话ID",
    content: "你好，欢迎使用星云 API！",
  }),
});
console.log(await resp.json());

07 · 统一返回格式

所有接口返回统一信封结构，业务数据在 data 中：

字段	类型	说明
ok	boolean	是否成功，`true` 为成功
code	number	业务状态码，`0` 表示成功，非 0 表示失败
message	string	结果说明；失败时为错误原因
request_id	string	请求追踪 ID（`nb_` 前缀），排查问题时可提供给客服
data	object	业务数据，结构以各接口响应说明为准

08 · 成功响应示例

JSON

{
  "ok": true,
  "code": 0,
  "message": "success",
  "request_id": "nb_xxxxxxxx",
  "data": {}
}

09 · 失败响应示例

JSON

{
  "ok": false,
  "code": 401,
  "message": "API Key 无效或缺失",
  "request_id": "nb_xxxxxxxx",
  "data": null
}

10 · 错误码

如果请求失败，可根据响应中的 code 和 message 排查问题，完整说明请查看「错误码」。

11 · 注意事项

参数类型需与文档保持一致（字符串、数字、布尔不要混用）。
必填参数不能为空。
API Key 请妥善保管，不要提交到公开代码仓库。
除个别接口（如创建设备）外，业务接口都需要传 instance_guid。
不同接口可能存在独立参数要求，具体以对应接口页面说明为准。

支持与维护 › 更新日志

更新日志

记录星云API平台的每一次功能更新与优化，帮助您及时了解最新动态。

全部版本 ▾

2026-09-01

v1.1.0

接口新增新增个人资料、标签、群发助手、群管理等 22 个接口

本次新增：个人资料（获取 / 更新个人信息、获取个人二维码）、标签管理（同步标签、操作标签 / 标签组）、群发助手（获取素材库列表、群发、发送待发送消息）、联系人（添加名片、添加群成员为好友、同意新客户、更新外部联系人信息、更新用户标签、设置同事备注、同步外部数据）、群管理（解散群、退出群聊、群置顶、禁止改群名、禁止群内互加、设置邀请确认、设置群备注）。完整清单与入参 / 出参见「接口详情」。

/api/personal/*/api/label/*/api/message/groupSend/api/contact/addCard/api/room/disband

2026-09-01

v1.1.0

接口调整接口全面对齐最新版本：部分接口迁移，入参 / 出参调整

全部接口已更新到最新版本，多处入参 / 出参字段有变化，请以「接口详情」为准重新对接。主要迁移：个人信息类迁移至 /api/personal/*（如「获取个人信息」→ /api/personal/getInfo）；部分群管理接口迁移至 /api/room/*。大整数 ID（会话 / 群 / 序号 / 成员等）在示例中统一以「字符串」形式给出，避免 JavaScript 解析时丢失精度，平台会自动转回数字。

获取个人信息 → /api/personal/getInfo群管理 → /api/room/*

2026-07-28

v1.0.0

正式上线星云企业微信开放平台正式上线

提供企业微信实例扫码托管、消息收发、通讯录、群聊、朋友圈、文件等语义化 API；支持在线测试、回调事件实时预览，以及体验版 / 企业 POC 权益体系。

基础地址：https://api.xingyapi.com鉴权：X-Nebula-Key

事件与 Webhook › 回调结构说明

回调结构说明

实例登录后收到的每条企业微信消息 / 事件，都会以下述结构推送。本页说明回调体的通用结构、content 的三种形态，以及各 msgType 的含义。（示例中的 URL、base64、密钥等均为脱敏样例。）

总体说明

· 回调体即为单条消息对象，不再有 code / data[] / msg 外层包装，也不再有 cmd 分类。
· 通过 msgType 区分消息类型；msgType 不同，content 的结构也不同。
· 消息按来源分两类，同一语义在两类来源下 msgType 与 content 结构可能不同：外部联系人（个微）微信侧联系人发来的消息 · 企微企业微信侧联系人发来的消息。

消息通用结构

JSON

{
  "id": 1000242,                        // 消息服务端 id
  "syncKey": 11195457,                  // 同步序号
  "roomType": false,                    // true=群消息  false=单聊消息
  "fromUserId": 7881303246306300,       // 发送者 id
  "toUserId": 1688854578848099,         // 接收者 id（单聊）
  "roomId": 10758922947847562,          // 群 id（群消息 / 系统通知，roomType=true 时出现）
  "msgType": 2,                         // 消息类型，见下方总览
  "timestamp": 1785228744,              // 消息时间戳（秒）
  "clientMsgId": "4982279615518431785", // 客户端消息唯一标识
  "content": { }                        // 消息体，结构随 msgType 变化
}

content 的三种形态

形态	出现场景	说明
对象 · 已解析字段	企微媒体消息、位置、链接、名片、小程序	直接给出可用字段
对象 · contentBase64	个微媒体消息、绝大多数系统 / 群通知	`{ "msgType": x, "contentBase64": "…" }`，原始数据 base64 需自行解析；无内容时为空串
数组	文本消息	`[{ "type": 0, "content": "…" }]`

contentBase64 解码类型对照

关键：contentBase64 解码后不是统一 JSON。按 msgType 分三种：
① UTF-8 文本——base64 解码即得文本（如群名 / 成员 ID 列表 / 灰字提示）；
② Protobuf 二进制——需按 protobuf 解析（媒体消息、部分系统通知），字段随类型不同；
③ 空串 ""——该消息无独立 payload，信息在其它字段（如退群人取 fromUserId）。
下表状态：✅ 已确认 · 🟡 高置信推断 · ⚠️ 待上游确认 · ⛔ 样例含截断（base64 带 …，后续字段无法恢复）。

msgType	消息	解码类型	状态	当前可解析内容
101	个微图片	Protobuf	⛔	可确认图片下载 URL
103	个微视频	Protobuf	⛔	可确认视频下载 URL
16	个微语音	Protobuf	⛔	field 1 为长字符串媒体数据
102	个微文件	Protobuf	⛔	文件名 + 下载 URL
26	红包	Protobuf	⛔	红包标识 + 祝福语
104	GIF / 动画表情	Protobuf	✅	完整样例：URL / MD5 / 尺寸 / 名称等
141	视频号	嵌套 Protobuf	⛔	嵌套消息 + 视频下载 URL
2357	外部好友申请（带信息）	已解析字段	✅	平台已解析为 `corpId / uin / corpName / customerName / source`（见下方示例，非 contentBase64）
1011	灰色操作提示	UTF-8	✅	base64 后直接 UTF-8
1037	邀请群成员	嵌套 Protobuf	✅	文本段 + 被邀请用户 ID
1001	群名修改	UTF-8	✅	解码即新群名
1002	新增群成员	UTF-8	✅	解码即成员 ID
1003	移除群成员	UTF-8	✅	解码即成员 ID
1005	自己退群	空	✅	退群人读取 `fromUserId`
1006	群新增	UTF-8	✅	「;」分隔成员 ID
2001	消息已读	Protobuf	✅	read_sync_key + unread_hint（见「更多已解出的结构」）
1043	群管理员变动	Protobuf	✅	actor_id / target_id / op_code（见「更多已解出的结构」）
1022	群管理设置变更	Protobuf	✅	带可读中文文案（如已启用"禁止改群名"）
2055	清空聊天记录	Protobuf	✅	wire：单个整数值，含义待确认
2132	外部好友申请通知	空	✅	当前样例无 payload
2131	联系人关系 / 资料变化	空	✅	当前样例无 payload
2180	联系人伴随通知	空	✅	当前样例无 payload
2188	内部联系人资料变化	空	✅	当前样例无 payload
2313	加入黑名单	空	✅	当前样例无 payload
2118	群信息变动伴随通知	空	✅	当前样例无 payload
2002	删除聊天	空	✅	当前样例无 payload

ⓘ标「空」的类型在当前样例中 contentBase64 为空串，尚不能断定是「该消息本身无 payload」还是「样例恰好无数据」；⛔ 的媒体类型 base64 在抓包中被截断，仅能恢复到下载 URL 等前置字段。完整字段以上游 .proto 为准。

消息类型总览 · 聊天消息

msgType	来源	说明	content 形态
2	个微	文本	数组
0	企微	文本	数组
101	个微	图片	contentBase64
14	企微	图片	已解析字段
103	个微	视频	contentBase64
23	企微	视频	已解析字段
102	个微	文件	contentBase64
15	企微	文件	已解析字段
16	个微	语音	contentBase64
104	个微 / 企微	GIF	contentBase64
29	企微	自定义表情 / 贴图	已解析字段
6	个微 / 企微	位置	已解析字段
13	个微 / 企微	链接	已解析字段
26	个微	红包	contentBase64
41	个微	名片	已解析字段
78	个微 / 企微	小程序	已解析字段
141	个微	视频号	contentBase64

消息类型总览 · 系统 / 通知消息

模块	msgType	说明
联系人相关	2132	外部好友申请通知
	2357	外部好友申请通知（带申请人信息）
	2131	好友申请通过 / 外部联系人信息（备注、电话、描述）更改通知
	2188	内部联系人信息（备注、电话、描述）更改通知
	2313	外部联系人加入黑名单通知
	2180	联系人相关伴随通知（与 2131 / 2313 同时出现，content 为空）
群相关	1001	群名变更通知
	1002	新增群成员通知
	1003	移除群成员通知
	1005	群成员自己退群通知
	1006	群新增通知
	1022	群管理设置变更通知（禁止改群名 / 禁止群内互加等）
	1037	邀请群成员通知
	1043	群管理员变动通知
	2118	群信息变动通知（几乎所有群操作都会伴随一条或多条）
会话消息	2055	清空聊天记录通知
	2002	删除聊天通知
	2001	消息已读通知
	1011	操作提示（聊天窗口灰色小字提示）

补充 · 其它已观测到的 msgType

msgType	类型	content 形态 / 说明
2063	撤回消息	contentBase64（含被撤回消息信息，需自行解析）
2104	联系人免打扰 / 置顶	contentBase64（多为空）
132	服务提示卡片	Protobuf · `field6`=提示文本（如「点击完善信息，提醒你最佳通勤路线」）
105	企业微信服务通知（如周报小结）	Protobuf · `field5`=标题、`field10`=统计文本、`field11`=重复统计段（key/value/unit）
38	登录操作通知（设备登录提醒）	Protobuf · `field1`=「登录操作通知」、`field2`=设备/时间文本（如「登录设备：iPad企业微信，登录时间：…」）。可用于感知账号被登录 / 换设备。
10	服务通知（邮件助手等功能推广）	Protobuf · `field1`=标题、`field3/5`=正文
573	联系客户统计通知	Protobuf · `field1`=标题（如「联系客户统计 8.7」）
80 31	待确认	contentBase64（首字段内容较大、样例被截断，需完整样例确认语义）
2201 2130	待确认（系统通知）	contentBase64（多为空）

ⓘ本表为线上真实回调中已观测到的 msgType。2063 / 2104 含义已确认；其余标「待确认」的仅确认会推送、结构为 contentBase64，确切语义待补充——文档仅依据抓包整理，不臆测。

消息示例 · 按类型分类

以下按消息类型归类（不再按来源/更新时间分节）；同一类型的个微与企微形态相邻对照。媒体凭证（fileId / aesKey / 下载票据 / 会议入会链接）仅示意，请勿落库。

一、聊天消息

文本 msgType = 2 数组

JSON

{
  "id": 1000242, "syncKey": 11195457, "roomType": false,
  "fromUserId": 7881303246306300, "toUserId": 1688854578848099,
  "msgType": 2, "timestamp": 1785228744, "clientMsgId": "4982279615518431785",
  "content": [ { "type": 0, "content": "这是一条测试消息" } ]
}

文本 msgType = 0 数组

JSON

{
  "id": 1000300, "syncKey": 11195477, "roomType": false,
  "fromUserId": 1688857970889847, "toUserId": 1688854578848099,
  "msgType": 0, "timestamp": 1785230839, "clientMsgId": "CAQQ9Ouh0wYY...",
  "content": [ { "type": 0, "content": "这是一条测试消息" } ]
}

图片 msgType = 101 contentBase64

JSON

{
  "id": 1000245, "syncKey": 11195458, "roomType": false,
  "fromUserId": 7881303246306300, "toUserId": 1688854578848099,
  "msgType": 101, "timestamp": 1785228942, "clientMsgId": "268542536807047311",
  "content": { "msgType": 101, "contentBase64": "BASE64_DATA…" }
}

视频(103)、文件(102)、语音(16)、GIF(104)、红包(26)、视频号(141) 均为同样的 { "msgType": x, "contentBase64": "…" } 形态，仅 msgType 不同，需自行解析 base64。

个微图片(101) contentBase64 解码后的 protobuf 结构 wire 逆向

field	类型	含义
3	string	原图下载 URL（微信媒体 CDN）
4	varint	文件大小（字节）
5 / 6	varint	宽 / 高
8 / 10 / 31	bytes(32)	md5 / 校验
25	string	AES 解密密钥（`v1_…` 前缀）
26 / 27 / 28 / 29	string / varint	第二变体：下载 URL / 大小 / 宽 / 高
32	message	嵌套 `{1:URL, 2:md5, 3:v1_密钥, 4:md5, 5:size}` + 宽 / 高

ⓘ下载：取 field 3（或 26）URL 下载密文，用 field 25 的 v1_ 密钥做 AES 解密。field number 由线上真实样例逆向，官方字段名以上游 .proto 为准。

图片 msgType = 14 已解析字段

JSON

{
  "id": 1000303, "msgType": 14, "roomType": false,
  "fromUserId": 1688857970889847, "toUserId": 1688854578848099,
  "timestamp": 1785231015, "clientMsgId": "CAQQpO2h0wYY...",
  "content": {
    "id": "FILE_ID…", "size": 1264883,
    "width": 2160, "height": 2880,
    "aesKey": "AES_KEY", "md5": "FILE_MD5",
    "midImageFileSize": 262144, "thumbFileSize": 8192,
    "thumbWidth": 300, "thumbHeight": 400, "thumbMd5": "THUMB_MD5"
  }
}

字段以线上真实回调为准：图片(14)用 id / size / md5（非 fileId/fileSize/fileMd5），并含 midImageFileSize / thumbFileSize / thumbWidth / thumbHeight / thumbMd5；高清原图另含 isHd。下载需用 id(fileId) + aesKey 调下载接口后按 AES 解密。

个微视频(103) contentBase64 解码后的 protobuf 结构 wire 逆向

field	类型	含义
1	string	视频下载 URL
3	varint	文件大小（字节）
4	varint	时长（秒）
5 / 6	varint	宽 / 高
7	string	封面 / 缩略图 URL
8 / 9 / 19	bytes(32)	md5 / 校验
16	string	AES 解密密钥（`v1_…`）
17	varint	封面大小

企微视频 msgType = 23 已解析字段

JSON

{
  "id": 1000488, "msgType": 23, "roomType": false,
  "fromUserId": 1688857970889847, "toUserId": 1688854578848099,
  "timestamp": 1785231100, "clientMsgId": "...",
  "content": {
    "id": "FILE_ID…", "size": 346390, "duration": 3,
    "width": 1280, "height": 720,
    "thumbUrl": "https://example.com/thumb/0",
    "aesKey": "AES_KEY", "md5": "FILE_MD5"
  }
}

企微视频(23)：id=fileId、duration=时长(秒)、width/height=尺寸、thumbUrl=封面缩略图；下载用 id + aesKey 调下载接口后 AES 解密。（字段以实际回调为准。）

个微文件(102) contentBase64 解码后的 protobuf 结构 wire 逆向

field	类型	含义
2	string	文件名（含扩展名）
3	string	文件下载 URL
4	varint	文件大小（字节）
8 / 10	bytes(32)	md5 / 校验
25	string	AES 解密密钥（`v1_…`）

企微文件 msgType = 15 已解析字段

JSON

{
  "id": 1000996, "msgType": 15, "roomType": false,
  "fromUserId": 1688857970889847, "toUserId": 1688854578848099,
  "timestamp": 1785923442, "clientMsgId": "...",
  "content": {
    "id": "FILE_ID…", "name": "示例文件.txt", "url": "",
    "size": 12216, "aesKey": "AES_KEY", "md5": "FILE_MD5"
  }
}

企微文件(15)：id=fileId、name=文件名(含扩展名)、size=字节、aesKey/md5=下载解密与校验；url 多为空，需用 id 调下载接口获取内容。

个微语音(16) 已解析字段

JSON

{
  "id": 1000258, "syncKey": 11195461, "roomType": false,
  "fromUserId": 7881303246306300, "toUserId": 1688854578848099,
  "msgType": 16, "timestamp": 1785229400, "clientMsgId": "...",
  "content": {
    "id": "VOICE_FILE_ID", "size": 4096,
    "voiceTime": 3, "aesKey": "AES_KEY", "md5": "FILE_MD5"
  }
}

注：实测个微语音(16) 为「已解析字段」形态（id / size / voiceTime(秒) / aesKey / md5），非 contentBase64；下载后用 aesKey 做 AES 解密。（总览表历史标注为 contentBase64，以此实测为准。）

自定义表情 / 贴图 msgType = 29 已解析字段

JSON

{
  "id": 1000480, "syncKey": 11195560, "roomType": true,
  "fromUserId": 1688854675899373, "roomId": 10758922947847562,
  "msgType": 29, "timestamp": 1785294100, "clientMsgId": "...",
  "content": {
    "url": "https://example.com/emoticon/0", "type": 1,
    "md5": "FILE_MD5", "width": 257, "height": 251,
    "name": "自定义表情", "flag": 103
  }
}

GIF / 动画表情：个微为 contentType=104（contentBase64，形态同图片，需解析）；企微自定义表情见上方 29。

位置 msgType = 6 已解析字段

JSON

{
  "id": 1000257, "msgType": 6, "roomType": false,
  "fromUserId": 7881303246306300, "toUserId": 1688854578848099,
  "timestamp": 1785229387, "clientMsgId": "7330448752447651776",
  "content": {
    "longitude": 117.187643, "latitude": 34.282147,
    "address": "江苏省徐州市鼓楼区中山北路226号", "title": "鼓楼广场C座"
  }
}

链接 msgType = 13 已解析字段

JSON

{
  "id": 1000272, "msgType": 13, "roomType": false,
  "fromUserId": 7881303246306300, "toUserId": 1688854578848099,
  "timestamp": 1785229772, "clientMsgId": "6825245120123380144",
  "content": {
    "url": "https://example.com/s?id=xxxx",
    "title": "文章标题"
    // 企微侧链接会多一个 "imageUrl": "https://example.com/img/0"
  }
}

视频号(141) contentBase64 解码后的 protobuf 结构 wire 逆向

field	类型	含义
127	message	视频号内容外层包装，内含以下字段：
127 → 2 / 3	string	视频下载 URL（视频号 CDN）
127 → 4	string	发布者头像 URL
127 → 5	string	视频号昵称
127 → 6	string	视频描述 / 标题
127 → 7	string	视频号主页链接
127 → 8	string	media key（大字段，导出 / 解密用）
127 → 10	string	objectId / feedId（视频号内容 id）
127 → 12 / 13	varint	宽 / 高

ⓘ以上媒体类 field number 均由线上真实样例逆向 protobuf wire 得到，官方 message / 字段名以上游 .proto 为准；141 的 field 127 内另有若干未逐一列出的辅助字段。

名片 msgType = 41 已解析字段

JSON

{
  "id": 1000266, "msgType": 41, "roomType": false,
  "fromUserId": 7881303246306300, "toUserId": 1688854578848099,
  "timestamp": 1785229668, "clientMsgId": "8361993591722517042",
  "content": {
    "cardUserId": 7881300228032100,
    "avatarUrl": "https://example.com/avatar/0",
    "name": "「brave」", "corpName": "微信"
  }
}

企微侧名片额外含 corpId（对方企业 id）、displayName（对外显示名）、cardToken（名片令牌，用于进一步拉取名片详情）；个微侧名片通常仅 cardUserId / avatarUrl / name / corpName。

小程序 msgType = 78 已解析字段

JSON

{
  "id": 1000263, "msgType": 78, "roomType": false,
  "fromUserId": 7881303246306300, "toUserId": 1688854578848099,
  "timestamp": 1785229583, "clientMsgId": "9080306373270132496",
  "content": {
    "miniProgramDetails": {
      "username": "gh_xxxxxxxx@app", "appId": "wxxxxxxxxxxxxxxxxx",
      "path": "?ChannelFrom=xxxx&...", "type": 2, "source": 452,
      "coverUrl": "https://example.com/cover/640",
      "title": "小程序标题", "appName": "小程序名称",
      "coverFileId": "COVER_FILE_ID…", "coverAesKey": "AES_KEY",
      "coverWidth": 500, "coverHeight": 400
      // 企微侧比个微侧多一个 "flag": 1
    }
  }
}

红包(26) contentBase64 解码后的 protobuf 结构 wire 逆向

field	类型	含义
1	bytes	红包标识
2	string	祝福语（如「恭喜发财，大吉大利」）
4	varint	发送者 userId
7	string	领取 token（base64）
9 / 10	string	资源 URL
11 / 12	string	提示文本（「来自X的红包，请进入手机版企业微信领取 / 查看」）

ⓘ企微红包无法通过 API 领取，回调仅告知红包事件；提示文本明确需在手机版企业微信内操作。

合并转发聊天记录 contentType = 4 protobuf

⚠️4 不是视频，是「合并转发的聊天记录」——当成视频处理会把整段对话（每条含发送人姓名 / 时间 / 正文或媒体元数据）整包入库。高密度 PII，不可整包落库。

字段	含义
`title`	转发记录标题（如「示例名称和示例名称的聊天记录」）
`count`	子消息条数
`items[]`	子消息列表，每条含 `send_time / content_type / kind`(text·image·…) / `sender_name` + `text` 或 `media{size, md5, thumb_size, *_present}`
`items_truncated`	是否因超限截断

群接龙 contentType = 213 protobuf

字段	含义
`text`	接龙正文（含标题与已接龙名单）
`solitaire.creator_id`	接龙创建人 id（不等于本条 fromUserId）
`solitaire.participant_count`	参与人数
`solitaire.participants[]`	参与人 `{ user_id, name, join_time }`

ⓘ三个坑：① 推的是全量快照非增量，每有人接龙就重发完整名单，业务侧直接覆盖、不要累加；② 参与人 name 可能为空，需按正文的「偏移-长度」区间切出补回（单位是 Unicode 码点、不是字节，按字节切会乱码）；③ creator_id ≠ fromUserId。

快速会议卡片 contentType = 579 protobuf

字段	含义
`meeting.title`	会议标题
`meeting.meeting_no`	会议号
`meeting.organizer_id`	发起人 id
`meeting.join_url_present`	入会链接是否存在（持链即可入会，属凭证，勿落库）

二、联系人相关通知

外部好友申请 msgType = 2132 / 2357 contentBase64

JSON

{
  "id": 1000355, "syncKey": 11195500, "roomType": true,
  "fromUserId": 10030, "roomId": 10030,
  "msgType": 2132, "timestamp": 1785233176, "clientMsgId": "...",
  "content": { "msgType": 2132, "contentBase64": "" }
}

2132 为无 payload 的申请通知（content 空）；2357 为带申请人信息的申请通知，实测已解析为结构化字段（非 contentBase64）：

外部好友申请（带申请人信息）msgType = 2357 已解析字段

JSON

{
  "id": 1000360, "syncKey": 11195502, "roomType": true,
  "fromUserId": 10030, "roomId": 10030,
  "msgType": 2357, "timestamp": 1785233200, "clientMsgId": "...",
  "content": {
    "corpId": 1970320000000000, "uin": 1688850000000000,
    "corpName": "示例企业", "customerName": "示例名称", "source": 1
  }
}
// corpId=申请人企业 id · uin=申请人 id · corpName=企业名 · customerName=申请人昵称 · source=来源渠道

好友申请通过 msgType = 2131

通过后会连推一组消息：① 2131 好友关系变动（content 空）② 一条 msgType=2 打招呼文本「我通过了你的联系人验证请求，现在我们可以开始聊天了」③ 1011 灰字提示 ④ 伴随 2131 / 2180（content 空）。外部联系人信息（备注 / 电话 / 描述）更改也复用 2131；内部联系人信息更改为 2188；加入黑名单为 2313（伴随 2131 / 2180）。

三、群相关通知

群名变更 msgType = 1001 contentBase64

JSON

{
  "id": 1000449, "syncKey": 11195534, "roomType": true,
  "fromUserId": 1688854578848099, "roomId": 10758922947847562,
  "msgType": 1001, "timestamp": 1785293964, "clientMsgId": "...",
  "content": { "msgType": 1001, "contentBase64": "5Li+5Liq5qCX5a2Q" }
  // contentBase64 解码即为新群名
}
// 几乎所有群操作都会伴随一条或多条 msgType=2118（群信息变动，content 空）

群成员 / 群操作 · content 解码对照

msgType	事件	contentBase64 解码后含义
1002	新增群成员	新增成员 id（先到 2118，再到 1002）
1003	移除群成员	被移除成员 id（伴随多条 2118）
1005	成员自己退群	content 空；退群人 = `fromUserId`（先到 2118，再到 1005）
1006	群新增	分号分隔的成员 id 列表，如 `7881303246306300;7881302241438345`（可能推送多次，伴随 2001 已读、多条 2118）
1037	邀请群成员	邀请信息；同时给被邀请人推一条 `msgType=13` 入群邀请链接
1022	群管理设置变更	禁止改群名 / 禁止互加等设置变更（伴随 2118）
1043	群管理员变动	变动信息（伴随 2118；样例中推送两次）
2055	清空聊天记录	—
2002	删除聊天	content 空（样例中推送两条）

ⓘ群解散在样例中仅回调两条 2118，未见独立的解散 msgType。文档仅依据抓包样例整理，未出现在样例中的类型不做臆测。

四、会话 / 信令通知

已读回执 2001 · 群角色变更 1043 · 撤回 2063 protobuf 字段

contentType	字段	含义
2001 已读回执	`read_sync_key` · `unread_hint`	read_sync_key = 已读游标（≈ 本条 syncKey 减 1~3）
1043 群角色变更	`actor_id` · `target_id` · `op_code`	op_code=0 实测 = 设为管理员；取消管理员只推 2118、不推 1043（不对称）
2063 撤回	`revoked_app_msg_id` · `operator_id` · `room_id` · `revoked_send_time`	四处交叉验证一致

ⓘ补充信令类（content 空、仅群聊、一次群操作可伴随 3~4 条，建议过滤）：2002 · 2055 · 2104 · 2114 · 2118 · 2131 · 2132 · 2180 · 2188 · 2201 · 2215 · 2308（2308 为改群公告伴随）。另：移出成员只推 2118、不推 1006；senderName 常为空，需查通讯录补全；同一内容有多种 contentType（图片 14/101、文件 15/20/102、视频 23/103、表情 29/104），解析层按「同类归一」处理；媒体凭证不落库（fileId / aesKey / 带签名下载链 / 红包票据 / 会议入会链接，建议只存 *_present 标志，用时当场解、用完即弃）。

支持与维护 › 错误码

错误码

调用 API 时，如果返回的 code 不为 0，表示请求失败。你可以根据错误码定位问题并采取相应措施。

🔍

错误码	类型	描述	解决方案
0	成功	请求成功，业务数据在 data 字段	无
401	认证相关	API Key 无效或缺失	请求头带 `X-Nebula-Key: <你的Key>`，值取自控制台「API Key」页
40001	请求参数	请求体必须为 JSON 对象	Content-Type 用 application/json，body 为合法 JSON
40301	接口限制	该接口需申请企业 POC 后开放（体验版仅开放 20 个基础接口）	在控制台「企业 POC」提交申请，审核通过后全部接口开放
40302	接口限制	账号额度已满，无法再接入新实例	申请企业 POC 或联系客服扩容
50001	业务错误	接口调用失败，具体原因见 `message`（如「conversationId is required」）	按 message 提示检查参数、实例是否在线
50000	服务器错误	上游服务调用失败（超时 / 网络异常 / 暂不可用）	请稍后重试，持续失败请联系客服
50002	服务器错误	创建实例成功但未获取到实例标识	请重试，或联系客服

星云API开发文档

多端云设备

登录代理方案

统一 API 规范

快速开始

创建实例

获取 API Key

调用接口

配置 Webhook

正式上线

5 分钟快速开始

注册并登录控制台

创建实例并扫码登录

获取 API Key

调用接口

接收回调（可选）

基础信息准备

请求规范与公共参数

01 · 基础请求信息

02 · 请求地址组成

03 · 请求 Header

04 · 公共参数

05 · POST 请求规范

06 · 请求示例

07 · 统一返回格式

08 · 成功响应示例

09 · 失败响应示例

10 · 错误码

11 · 注意事项

更新日志

Webhook 说明

工作原理

方式一：控制台预览（零代码）

方式二：转发到你的服务器

请求头与请求体

验证签名

回调结构说明

总体说明

消息通用结构

content 的三种形态

contentBase64 解码类型对照

消息类型总览 · 聊天消息

消息类型总览 · 系统 / 通知消息

补充 · 其它已观测到的 msgType

消息示例 · 按类型分类

一、聊天消息

二、联系人相关通知

三、群相关通知

四、会话 / 信令通知

错误码

在线调试

基础信息

联系客服

版本概览

更新说明

事件字段

签名验证

content 三种形态

两类来源

小提示

错误码说明

常见问题

需要帮助？