API 介绍

WuKongIM REST API 完整指南，包含安全规范、请求格式和响应标准

​

概述

WuKongIM 提供了完整的 REST API 接口，用于管理即时通讯系统的各个方面，包括消息发送、频道管理、用户管理、会话管理等功能。

重要安全提醒：WuKongIM API 专为内部业务系统设计，严禁暴露到外网，以防止安全问题。

​

安全注意事项

​

🔒 内部使用限制

• 仅限内部使用：所有 API 接口仅供内部业务系统调用
• 禁止外网暴露：严禁将 API 服务暴露到公网或外部网络
• 端口保护：必须阻止外部网络访问 5001 端口
• 网络隔离：建议在内网环境中部署和使用

​

🛡️ 安全最佳实践

• 在防火墙中阻止 5001 端口的外部访问
• 使用 VPN 或内网环境进行 API 调用
• 定期审查网络访问权限和日志
• 避免在公网文档中暴露 API 端点信息

​

基础信息

​

服务器地址

# 内网环境（推荐）
http://localhost:5001

# 或内网 IP
http://192.168.1.100:5001

​

认证机制

WuKongIM API 无需 Token 认证，因为设计为内部系统专用。所有 API 调用都是直接访问，无需额外的认证头。

​

API 标准和规则

​

📊 HTTP 状态码标准

WuKongIM API 遵循标准的 HTTP 状态码规范：

​

✅ 成功响应 (200)

• HTTP 200：表示请求执行成功
• 某些接口只需检查 HTTP 200 状态码，无需解析 JSON 响应
• 成功响应可能包含数据或仅返回状态确认

​

❌ 失败响应 (非 200)

• HTTP 400：请求参数错误
• HTTP 500：服务器内部错误

​

🔧 请求格式规范

​

Content-Type

所有 POST 请求必须使用 JSON 格式：

Content-Type: application/json

​

请求体示例

{
  "channel_id": "group123",
  "channel_type": 2,
  "from_uid": "user123",
  "payload": "SGVsbG8gV29ybGQ="
}

​

📋 响应格式规范

​

成功响应示例

{
  "message_id": 123456789,
  "message_seq": 1001,
  "client_msg_no": "client_msg_123"
}

​

错误响应格式 (HTTP 400)

{
  "msg": "channel_id 参数不能为空",
  "status": 400
}

文档说明：本文档仅展示成功响应的参数说明，错误响应格式统一为上述格式。

​

核心数据类型

​

📁 频道类型 (channel_type)

值	类型	说明
1	个人频道	一对一私聊频道
2	群组频道	多人群组聊天频道

​

📱 设备标识 (device_flag)

标识值	设备类型	描述
0	App	Android，iPhone、iPad 设备
1	Web	浏览器、Web 应用
2	Desktop	桌面应用程序

​

💬 消息格式

消息内容使用 Base64 编码传输：

{
  "payload": "SGVsbG8gV29ybGQ=",  // Base64 编码的消息内容
  "from_uid": "user123",
  "channel_id": "group123",
  "channel_type": 2
}

​

🔑 重要参数规范

​

channel_id 使用规范

• 直接使用：channel_id 参数应直接使用，无需添加 @ 前缀
• 正确示例："channel_id": "group123"
• 错误示例："channel_id": "@group123"

不要在 channel_id 参数前添加 @ 符号，直接使用原始 ID 值。