API Overview

API 概览

IMBoy 提供两类接口：REST API（认证、用户、消息管理）和 WebSocket（实时双向通讯）。

---

认证方式

所有 REST 接口需要在请求头中携带 JWT Token：

Authorization: Bearer <token>

获取 Token：

POST /v1/passport/login
Content-Type: application/json

{
  "identifier": "username_or_phone",
  "password": "md5(password)"
}

响应：

{
  "code": 0,
  "data": {
    "token": "eyJ...",
    "uid": "123456789",
    "expire_at": 1752345678
  }
}

---

REST API 主要端点

用户

方法	路径	说明
POST	/v1/passport/register	注册
POST	/v1/passport/login	登录
POST	/v1/passport/logout	登出
POST	/v1/passport/refresh	刷新 Token
GET	/v1/user/profile	获取当前用户信息
PUT	/v1/user/profile	更新用户信息

好友

方法	路径	说明
GET	/v1/friend/list	好友列表
POST	/v1/friend/add	发送好友申请
POST	/v1/friend/accept	同意好友申请
DELETE	/v1/friend/:uid	删除好友

群组

方法	路径	说明
POST	/v1/group/create	创建群组
GET	/v1/group/list	我的群组列表
GET	/v1/group/:id/members	群成员列表
POST	/v1/group/:id/invite	邀请成员
DELETE	/v1/group/:id/member/:uid	踢出成员

消息

方法	路径	说明
GET	/v1/message/history	历史消息（分页）
DELETE	/v1/message/:id	撤回消息

附件

方法	路径	说明
POST	/v1/upload/presign	获取预签名上传 URL
GET	/v1/upload/view	获取授权下载 URL

E2EE

方法	路径	说明
POST	/v1/e2ee/user_keys	上传设备公钥
GET	/v1/e2ee/user_keys	获取用户公钥
GET	/v1/e2ee/group_member_keys	获取群成员公钥

---

统一响应格式

{
  "code": 0,          // 0 = 成功；非 0 = 错误码
  "msg": "ok",        // 人类可读的消息
  "data": { ... },    // 业务数据（成功时）
  "meta": {           // 分页元数据（列表接口）
    "total": 100,
    "page": 1,
    "size": 20
  }
}

常见错误码见 include/error_code.hrl。

---

WebSocket 接口

连接

wss://yourdomain.com/ws?token=<jwt_token>

消息格式

所有 WebSocket 消息为 JSON，结构如下：

{
  "msg_id": "unique_message_id",
  "type": "c2c_msg",
  "payload": { ... },
  "timestamp": 1752345678000
}

主要消息类型

type	方向	说明
c2c_msg	双向	单聊消息
c2g_msg	双向	群聊消息
ack	客户端→服务端	消息已收到确认
ping	客户端→服务端	心跳
pong	服务端→客户端	心跳响应
token_refresh	服务端→客户端	要求刷新 Token
e2ee_key_alert	服务端→客户端	对方密钥已变更警告

QoS 投递机制

在线投递 → 未 ACK → 2s 重试 → 5s 重试 → 7s 重试 → 11s 重试
                                                        ↓
                                               转离线消息存储

---

调试工具

# WebSocket 调试
open https://coolaf.com/tool/chattest
# 连接地址：wss://yourdomain.com/ws?token=<token>

# 获取测试 Token（本地开发）
# 在 Erlang shell 中执行：
token_ds:encrypt_token(UserId).