跳转到主要内容

​
概述

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)

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

​
💬 消息格式

消息内容使用 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 值。