itom-group/open-im-server-deploy

Fork 0

Files

kim.dev.6789 e50142a3b9 复制项目

2026-01-14 22:16:44 +08:00

15 KiB

Raw Blame History

OpenIM 会议接口文档（用户端 - 前端对接版）

本文档专门用于前端开发人员对接 OpenIM 会议相关 API 接口（用户端）。

基础说明

请求格式

请求方法: 所有接口均使用 POST 方法
Content-Type: application/json
请求头: 需要在请求头中携带 token 进行身份验证

POST /meeting/get_meeting
Content-Type: application/json
token: your_token_here

响应格式

所有接口统一返回以下格式：

{
  "errCode": 0,        // 错误码，0表示成功
  "errMsg": "",        // 错误消息
  "errDlt": "",        // 错误详情
  "data": {}           // 响应数据，具体结构见各接口说明
}

基础URL

根据部署环境配置，例如：

开发环境: http://localhost:10002
生产环境: https://your-domain.com

会议状态说明

状态值	状态名称	说明	用户端可见
1	已预约	会议已创建，等待开始	✅ 可见
2	进行中	会议正在进行	✅ 可见
3	已结束	会议已结束	❌ 不可见
4	已取消	会议已取消	❌ 不可见

重要提示：

用户端接口只能查看状态为 1（已预约） 和 2（进行中） 的会议
状态为 3（已结束） 和 4（已取消） 的会议对用户端不可见

用户端接口

1. 获取会议信息

接口地址: POST /meeting/get_meeting

接口描述: 获取单个会议信息，只能查看已预约和进行中的会议

请求参数:

{
  "meetingID": "string"  // 会议ID（必填）
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "meetingInfo": {
      "meetingID": "string",              // 会议ID
      "subject": "string",                // 会议主题
      "coverURL": "string",               // 封面URL
      "scheduledTime": 1234567890000,     // 预约时间戳（毫秒）
      "status": 1,                        // 会议状态：1-已预约，2-进行中
      "description": "string",            // 会议描述
      "duration": 60,                     // 会议时长（分钟）
      "enableMic": true,                  // 是否开启连麦
      "enableComment": true,             // 是否开启评论
      "anchorUsers": [                    // 主播用户信息列表
        {
          "userID": "user1",
          "nickname": "主播1",
          "faceURL": "https://example.com/avatar1.jpg"
        },
        {
          "userID": "user2",
          "nickname": "主播2",
          "faceURL": "https://example.com/avatar2.jpg"
        }
      ],
      "groupID": "string",              // 关联的群聊ID
      "checkInCount": 50                // 签到人数统计
    }
  }
}

业务规则:

用户端接口只显示状态为 1（已预约） 和 2（进行中） 的会议
如果会议状态为 3（已结束） 或 4（已取消），将返回错误
用户端接口不返回管理字段：
- creatorUserID（创建者ID）
- ex（扩展字段）
- createTime（创建时间）
- updateTime（更新时间）
- estimatedCount（预估人数）
- anchorUserIDs（主播ID列表，只返回 anchorUsers）
返回的主播信息包含用户ID、昵称、头像等完整用户信息
返回签到人数统计（checkInCount），用于显示会议签到情况

错误码:

0: 成功
1001: 参数错误或会议不可用（会议已结束或已取消）
1004: 会议不存在
500: 服务器内部错误

2. 获取会议列表

接口地址: POST /meeting/get_meetings_public

接口描述: 获取会议列表，只能查看已预约和进行中的会议

请求参数:

{
  "status": 1,                      // 会议状态（选填）：1-已预约，2-进行中（只能查询这两个状态）
  "keyword": "string",             // 搜索关键词（选填，搜索主题和描述）
  "startTime": 1234567890000,      // 开始时间戳（毫秒，选填）
  "endTime": 1234567890000,        // 结束时间戳（毫秒，选填）
  "pagination": {
    "pageNumber": 1,               // 页码，从1开始（选填，默认1）
    "showNumber": 20               // 每页数量（选填，默认20）
  }
}

参数说明:

status: 如果指定，只能传入 1 或 2，传入其他值将返回错误
如果不指定 status，查询结果会自动过滤，只返回状态1和2的会议
用户端接口不支持按创建者查询（没有 creatorUserID 参数）

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 100,                   // 总数（只包含状态1和2的会议）
    "meetings": [
      {
        "meetingID": "string",
        "subject": "string",
        "coverURL": "string",
        "scheduledTime": 1234567890000,
        "status": 1,
        "description": "string",
        "duration": 60,
        "enableMic": true,
        "enableComment": true,
        "anchorUsers": [
          {
            "userID": "user1",
            "nickname": "主播1",
            "faceURL": "https://example.com/avatar1.jpg"
          }
        ],
        "groupID": "string",            // 关联的群聊ID
        "checkInCount": 50              // 签到人数统计
      }
    ]
  }
}

业务规则:

用户端接口只显示状态为 1（已预约） 和 2（进行中） 的会议
如果指定 status 参数，只能传入 1 或 2，传入其他值将返回错误
如果不指定 status，查询结果会自动过滤，只返回状态1和2的会议
用户端接口不支持按创建者查询
用户端接口不返回管理字段（创建者ID、扩展字段、创建时间、更新时间、预估人数等）
返回的主播信息包含用户ID、昵称、头像等完整用户信息

错误码:

0: 成功
1001: 参数错误（如状态值不是1或2）
500: 服务器内部错误

签到接口

1. 会议签到

接口地址: POST /meeting/check_in

接口描述: 用户对会议进行签到，一个用户在一个会议中只能签到一次

请求参数:

{
  "meetingID": "string"  // 会议ID（必填）
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "checkInID": "string",    // 签到ID
    "checkInTime": 1234567890000  // 签到时间戳（毫秒）
  }
}

业务规则:

一个用户在一个会议中只能签到一次
只能对状态为 1（已预约） 和 2（进行中） 的会议签到
签到成功后会自动更新会议的签到统计（checkInCount）
如果用户已经签到过，会返回错误

错误码:

0: 成功
1001: 参数错误或会议不可用（会议已结束或已取消）
1001: 用户已签到
1004: 会议不存在
500: 服务器内部错误

2. 检查用户是否已签到

接口地址: POST /meeting/check_user_check_in

接口描述: 检查当前用户是否已对指定会议签到

请求参数:

{
  "meetingID": "string"  // 会议ID（必填）
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "isCheckedIn": true,  // 是否已签到
    "checkInInfo": {      // 签到信息（如果已签到）
      "checkInID": "string",
      "meetingID": "string",
      "userID": "string",
      "checkInTime": 1234567890000,
      "userInfo": {
        "userID": "string",
        "nickname": "string",
        "faceURL": "string"
      }
    }
  }
}

业务规则:

如果用户已签到，返回 isCheckedIn: true 和签到详细信息
如果用户未签到，返回 isCheckedIn: false，checkInInfo 为 null
已签到时，会返回用户的基本信息（用户ID、昵称、头像等）

错误码:

0: 成功
1001: 参数错误
500: 服务器内部错误

3. 获取会议签到列表

接口地址: POST /meeting/get_check_ins

接口描述: 获取指定会议的所有签到记录列表

请求参数:

{
  "meetingID": "string",  // 会议ID（必填）
  "pagination": {
    "pageNumber": 1,      // 页码，从1开始（选填，默认1）
    "showNumber": 20      // 每页数量（选填，默认20）
  }
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 100,         // 总数
    "checkIns": [
      {
        "checkInID": "string",      // 签到ID
        "meetingID": "string",      // 会议ID
        "userID": "string",         // 用户ID
        "checkInTime": 1234567890000, // 签到时间戳（毫秒）
        "userInfo": {               // 用户信息
          "userID": "string",
          "nickname": "string",
          "faceURL": "string"
        }
      }
    ]
  }
}

业务规则:

支持分页查询
签到列表按签到时间倒序排列（最新签到的在前）
每个签到记录包含用户的完整信息（用户ID、昵称、头像等）

错误码:

0: 成功
1001: 参数错误
500: 服务器内部错误

4. 获取会议签到统计

接口地址: POST /meeting/get_check_in_stats

接口描述: 获取指定会议的签到人数统计

请求参数:

{
  "meetingID": "string"  // 会议ID（必填）
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "meetingID": "string",   // 会议ID
    "checkInCount": 50       // 签到人数
  }
}

业务规则:

返回会议的签到总人数
这个统计也会在会议信息中的 checkInCount 字段中返回

错误码:

0: 成功
1001: 参数错误
500: 服务器内部错误

业务规则

1. 会议与群聊的关联

创建会议时会自动创建一个群聊
群聊名称为："会议群-{会议主题}"
会议封面会作为群聊头像

群聊的 ex 字段中会包含会议标识：

{
  "isMeetingGroup": true,
  "meetingID": "会议ID"
}

2. 主播与群角色的关系

有主播列表时：
- 第一个主播 → 群主
- 其他主播 → 管理员
- 创建者（如果不在主播列表中）→ 普通成员
没有主播列表时：
- 创建者 → 群主

3. 评论开关与群禁言

开启评论 (enableComment: true)：
- 自动取消群禁言
- 群成员可以发送消息
关闭评论 (enableComment: false)：
- 自动禁言群
- 群成员无法发送消息

4. 权限控制

查看会议：用户端只能查看已预约和进行中的会议

5. 时间验证

创建会议时，预约时间不能早于当前时间
更新会议时，如果更新预约时间，也不能早于当前时间

错误码说明

通用错误码

错误码	说明
0	成功
500	服务器内部错误
1001	参数错误
1002	权限不足
1004	记录不存在

会议相关错误场景

错误码	场景
1001	查询状态不是1或2
1004	会议不存在
1004	查询已结束或已取消的会议

注意事项

1. 认证

所有接口都需要在请求头中携带 token 进行身份验证
Token通过 /auth/get_user_token 接口获取

2. 请求格式

所有接口使用 POST 方法
Content-Type: application/json
请求体为JSON格式

3. 响应格式

所有接口统一返回格式：{errCode, errMsg, errDlt, data}
errCode 为 0 表示成功，非0表示失败
失败时查看 errMsg 和 errDlt 获取错误详情

4. 时间戳

所有时间戳均为毫秒级Unix时间戳
例如：1234567890000 表示 2009-02-13 23:31:30

5. 分页参数

分页参数统一格式：

{
  "pagination": {
    "pageNumber": 1,    // 页码，从1开始
    "showNumber": 20    // 每页数量
  }
}

6. 用户端接口特点

只能查看状态为 1（已预约） 和 2（进行中） 的会议
不返回管理字段：
- creatorUserID（创建者ID）
- ex（扩展字段）
- createTime（创建时间）
- updateTime（更新时间）
- estimatedCount（预估人数）
- anchorUserIDs（主播ID列表，只返回 anchorUsers）
不支持按创建者查询（没有 creatorUserID 参数）

7. 主播信息

用户端接口只返回 anchorUsers（主播详细信息）
主播信息包含：userID、nickname、faceURL 等

8. 群聊关联

每个会议都会关联一个群聊
通过 groupID 字段可以获取关联的群聊ID
可以使用群聊相关接口（/group/*）操作关联的群聊

9. 会议状态流转

1（已预约） → 2（进行中） → 3（已结束）
              ↓
            4（已取消）

用户端只能查看状态 1（已预约） 和 2（进行中） 的会议
状态 3（已结束） 和 4（已取消） 的会议对用户端不可见

接口汇总表

接口路径	方法	描述	权限要求
`/meeting/get_meeting`	POST	获取会议信息	登录用户
`/meeting/get_meetings_public`	POST	获取会议列表	登录用户

请求示例

curl -X POST http://localhost:10002/meeting/get_meeting \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "meetingID": "meeting123"
  }'

获取会议列表

curl -X POST http://localhost:10002/meeting/get_meetings_public \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "status": 1,
    "keyword": "产品",
    "pagination": {
      "pageNumber": 1,
      "showNumber": 20
    }
  }'

会议签到

curl -X POST http://localhost:10002/meeting/check_in \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "meetingID": "meeting123"
  }'

检查用户是否已签到

curl -X POST http://localhost:10002/meeting/check_user_check_in \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "meetingID": "meeting123"
  }'

获取会议签到列表

curl -X POST http://localhost:10002/meeting/get_check_ins \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "meetingID": "meeting123",
    "pagination": {
      "pageNumber": 1,
      "showNumber": 20
    }
  }'

获取会议签到统计

curl -X POST http://localhost:10002/meeting/get_check_in_stats \
  -H "Content-Type: application/json" \
  -H "token: your_token" \
  -d '{
    "meetingID": "meeting123"
  }'

最后更新时间: 2025-01-23

15 KiB Raw Blame History Unescape Escape

OpenIM 会议接口文档（用户端 - 前端对接版）

目录

基础说明

请求格式

响应格式

基础URL

会议状态说明

用户端接口

1. 获取会议信息

2. 获取会议列表

签到接口

1. 会议签到

2. 检查用户是否已签到

3. 获取会议签到列表

4. 获取会议签到统计

业务规则

1. 会议与群聊的关联

2. 主播与群角色的关系

3. 评论开关与群禁言

4. 权限控制

5. 时间验证

错误码说明

通用错误码

会议相关错误场景

注意事项

1. 认证

2. 请求格式

3. 响应格式

4. 时间戳

5. 分页参数

6. 用户端接口特点

7. 主播信息

8. 群聊关联

9. 会议状态流转

接口汇总表

请求示例

获取会议列表

会议签到

检查用户是否已签到

获取会议签到列表

获取会议签到统计

15 KiB

Raw Blame History