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 › 回调结构说明

回调结构说明

了解星云 API 实时回调的事件类型、公共字段、content 数据结构和处理方式。

生产环境实测最近验证 2026-09-12 已覆盖 23 种 contentType 示例均已脱敏

▶ 查看实时回调配置 Webhook 查看完整事件类型

30 秒理解回调

你的服务器收到平台 POST 后，按这条链路处理即可，不必读完整页：

01收到 POST平台把事件 POST 到你的回调地址

→

02验签用 X-Nebula-Signature 校验来源可信

→

03遍历 events[]body 是 {instance_guid, events[]}

→

04判 messageType会话类型：0 单聊 / 1 群 / 3 系统

→

05判 contentType内容类型码，决定 content 形状

→

06解析 content按四种结构（A/B/C/D）取值

关键：messageType（会话类型）与 contentType（内容类型）是两个独立字段，不要混用。

回调请求头 / 传输层

平台把事件带签名 POST 到你在「实例与回调」配置的地址。请求头与请求体如下（Headers / Body 切换，可一键复制）：

HeadersBody

Content-Type: application/json
X-Nebula-Timestamp: 1789200000
X-Nebula-Signature: <HMAC-SHA256(secret, timestamp + "." + rawBody)>
User-Agent: Nebula-Webhook/1.0

{
  "instance_guid": "inst_xxxxxxxx",
  "events": [
    {
      "id": 1013420,
      "messageType": 0,
      "contentType": 0,
      "roomId": 0,
      "fromUserId": 7881300000000002,
      "toUserId": 1688850000000001,
      "sendTime": 1789093735,
      "content": [{ "type": 0, "text": "您好" }]
    }
  ]
}

ⓘ回调地址需 HTTPS、公网可访问；请在 10 秒内返回 {"code":0} 确认接收。同一次 POST 的 events[] 可含多条事件，需遍历处理。

传输层 ≠ 事件数据层：你收到的是星云包装层（instance_guid + events[] + X-Nebula-Signature）。平台内部从上游服务包接收事件（X-Wework-* 等）属平台内部链路，不会出现在你收到的请求里。

验证签名

用回调密钥（whsec_…，在「实例与回调」查看）按下式计算，与 X-Nebula-Signature 比对一致即可信：

Python

import hmac, hashlib
sig = hmac.new(secret.encode(),
      (timestamp + ".").encode() + raw_body,
      hashlib.sha256).hexdigest()
# sig == 请求头 X-Nebula-Signature ?（raw_body 用原始字节，勿重序列化）

消息公共结构

events[] 里每条事件的通用字段（真实脱敏样本）：

JSON

{
  "id": 1013420,
  "messageType": 0,
  "contentType": 0,
  "roomId": 0,
  "fromUserId": 7881300000000002,
  "toUserId": 1688850000000001,
  "senderName": "",
  "summary": "您好",
  "sendTime": 1789093735,
  "syncKey": 12014383,
  "flag": 16777216,
  "appInfo": "<appInfo>",
  "extraData": "",
  "devInfo": 0,
  "content": [{ "type": 0, "text": "您好" }]
}

字段	类型	是否必有	说明 / 注意事项
id	int64	是	消息服务端 id（撤回用 serverMsgId）；同账号内唯一，可去重。
messageType	int	是	会话类型：0 好友(单聊) / 1 群聊 / 3 系统通知。见下节。
contentType	int	是	内容类型码，决定 `content` 形状与语义。全表见「事件目录」。
roomId	int64	是	群会话 id；非群（单聊/系统私发）为 `0`。
fromUserId	int64	是	发送方 id。群消息为真实成员 id；系统通知常为系统伪用户（如 10030 / 10014 / 10120，非真实账号）。
toUserId	int64	是	接收方 id，通常是本账号；群/广播类系统通知为 `0`。
senderName	string	否	发送方昵称；实测多为空串（需昵称走通讯录接口）。
summary	string	否	人类可读摘要（如 `[图片]` / `[语音]` / 文章标题）。媒体/系统消息可据此直接展示。
sendTime	int64	是	发送时间（秒级 Unix）。
syncKey	int64	是	同步游标，递增；可作 `message/sync` 的位置标记。
flag	int64	否	内部标志位（位掩码），原样透传即可。
appInfo / extraData / devInfo	—	否	平台内部透传字段，一般无需解析，原样透传。
content	array/object	是	消息内容，四种结构见下节。

大整数（int64）：平台已把超过 JS 安全整数（2⁵³）的大整数 ID 转成字符串下发；仍在安全范围内的保持数字。为稳妥，你侧统一按字符串 / BigInt / json-bigint 处理，切勿直接用 Number 解析。

messageType · 会话类型

好友 / 单聊

roomId=0；fromUserId 为对方 uin。

群聊

roomId 为群 id(>0)；fromUserId 为群内真实发送成员。

系统通知

群相关带群 id；全局类 fromUserId 为系统伪用户（10030 等）。

messageType 只区分会话；具体是文本/图片/系统事件由 contentType 决定。二者不可混用。

content 的四种结构

content 不能用单一结构体解析，按 contentType 走以下四种：

A · 文本数组 contentType 0 / 2

适用：纯文本。正文在 content[].text，多段拼接得完整正文；type：0 普通文本、5 @提及（带 userId+text 昵称）。

最小示例

"content": [{ "type": 0, "text": "就仅仅" }]

B · 媒体对象图片 / 视频 / 文件 / 语音

适用：媒体消息。id（或 url）+ aesKey 是下载凭证，配合下方 API 取原文。

最小示例

"content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>", "size": 1209017 }

cdn/download cdn/urlDownload

C · 系统 hex 对象多数系统通知 / 表情 / 图文

适用：系统信号与部分内容。hex 是十六进制 protobuf（非 base64），很多系统通知 hex 为空串，只作信号——收到即调对应同步接口。msgType == 外层 contentType。

最小示例

"content": { "hex": "", "msgType": 2131 }

D · 结构化明文对象好友申请 / 链接卡片

适用：直接给明文字段，无需解码，字段即可用。

最小示例

"content": { "uin": 7881300000000002, "corpName": "示例网络科技", "customerName": "示例客户" }

contentType 事件目录

搜索或筛选你关心的事件；每条给出会话类型、content 形状、验证状态与「收到后动作」。

全部聊天消息联系人群事件系统通知 ✓ 只看已实测

contentType	名称	messageType	content 形状	验证状态	收到后动作
0	文本	0 / 1	A 文本数组	✓ 已实测	取 content[].text 拼接
2	文本（单聊变体）	0	A 文本数组	✓ 已实测	同 0
13	链接 / 视频号卡片	0 / 1	D 结构化	✓ 已实测	取 title/description/imageUrl/url
14	图片（群）	1	B 媒体	✓ 已实测	id+aesKey → cdn/download
101	图片（单聊）	0	B 媒体	✓ 已实测	url+wechatAuthKey → cdn/urlDownload
15	文件	0 / 1	B 媒体	✓ 已实测	cdn/download
20	文件（转发 / 群）	1	B 媒体	✓ 已实测	cdn/download
16	语音	0 / 1	B 媒体	✓ 已实测	cdn/download（silk）
23	视频	0 / 1	B 媒体	✓ 已实测	cdn/download（忽略发送端 path）
103	视频（单聊）	0	B 媒体	✓ 已实测	url → cdn/urlDownload
104	动画表情	0 / 1	C hex	✓ 已实测	hex 内含 CDN url，需解析
31	图文 / 公众号文章卡片	1 / 3	C hex	✓ 已实测	summary=标题可直接展示
105	系统图文（如「一周小结」）	3	C hex	✓ 已实测	summary=标题
6	位置	0 / 1	D 结构化	—	取经纬度 / 地址
41	名片	0 / 1	D 结构化	—	取字段
78	小程序	0 / 1	D 结构化	—	取字段（两层）
26	红包	0 / 1	C hex	—	原样透传
2001	已读回执	0 / 1	C hex(短)	✓ 已实测	发消息后必收一条，可忽略
2131	外部联系人信息变动 / 删除	3	C hex(常空)	✓ 已实测	调 `contact/syncExternal`
2357	好友申请（结构化）	3	D 结构化	✓ 已实测	展示申请，agreeToNewCustomer 同意
2132	好友申请	3	C hex(常空)	✓ 已实测	同上
2118	群信息变动	1	C hex(常空)	✓ 已实测	按 roomId 刷新群资料
1006	群成员 / 建群相关	1	C hex(成员id)	✓ 已实测	刷新群成员
2104	联系人免打扰 / 置顶	3	C hex	✓ 已实测	原样透传
2130	系统通知（语义待定）	3	C hex(空)	✓ 已实测	原样透传
2180	系统通知（语义待定）	3	C hex(空)	✓ 已实测	原样透传
2201	系统通知（语义待定）	3	C hex(空)	✓ 已实测	原样透传
2186	个人标签变更	3	C hex	—	调 `label/sync`（syncType=2）
2185	企业标签变更	3	C hex	—	调 `label/sync`（syncType=1）
2188	内部联系人变动	3	C hex	—	调通讯录同步
2063	撤回消息	0 / 1	C hex	✓ 已实测	解 hex 字段 15（=原消息 appInfo）定位原消息，标记已撤回

真实消息示例（脱敏）

生产真实报文，已脱敏（id/uin/roomId/md5/aesKey/URL 凭证/姓名替换为占位）。常用类型直接展示，其余折叠。

文本（contentType 0 群 / 2 单聊）

JSON

{ "id": 1000554, "messageType": 1, "contentType": 0, "roomId": 10000000000002,
  "fromUserId": 1688850000000011, "sendTime": 1789106713,
  "content": [{ "type": 0, "text": "就仅仅" }] }

处理：取 content[].text 拼接得完整正文；单聊文本为 contentType 2、messageType:0、roomId:0。

图片（contentType 14 群 / 101 单聊）

JSON

{ "id": 1013724, "messageType": 1, "contentType": 14, "roomId": 10000000000002,
  "content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>",
    "size": 1209017, "width": 1080, "height": 1920, "thumbMd5": "<md5>" } }

处理：14（群）用 id+aesKey 走 cdn/download；101（单聊）content 带 url+wechatAuthKey，走 cdn/urlDownload。

cdn/download cdn/urlDownload

语音（contentType 16）

JSON

{ "id": 1013637, "messageType": 0, "contentType": 16, "summary": "[语音]",
  "content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>", "size": 2608, "voiceTime": 2 } }

处理：voiceTime 秒；silk 格式，走 cdn/download。

视频（contentType 23 / 103）

JSON

{ "id": 1013739, "messageType": 0, "contentType": 23,
  "content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>",
    "size": 2533630, "width": 1920, "height": 1080, "duration": 2 } }

处理：23 走 cdn/download（忽略发送端本地 path）；103（单聊）带 url，走 cdn/urlDownload。

文件（contentType 15 / 20）

JSON

{ "id": 1013745, "messageType": 0, "contentType": 15,
  "content": { "id": "<下载凭证>", "md5": "<md5>", "aesKey": "<aesKey>", "name": "示例文件.jpg", "size": 1863186 } }

处理：走 cdn/download；20（群/转发）同构，summary=发送人 : [文件名]。

104动画表情▸

JSON

{ "id": 1013605, "messageType": 0, "contentType": 104, "summary": "[动画表情]",
  "content": { "hex": "0a4768747470…（十六进制，内含 CDN url 与表情信息）", "msgType": 104 } }

处理：C 结构，hex 为十六进制 protobuf，解出内含 CDN url。

31图文 / 公众号文章卡片▸

JSON

{ "id": 1013415, "messageType": 3, "contentType": 31, "roomId": 10120,
  "summary": "同事们在看《示例文章标题》",
  "content": { "hex": "0aeb020a…（十六进制，含标题/摘要/落地页/配图）", "msgType": 31 } }

处理：summary 即文章标题可直接展示；明细需解 hex。

13链接 / 视频号卡片▸

JSON

{ "id": 1001089, "messageType": 1, "contentType": 13, "roomId": 10000000000002,
  "content": { "title": "卡片标题", "description": "卡片描述",
    "imageUrl": "https://example.com/cover.jpg", "sph_feed_h5_message": { "url": "<base64>" } } }

处理：普通链接取 title/description/imageUrl/url；视频号在 sph_feed_h5_message（字段 base64）。

2063撤回消息▸

JSON

{ "id": 1006265, "messageType": 1, "contentType": 2063, "roomId": 10000000000002,
  "fromUserId": 1688850000000001, "appInfo": "<本条撤回通知自身的标识>",
  "content": { "hex": "180020…（十六进制 protobuf，内嵌被撤回的原消息）", "msgType": 2063 },
  "extraData": "<base64，内含原消息标识>" }

hex 按 protobuf 解码后的关键字段（字段号 → 含义）：

字段号	含义
4	原消息发送者 userId（即撤回人）
5	原消息接收方 userId（单聊时）
7	原消息的 `contentType`（如 0 文本、102 文件）
8	原消息完整内容（嵌套 protobuf）。文本：正文在 8 → 2 → 1；文件：2 文件名、3 下载链接、4 大小（字节）、8/10 md5、25 fileId
12	原消息发送时间（秒级时间戳）
15	原消息的 `appInfo`——与之前收到那条消息的 `appInfo` 完全一致，用它定位被撤回的消息

处理：按字段 15 找到原消息并标记「已撤回」；不要当成新消息展示，也不要再展示或下载被撤回的内容。单聊（messageType 0）与群聊（1）都会推送；用 message/revoke 撤回自己发的消息（serverMsgId 取该消息的 id）同样会收到本回调。已实测文本、文件撤回，结构一致。

系统通知 · 收到后动作

系统通知多为 content:{hex,msgType} 且 hex 常空——它们是信号，重点是「收到后调哪个接口」：

contentType	事件	收到后动作
2001	已读回执	发消息后必收一条，一般忽略
2131	外部联系人信息变动 / 删除	调 contact/syncExternal 拉增量
2357 / 2132	好友申请（结构化 / 信号）	2357 直接给明文可展示；`agreeToNewCustomer` 同意
2118	群信息变动	按 `roomId` 刷新群资料（频率最高的群推送）
1006	群成员 / 建群	刷新群成员（hex 解出为分号连接的成员 uin）
2186	个人标签变更	调 label/sync（syncType=2）
2185	企业标签变更	调 label/sync（syncType=1）
2063	撤回消息	解 `hex` 字段 15 得原消息 `appInfo`，据此找到原消息标记「已撤回」（详见上方「2063 撤回消息」示例）

好友申请 2357（结构化明文）

{ "id": 1013589, "messageType": 3, "contentType": 2357, "roomId": 10030, "fromUserId": 10030,
  "summary": "示例客户@微信申请添加你为联系人",
  "content": { "uin": 7881300000000002, "corpId": 1970320000000001,
    "source": "微信", "corpName": "示例网络科技", "customerName": "示例客户" } }

ⓘfromUserId 为 10030 等是系统伪用户（非真实账号）；hex 空只作信号。

连接事件

长链状态变化也会进入 events[]。你侧按 body 形状识别（你收不到平台内部的事件名头）：

事件	你收到的 body	语义
连接建立 / 已连接	空事件 `{}` —— 平台已自动过滤，不再转发给你	无需处理
长链断开	`{ "code":0, "message":"手动关闭长链", "time":"…" }`	主动关闭（code=0）等；`code` 见错误码

不要只靠连接事件判断账号是否掉线：账号被别处登录踢下线时上游不推断开事件。请以业务探测 / 控制台「实例状态」为准。

哪些操作会触发回调

实测结论——经接口发送消息不触发回调（只会其后一条 2001 回执）：

操作	是否推送
经接口发消息	不推，仅其后一条 contentType 2001 回执
客户端手动发消息	推（文本 / 图片 / 语音 / 视频 / 文件 / 表情…均已抓到）
收到好友申请	推 2357（结构化）/ 2132
外部联系人变动	推 2131 → 调 syncExternal
群设置变更	推若干 2118 + 具体事件
大文件上传完成	推上传完成事件（异步）
账号被别处登录踢下线	不推（见连接事件说明）

解析注意与安全

int64 精度：超过 2⁵³ 的大整数平台已转字符串；统一按字符串 / BigInt 处理，勿用 Number。
hex ≠ base64：系统类 content.hex 是十六进制 protobuf（常为空），不要当 base64 解。
回调与 message/sync 不同源：回调的文本/媒体/结构化类可直接拿明文/凭证；message/sync 返回的是企微 protobuf——两者不可用同一解析器。
媒体凭证（id / aesKey / 下载 url 临时票据）时效性强，不要长期明文保存，即用即取。
示例已脱敏：本页 id / 姓名 / 企业名 / md5 / aesKey / URL 凭证均为占位，真实值以你收到的为准。

▶ 查看实时回调配置 Webhook

遇到问题？在控制台「联系客服」或添加客服微信 xingyunbot 获取技术支持。

支持与维护 › 错误码

错误码

调用 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 说明

工作原理

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

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

请求头与请求体

验证签名

回调结构说明

30 秒理解回调

回调请求头 / 传输层

验证签名

消息公共结构

messageType · 会话类型

好友 / 单聊

群聊

系统通知

content 的四种结构

A · 文本数组 contentType 0 / 2

B · 媒体对象 图片 / 视频 / 文件 / 语音

C · 系统 hex 对象 多数系统通知 / 表情 / 图文

D · 结构化明文对象 好友申请 / 链接卡片

contentType 事件目录

真实消息示例（脱敏）

文本（contentType 0 群 / 2 单聊）

图片（contentType 14 群 / 101 单聊）

语音（contentType 16）

视频（contentType 23 / 103）

文件（contentType 15 / 20）

系统通知 · 收到后动作

连接事件

哪些操作会触发回调

解析注意与安全

错误码

在线调试

基础信息

联系客服

版本概览

更新说明

事件字段

签名验证

错误码说明

常见问题

需要帮助？

B · 媒体对象图片 / 视频 / 文件 / 语音

C · 系统 hex 对象多数系统通知 / 表情 / 图文

D · 结构化明文对象好友申请 / 链接卡片