接入概览

Kaya 开放平台的全部接口都由 https://open.kayaio.xyz 提供，与 Kaya 客户端使用的接口完全隔离：开发者平台不接触客户端接口，客户端接口也不会出现在开发者文档中。

当前开放两类能力：

• 群机器人：加入公开群、收消息事件、发消息、@ 成员。
• Kaya 互联：OAuth2 授权码模式的一键登录与用户信息。

所有写操作都要求开发者账号已通过平台认证；未认证账号可以登录控制台查看，但任何创建、修改、发送都会返回 403。

开发者账号

开发者账号就是你的 Kaya 账号：在 https://open.kayaio.xyz/login 用 Kaya 用户名和密码直接登录， 首次登录会自动为你开通开发者账号 —— 没有独立的注册流程，也不需要额外绑定。

• 开放平台不保存 Kaya 密码：密码只在登录这一刻交给 Kaya 主服务校验，通过后只回「这是哪个账号」。
• 任何 Kaya 用户都能登录，但只有通过认证的开发者才能创建机器人、创建互联应用、发送消息。
• 内测期间认证由平台人工开通；如需认证权限请联系平台管理员。

开发者凭据

开发者凭据分两类，都只在创建成功时明文返回一次，请立即保存：

• 机器人回调密钥（webhook_secret）：用于校验事件是否来自 Kaya。库里只存它的哈希，忘记只能重置。
• 应用的 client_secret：用于 OAuth 换 token。同样只存哈希，忘记只能重置（重置不会吊销已签发的 token）。

机器人本身没有「登录密码」：机器人在 IM 内是一个不可登录的账号，只能通过开放平台接口驱动。

群机器人

能力范围

• 通过群号加入公开群（入群方式为「无需申请」的群）。
• 在已加入的群发送文本消息，可 @ 指定群成员。
• 拉取已加入群的历史消息（游标分页）。
• 接收已加入群的新消息事件（webhook 回调）。

创建流程

控制台 → 机器人 → 创建机器人 → 填写名称与简介 → 保存好回调密钥 → 配置 webhook 地址 → 用群号加群。

事件回调

Kaya 会以 POST 把事件推送到你配置的 webhook 地址，请求头：

X-Kaya-Event: message.created
X-Kaya-Timestamp: 1761657600
X-Kaya-Signature: 3f2a...（HMAC-SHA256 十六进制）
X-Kaya-Delivery: 1024
Content-Type: application/json

事件体（message.created）：

{
  "event_id": "m-10240:12",
  "event_type": "message.created",
  "timestamp": 1761657600,
  "bot_id": 12,
  "message": {
    "id": 10240,
    "conversation_id": 88,
    "sender_id": 3,
    "sender_name": "Kaya",
    "type": "text",
    "content": "你好，机器人",
    "mentions": [],
    "created_at": "2026-10-30 00:12:03"
  }
}

响应约定：返回 2xx 视为投递成功；非 2xx 会按 30s → 60s → 120s … 退避重试，最多 6 次，之后置为失败（控制台可见最后一次错误）。同一 event_id 不会重复投递。

选择接入方式

机器人有两种收事件的方式，收到的事件内容完全一致，区别只在「怎么送到你的程序」：

方式	前提	说明
WebSocket	不需要公网服务器	由你的程序主动连到 Kaya，事件顺着长连接推下来。适合个人 / 单机 / 调试，需自己维护长连接状态。
Webhook	需要公网 HTTPS 服务器	Kaya 把事件 POST 到你配置的地址，失败自动重试。适合对外提供服务的机器人，运维更可靠。

在控制台机器人详情页切换；接口：POST /open/api/bots/:id/mode（{"mode":"websocket"|"webhook"}）。

WebSocket 接入

连接地址：wss://open.kayaio.xyz/open/ws

1. 首帧鉴权

连上后 10 秒内必须发出第一帧，否则连接被断开：

{"op":"identify","bot_id":12,"secret":"<你的回调密钥>"}

通过后会收到：{"op":"ready","bot_id":12,"name":"…","heartbeat":30}。 密钥与 Webhook 验签共用同一把（控制台「回调密钥」处）。

2. 收事件

此后每一帧就是一个事件，帧体与 Webhook 请求体逐字节一致，解析代码可以完全复用：

{"event_id":"m-10240:12","event_type":"message.created", ...}

3. 心跳

• 服务端每 30 秒发一个 WebSocket ping 帧，客户端需回 pong（绝大多数库自动处理）。
• 超过 70 秒没有任何帧（含 pong）会被判定断线并关闭连接。

一个机器人可以有多条连接（多台机器跑同一个机器人），事件会推给全部在线连接 —— 业务侧自行去重。

签名算法

签名内容 = 时间戳 + "." + hex(sha256(请求体))，用回调密钥做 HMAC-SHA256：

signature = HMAC_SHA256(secret, ts + "." + hex(SHA256(rawBody)))

请务必：

• 用原始字节计算，不要先反序列化再序列化（格式差异会让摘要不同）。
• 校验时间戳在 ±5 分钟内，防止录制重放。
• 用常量时间比较（hmac.Equal）而不是 ==。

Python 示例：

import hmac, hashlib
def verify(secret, ts, raw: bytes, sig: str) -> bool:
    digest = hashlib.sha256(raw).hexdigest()
    mac = hmac.new(secret.encode(), f"{ts}.{digest}".encode(), hashlib.sha256)
    return hmac.compare_digest(mac.hexdigest(), sig)

接口参考

所有开放接口前缀为 https://open.kayaio.xyz/open/api，均使用会话 Cookie（登录后由控制台下发）鉴权，请求体为 JSON。

方法	路径	说明
POST	/open/api/bots	创建机器人（需认证）
GET	/open/api/bots	机器人列表
POST	/open/api/bots/:id/webhook	设置回调地址
POST	/open/api/bots/:id/secret	重置回调密钥
POST	/open/api/bots/:id/groups	按群号加入公开群
DELETE	/open/api/bots/:id/groups/:conv	退出群聊
POST	/open/api/bots/:id/messages	发送群消息（可带 mentions）
GET	/open/api/bots/:id/messages	拉取群消息（since_id / limit）
GET	/open/api/bots/:id/groups/:conv/members	群成员列表（供 @ 使用）
POST	/open/api/apps	创建互联应用（需认证）
POST	/oauth/token	授权码换 access_token
GET	/open/api/userinfo	凭 Bearer token 取用户信息

发送群消息示例：

POST https://open.kayaio.xyz/open/api/bots/12/messages
{"conversation_id":88,"text":"大家好","mentions":[3]}

错误码

HTTP	含义	处理建议
400	参数不合法	检查字段长度与必填项（机器人名 ≤20，消息 ≤2000 字）
401	未登录 / 令牌无效	重新登录控制台；userinfo 需带 Bearer token
403	未通过开发者认证 / 无权限	等待认证开通；或确认资源归属
404	资源不存在	机器人 / 群 id 是否存在
409	冲突	机器人已在该群内、名称等唯一约束冲突
429	发送频率超限	按机器人每分钟上限退避重试
503	内部通道不可用	平台侧暂时不可用，稍后重试

频率限制

• 机器人发送：20 条/分钟（默认，可在机器人设置里申请调整）。
• 事件投递：单条事件最多重试 6 次，退避 30s 起、上限 30min。
• 授权码有效期 5 分钟且一次性；Kaya 授权会话 15 分钟；access_token 30 天。

Kaya 互联

标准 OAuth2 授权码流程：

1. 把用户送到 https://open.kayaio.xyz/oauth/authorize?client_id=…&redirect_uri=…&state=…
2. 用户在 Kaya 授权页登录并确认（redirect_uri 必须已在应用白名单内）
3. 浏览器重定向到你的 redirect_uri?code=…&state=…
4. 服务端用 code + client_secret 换 token：

POST https://open.kayaio.xyz/oauth/token
grant_type=authorization_code&code=…&client_id=…&client_secret=…&redirect_uri=…

{"access_token":"…","token_type":"Bearer","expires_in":2592000,"scope":"basic"}

取用户信息：

GET https://open.kayaio.xyz/open/api/userinfo
Authorization: Bearer <access_token>

{"uid":3,"username":"Kaya","nickname":"Kaya","avatar":"","scope":"basic"}

安全约定：redirect_uri 做精确字符串比对（不做前缀匹配）；code 一次性且 5 分钟过期；换 token 时必须校验 client_secret。