聊天服务 API 参考

本页列出当前聊天服务源码的 HTTP 契约，包括星线 App 使用的个人业务接口、独立 MLS 接口及共享后台中属于星企的企业接口。基地址为 https://chat.thestarline.cn。路由存在仅代表代码实现，不能证明生产依赖已经配置、客户端已经接入或真实设备路径已经验收。

通用约定

除 GET /health、GET /auth/start、POST /auth/native/start、GET /auth/callback 和 POST /auth/exchange 外，以下接口均要求 Authorization: Bearer <chat_access_token>。这是聊天服务签发的 token，不能用 Account access token、OIDC ID token 或 LiveKit 媒体 token 替代。星企接口还要求相应企业成员和角色权限。

JSON 请求使用 Content-Type: application/json，根必须为对象，默认请求体上限为 16,384 字节；本文标注的接口有单独上限。二进制上传直接发送文件字节，不是 multipart。JSON 响应为 UTF-8，使用 Cache-Control: no-store 与 X-Content-Type-Options: nosniff。媒体下载使用单独响应头。

时间值是 Unix 毫秒时间戳。UUID 字段用字符串；普通消息、事件、新事、评论等 ID 为安全整数；企业消息 ID 对外为字符串。分页游标均作用于指定资源，不能互换。下表中的 {id} 表示路径参数，不含字面花括号。

错误响应统一为：

{"error":{"code":"INVALID_CURSOR","message":"游标无效"}}

错误码必须与 HTTP 状态和具体路由一起判断。例如 NOT_FRIENDS 在联系动作中可为403，而建群/邀请成员返回400，邀请还可能是总人数超过50人；不能只按代码名推断唯一原因。详见限制与错误。

未支持的路由通常为 404，不保证返回 405。/__preview/enterprise/session 被明确禁用，始终返回 404，不是登录或测试会话入口。

健康与授权

这些接口无需聊天 Bearer token；授权完成后才获得业务会话。完整信任与到期语义见登录与会话。

native/start 的 app 不合法返回 INVALID_APP，挑战错误返回 INVALID_CHALLENGE，screen 错误返回 INVALID_SCREEN。服务端 Account token 交换使用机密客户端认证与服务端 PKCE verifier，App 不发送客户端 secret。原生 proof 失败不会签发会话；兼容票据不能携带原生 proof 伪装成新流程。两端本机退出都可能忽略远端logout失败，本机已清除不证明服务端撤销；Account密码变化也不自动撤销独立聊天session。

以下仅示意请求形状。占位挑战、ticket、state 和 verifier 必须由同一次测试授权流程产生，不能照抄为生产凭据：

curl -X POST 'https://chat.thestarline.cn/auth/native/start' \
  -H 'Content-Type: application/json' \
  --data '{"app":"starline","screen":"login","codeChallenge":"<S256_BASE64URL_43>"}'

curl -X POST 'https://chat.thestarline.cn/auth/exchange' \
  -H 'Content-Type: application/json' \
  --data '{"ticket":"<ONE_USE_TICKET>","state":"<SAME_STATE>","codeVerifier":"<LOCAL_VERIFIER>"}'

当前用户与资料

所有接口要求 Bearer。User 形状为 {id,displayName,friendId}。Profile 形状为 {user,bio,contactPhone}，本人读取时另含 phoneVisibility、visibleToUserIds；不可见手机号为 null。

手机号删除空格与短横线，11 位中国大陆手机号补 +86，其他形式需符合 + 开头的 8–15 位国际号码。资料手机号可见性不等于 Account 安全手机号设置。错误包括 INVALID_BIO、INVALID_PHONE、INVALID_VISIBILITY、INVALID_VIEWERS、SELF_BLOCK；屏蔽中媒体服务失败可返回 CALL_MEDIA_UNAVAILABLE。

好友与单聊

好友建立

friendId 去空格/短横线并转大写后须 11 位字母数字；temporaryCode 同样规范化后须 12 位 A–F/0–9。手机号和临时码查找分别按用户、方法每 10 分钟最多 20 次。错误包括 INVALID_INPUT、INVALID_FRIEND_ID、INVALID_FRIEND_CODE、SELF_FRIEND、ALREADY_FRIENDS、INCOMING_REQUEST、CONTACT_BLOCKED 和 TOO_MANY_LOOKUPS。未知或过期临时码返回 NOT_FOUND；收到对方申请时应处理 incoming，而不是重复反向申请。

单聊列表与消息

会话对象含 id、peer、lastMessage、unreadCount、peerReadMessageId、createdAt、isFriend、isBlocked、isHidden。普通消息含 id、senderId、clientId、body、media、createdAt；发送回执另含 conversationId、duplicate。media 不存在时为 null。文字 trim 后须非空且 ≤2000 Unicode 码点；媒体必须属于当前发送者。

相同发送者的 clientId 在普通单聊消息表中唯一；不同会话、正文或媒体复用同一 ID 返回 CLIENT_ID_REUSED。preparing/active/blocked 的 MLS 会话拒绝普通明文发送并返回 E2EE_REQUIRED。读取仍受个人历史边界和隐藏消息过滤。恢复聊天不恢复被历史边界排除的内容。

CHAT_TOKEN='<AUTHORIZED_TEST_SESSION>'
CONVERSATION_ID='11111111-1111-4111-8111-111111111111'
curl "https://chat.thestarline.cn/conversations/${CONVERSATION_ID}/messages?limit=50" \
  -H "Authorization: Bearer ${CHAT_TOKEN}"
curl -X POST "https://chat.thestarline.cn/conversations/${CONVERSATION_ID}/messages" \
  -H "Authorization: Bearer ${CHAT_TOKEN}" -H 'Content-Type: application/json' \
  --data '{"clientId":"22222222-2222-4222-8222-222222222222","text":"这是合成测试消息"}'

示例 UUID 是合成值，必须换成测试账号实际有权访问的范围；发送属于写操作，请仅在授权测试会话中使用。

个人群聊

企业频道使用另一组 enterprise 路由，不能与以下个人群互换。

group 对象含 id、name、ownerId、createdAt、memberCount、lastMessage、unreadCount、allReadMessageId、isMuted、isHidden。群消息额外含 senderDisplayName。常见错误是 INVALID_GROUP_NAME、INVALID_GROUP_MEMBERS、NOT_FRIENDS、FORBIDDEN、SELF_REMOVE、INVALID_MESSAGE、CLIENT_ID_REUSED、E2EE_REQUIRED；媒体处理失败可使成员操作返回503。

聊天文件、贴纸与城市

Media={id,kind,name,mimeType,size,createdAt}。file最大10 MiB，sticker最大512 KiB；账号聊天媒体总量100 MiB，自定义贴纸最多100个。文件名trim后1–120码点，禁止控制字符与路径分隔符。MIME需符合类型格式；贴纸必须有效PNG或JPEG，PNG宽高均≤2048。城市ID格式为小写字母开头、随后小写字母/数字/短横线、总长≤64，还必须存在于实际目录。

错误包括 INVALID_KIND、INVALID_NAME、INVALID_TYPE、EMPTY_FILE、INVALID_STICKER、TOO_LARGE、STORAGE_LIMIT、INVALID_CITY、CITY_STICKER_UNAVAILABLE、NOT_FOUND。普通上传保存原始字节，没有自动附件加密；上传后仍需发送引用mediaId的消息。下载的owner分支独立，非所有者的单聊可见消息分支不重查is_friend/block；群消息分支要求当前成员。因此删好友或屏蔽不保证撤销原先仍可见普通媒体。依据：chat-service/src/database.mjs:239-254。文件头校验不等于病毒扫描。

curl -X POST 'https://chat.thestarline.cn/media?kind=file&name=example.txt' \
  -H "Authorization: Bearer ${CHAT_TOKEN}" \
  -H 'Content-Type: text/plain' --data-binary '合成附件内容'

新事与互动

所有新事接口均需Bearer。visibility可为friends、selected、public、private，默认friends；public指已登录API用户可见，不是匿名网页。selected必须指定当前好友，屏蔽和个人隐藏会进一步过滤。

帖子输入viewerIds最多100、不重复、UUID，非selected时必须为空；selected至少一位有效未屏蔽好友。mediaIds最多9、不重复、UUID；必须为自己尚未绑定其他帖子的媒体。图片最多9张，或仅1段视频，不得混发。未绑定媒体超过24小时清理。PNG仍执行宽高≤2048校验，视频检查ftyp标识。

post含id、authorId、text、visibility、createdAt、author、media、likeCount、commentCount、liked、recentComments；作者读取selected帖子可得到viewerIds。comment含id、postId、authorId、replyToId、text、createdAt、authorName。通知含actorId、actorName、postId、commentId、kind、createdAt、readAt，kind为like/comment/reply。

错误包括INVALID_POST、INVALID_COMMENT、INVALID_REPORT、INVALID_MEDIA、INVALID_RANGE、INVALID_LIMIT、NOT_FOUND、FORBIDDEN。某些输入被权限过滤后得到404；不能仅因知道帖子或媒体ID就访问内容。

实时位置

以下路径模板中的 {resource} 必须替换为 conversations 或 groups，两类范围各实现相同四个Method。

经纬度与精度需有限数字，latitude为-90–90，longitude为-180–180，accuracy为0–100000。位置对象含userId、displayName、latitude、longitude、accuracy、startedAt、updatedAt。当前没有服务端自动到期字段，也没有位置写入普通events的契约。此数据不是MLS密文。

普通变更长轮询

GET /events 的query为after（默认0，非负安全整数）、wait（默认20，0–25秒）。响应200 {events,cursor}，每批最多100条、按ID升序；空批次保持原cursor。event为{id,conversationId,groupId,kind,messageId,createdAt}，可选引用可能null。客户端收到事件后重新获取对应业务资源，不应把它当完整消息内容。

curl 'https://chat.thestarline.cn/events?after=0&wait=20' \
  -H "Authorization: Bearer ${CHAT_TOKEN}"

客户端应连续维护轮询和断线重连。更多游标和客户端恢复行为见实时同步与通话。

MLS 设备与加密事件

这些接口要求Bearer且服务器已加载可用MLS校验器，否则503 E2EE_UNAVAILABLE。deviceId格式为[A-Za-z0-9_-]{1,80}；keyPackage与payload用规范标准base64，不是base64url。服务端验证MLS封装，终端负责完整消息认证与解密。

下表 {resource} 为conversations或groups，每种各有8条Method+path。范围必须属于当前用户；除state只查范围外，其余需相应已注册设备。单聊prepare、events POST、activate还需当前好友且未屏蔽。

加密event含sequence、kind、clientId、senderUserId、senderDeviceId、payload、createdAt、targetUserId、targetDeviceId。服务端按发送者、设备、clientId去重，检查范围、类型、payload摘要、收件人和包ID完全相同。Welcome定向单设备并消费相应密钥包；application仅active可发；preparing阶段仅创建者建立群；后续Commit协调及activate受创建者限制。

关键错误包括INVALID_KEY_PACKAGE、DEVICE_KEY_CHANGED、TOO_MANY_PACKAGES、NOT_MEMBER、UNKNOWN_DEVICE、MISSING_DEVICE、ALREADY_PREPARED、INVALID_EVENT、NOT_PREPARED、CLIENT_ID_REUSED、NOT_ACTIVE、PREPARING、NOT_CREATOR、INVALID_RECIPIENT、PACKAGE_USED、INVALID_WELCOME、INVALID_COMMIT、AWAITING_WELCOME、AWAITING_COMMIT、AWAITING_REKEY、INVALID_SCOPE。HTTP映射为NOT_MEMBER→404，UNKNOWN_DEVICE→403，INVALID_KEY_PACKAGE/INVALID_EVENT/INVALID_RECIPIENT/INVALID_WELCOME→400，其余具名MLS错误通常409。

当前iOS独立MLS传输器实现文字payload，Android与主聊天尚未完成同等接入；本节不提供虚构密文可直接发送的curl。联调需调用真实加密核心生成有效TLS字节，随意base64字符串会被拒绝。完整顺序见消息与媒体。

通话与 VoIP 设备

Call对象含id、scopeKind、scopeId、callerId、mode、state、createdAt、startedAt、endedAt、endedReason，不含内部roomName及请求clientId。state为ringing/active/ended/missed/cancelled；startedAt和endedAt可null。所有其他成员忙时，POST也可返回201且state=ended、endedReason=busy；必须检查对象状态。

媒体token不是聊天会话，不能公开缓存、写入静态站或长期复用。错误包括INVALID_CALL、INVALID_CALL_SCOPE、INVALID_VOIP_DEVICE、CALL_BUSY、CALL_STATE、CALL_MEDIA_UNAVAILABLE。状态机、空房回收与真实跨网络验收边界见实时同步与通话。

记忆识别与转出桥接

schema含category、icon、fields；字段含id、title、type、options，type为服务端归一化的表单字段类型，签证和宠物疫苗主题还会补充专用字段。请求的text会发送至聊天服务及配置模型，用于生成结构；这不形成持久记忆库或云同步，不能把“未持久保存”理解为“没有上传”。当前权威Account主源码没有/api/memory-export/redeem路由；App工作树的历史Account副本虽有实现，也不能证明当前服务支持。因此聊天侧转出桥接不能当成已验收能力。错误包括EXPORT_UNAVAILABLE、INVALID_EXPORT_TICKET、ACCOUNT_MISMATCH、INVALID_MEMORY_TEXT。

共享后台：独立星企企业接口

本节用于解释共享服务的完整路由范围。这些是星企接口，不是星线 App 个人前台功能。全部要求聊天Bearer；进入指定企业路径先验证企业成员，随后按操作检查manager（admin/owner）或owner。企业ID与个人群ID不能互换。

令以下表格的{org}表示/enterprise/organizations/{organizationId}，仅为排版缩写，实际请求必须展开完整路径。

企业常见错误为FORBIDDEN、INVALID_INPUT、NOT_FOUND、INVALID_INVITATION、INVITATION_ALREADY_USED、DECISION_CONFLICT、INVALID_DEPARTMENT、INVALID_MEMBER、INVALID_ASSIGNEE、INVALID_URL与CLIENT_ID_REUSED。邀请被撤销或过期不可批准加入；已被决定的同一邀请不能复活旧申请。企业频道保存服务端可读文字，不属于个人聊天MLS范围，也没有据此推导的企业附件路由。

调用与联调顺序

建议先在受控测试账号完成native/start→Account→callback→exchange，再调用/me确认身份与事件游标；之后读取列表，使用合成文字及小文件验证发送、重试、下载与已读。MLS联调必须使用真实生成的测试密钥包和密文；通话联调要在API状态之外验证双设备媒体与后台来电。

本页所有示例为合成或占位内容，没有生产凭据。接口细节与文档不一致时，以当前源码和可复核测试结果更新契约；不要通过去掉proof、改用旧接口或绕过成员检查“修复”失败。继续阅读数据模型、安全和隐私、测试及运维。

按业务流程联调时可结合联系人与个人群、新事、位置共享、MLS协议和限制与错误读取状态与失败分支。