> ## Documentation Index
> Fetch the complete documentation index at: https://wukong.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API 介绍

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

## 概述

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

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

## 安全注意事项

### 🔒 内部使用限制

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

### 🛡️ 安全最佳实践

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

## 基础信息

### 服务器地址

```bash theme={null}
# 内网环境（推荐）
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 格式：

```bash theme={null}
Content-Type: application/json
```

#### 请求体示例

```json theme={null}
{
  "channel_id": "group123",
  "channel_type": 2,
  "from_uid": "user123",
  "payload": "SGVsbG8gV29ybGQ="
}
```

### 📋 响应格式规范

#### 成功响应示例

```json theme={null}
{
  "message_id": 123456789,
  "message_seq": 1001,
  "client_msg_no": "client_msg_123"
}
```

#### 错误响应格式 (HTTP 400)

```json theme={null}
{
  "msg": "channel_id 参数不能为空",
  "status": 400
}
```

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

## 核心数据类型

### 📁 频道类型 (channel\_type)

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

### 📱 设备标识 (device\_flag)

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

### 💬 消息格式

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

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

### 🔑 重要参数规范

#### channel\_id 使用规范

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

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