WechatHookBot/docs/API文档.md

# WechatHookBot API 文档

## WechatHookClient API 参考

基于个微大客户版 Hook API 封装的 Python 客户端。

## 消息发送

### send_text - 发送文本消息

```python
await client.send_text(to_wxid: str, content: str) -> bool
```

**参数：**
- `to_wxid`: 接收者 wxid（个人或群聊）
- `content`: 文本内容

**返回：** 是否发送成功

**示例：**
```python
await client.send_text("wxid_xxx", "你好，世界")
await client.send_text("123@chatroom", "群聊消息")
```

---

### send_image - 发送图片

```python
await client.send_image(to_wxid: str, image_path: str) -> bool
```

**参数：**
- `to_wxid`: 接收者 wxid
- `image_path`: 图片文件路径

**支持格式：** jpg, png, gif

**示例：**
```python
await client.send_image("wxid_xxx", "D:/images/photo.jpg")
```

---

### send_file - 发送文件

```python
await client.send_file(to_wxid: str, file_path: str) -> bool
```

**参数：**
- `to_wxid`: 接收者 wxid
- `file_path`: 文件路径

**示例：**
```python
await client.send_file("wxid_xxx", "D:/documents/report.pdf")
```

---

### send_video - 发送视频

```python
await client.send_video(to_wxid: str, video_path: str) -> bool
```

**参数：**
- `to_wxid`: 接收者 wxid
- `video_path`: 视频文件路径

**示例：**
```python
await client.send_video("wxid_xxx", "D:/videos/demo.mp4")
```

---

### send_card - 发送名片

```python
await client.send_card(to_wxid: str, card_wxid: str, card_nickname: str) -> bool
```

**参数：**
- `to_wxid`: 接收者 wxid
- `card_wxid`: 名片的 wxid
- `card_nickname`: 名片昵称

**示例：**
```python
await client.send_card("wxid_xxx", "wxid_yyy", "张三")
```

---

### send_location - 发送位置

```python
await client.send_location(
    to_wxid: str,
    latitude: float,
    longitude: float,
    title: str,
    address: str
) -> bool
```

**参数：**
- `to_wxid`: 接收者 wxid
- `latitude`: 纬度
- `longitude`: 经度
- `title`: 位置标题
- `address`: 详细地址

**示例：**
```python
await client.send_location(
    "wxid_xxx",
    39.9042,
    116.4074,
    "天安门",
    "北京市东城区"
)
```

---

### send_link - 发送链接

```python
await client.send_link(
    to_wxid: str,
    title: str,
    desc: str,
    url: str,
    thumb_url: str = ""
) -> bool
```

**参数：**
- `to_wxid`: 接收者 wxid
- `title`: 链接标题
- `desc`: 链接描述
- `url`: 链接地址
- `thumb_url`: 缩略图 URL（可选）

**示例：**
```python
await client.send_link(
    "wxid_xxx",
    "新闻标题",
    "新闻摘要",
    "https://example.com/news",
    "https://example.com/thumb.jpg"
)
```

---

### send_miniapp - 发送小程序

```python
await client.send_miniapp(
    to_wxid: str,
    appid: str,
    title: str,
    page_path: str,
    thumb_url: str = ""
) -> bool
```

**参数：**
- `to_wxid`: 接收者 wxid
- `appid`: 小程序 appid
- `title`: 小程序标题
- `page_path`: 小程序页面路径
- `thumb_url`: 缩略图 URL（可选）

**示例：**
```python
await client.send_miniapp(
    "wxid_xxx",
    "wx1234567890",
    "小程序标题",
    "pages/index/index"
)
```

---

### send_at_message - 发送群聊@消息

```python
await client.send_at_message(
    chatroom_id: str,
    content: str,
    at_list: list[str]
) -> bool
```

**参数：**
- `chatroom_id`: 群聊 ID
- `content`: 消息内容
- `at_list`: 要@的 wxid 列表

**示例：**
```python
# @指定用户
await client.send_at_message(
    "123@chatroom",
    "大家好",
    ["wxid_aaa", "wxid_bbb"]
)

# @所有人
await client.send_at_message(
    "123@chatroom",
    "重要通知",
    ["notify@all"]
)
```

---

### revoke_message - 撤回消息

```python
await client.revoke_message(msg_id: str) -> bool
```

**参数：**
- `msg_id`: 消息 ID

**示例：**
```python
await client.revoke_message("1234567890")
```

---

## 好友管理

### get_friend_list - 获取好友列表

```python
await client.get_friend_list() -> list[dict]
```

**返回：** 好友列表

**示例：**
```python
friends = await client.get_friend_list()
for friend in friends:
    print(friend["wxid"], friend["nickname"])
```

---

### get_friend_info - 获取好友信息

```python
await client.get_friend_info(wxid: str) -> dict
```

**参数：**
- `wxid`: 好友 wxid

**返回：** 好友详细信息

**示例：**
```python
info = await client.get_friend_info("wxid_xxx")
print(info["nickname"], info["remark"])
```

---

### search_user - 搜索用户

```python
await client.search_user(keyword: str) -> dict
```

**参数：**
- `keyword`: 搜索关键词（wxid、手机号、微信号）

**返回：** 用户信息

**示例：**
```python
result = await client.search_user("wxid_xxx")
if result:
    print(result["nickname"])
```

---

### add_friend - 添加好友

```python
await client.add_friend(
    wxid: str,
    verify_msg: str = "",
    scene: int = 3
) -> bool
```

**参数：**
- `wxid`: 要添加的 wxid
- `verify_msg`: 验证消息
- `scene`: 添加场景（3=搜索，15=名片）

**示例：**
```python
await client.add_friend("wxid_xxx", "你好，我是...")
```

---

### accept_friend - 同意好友请求

```python
await client.accept_friend(v3: str, v4: str, scene: int) -> bool
```

**参数：**
- `v3`: 好友请求的 v3 参数
- `v4`: 好友请求的 v4 参数
- `scene`: 场景值

**示例：**
```python
# 从好友请求消息中获取参数
await client.accept_friend(v3, v4, scene)
```

---

### delete_friend - 删除好友

```python
await client.delete_friend(wxid: str) -> bool
```

**参数：**
- `wxid`: 要删除的好友 wxid

**示例：**
```python
await client.delete_friend("wxid_xxx")
```

---

### set_friend_remark - 修改好友备注

```python
await client.set_friend_remark(wxid: str, remark: str) -> bool
```

**参数：**
- `wxid`: 好友 wxid
- `remark`: 新备注

**示例：**
```python
await client.set_friend_remark("wxid_xxx", "张三")
```

---

### check_friend_status - 检测好友状态

```python
await client.check_friend_status(wxid: str) -> dict
```

**参数：**
- `wxid`: 好友 wxid

**返回：** 好友状态信息

**示例：**
```python
status = await client.check_friend_status("wxid_xxx")
print(status["is_friend"])  # 是否是好友
```

---

## 群聊管理

### get_chatroom_list - 获取群聊列表

```python
await client.get_chatroom_list() -> list[dict]
```

**返回：** 群聊列表

**示例：**
```python
chatrooms = await client.get_chatroom_list()
for room in chatrooms:
    print(room["chatroom_id"], room["name"])
```

---

### get_chatroom_members - 获取群成员

```python
await client.get_chatroom_members(chatroom_id: str) -> list[dict]
```

**参数：**
- `chatroom_id`: 群聊 ID

**返回：** 群成员列表

**示例：**
```python
members = await client.get_chatroom_members("123@chatroom")
for member in members:
    print(member["wxid"], member["nickname"])
```

---

### get_chatroom_info - 获取群信息

```python
await client.get_chatroom_info(chatroom_id: str) -> dict
```

**参数：**
- `chatroom_id`: 群聊 ID

**返回：** 群聊详细信息

**示例：**
```python
info = await client.get_chatroom_info("123@chatroom")
print(info["name"], info["member_count"])
```

---

### create_chatroom - 创建群聊

```python
await client.create_chatroom(member_list: list[str]) -> str
```

**参数：**
- `member_list`: 成员 wxid 列表（至少2人）

**返回：** 新群聊的 chatroom_id

**示例：**
```python
chatroom_id = await client.create_chatroom(["wxid_aaa", "wxid_bbb"])
```

---

### invite_to_chatroom - 邀请进群

```python
await client.invite_to_chatroom(
    chatroom_id: str,
    wxid_list: list[str]
) -> bool
```

**参数：**
- `chatroom_id`: 群聊 ID
- `wxid_list`: 要邀请的 wxid 列表

**示例：**
```python
await client.invite_to_chatroom("123@chatroom", ["wxid_xxx", "wxid_yyy"])
```

---

### remove_chatroom_member - 踢出群成员

```python
await client.remove_chatroom_member(
    chatroom_id: str,
    wxid_list: list[str]
) -> bool
```

**参数：**
- `chatroom_id`: 群聊 ID
- `wxid_list`: 要踢出的 wxid 列表

**示例：**
```python
await client.remove_chatroom_member("123@chatroom", ["wxid_xxx"])
```

---

### quit_chatroom - 退出群聊

```python
await client.quit_chatroom(chatroom_id: str) -> bool
```

**参数：**
- `chatroom_id`: 群聊 ID

**示例：**
```python
await client.quit_chatroom("123@chatroom")
```

---

### set_chatroom_name - 修改群名称

```python
await client.set_chatroom_name(chatroom_id: str, name: str) -> bool
```

**参数：**
- `chatroom_id`: 群聊 ID
- `name`: 新群名称

**示例：**
```python
await client.set_chatroom_name("123@chatroom", "新群名")
```

---

### set_chatroom_announcement - 修改群公告

```python
await client.set_chatroom_announcement(
    chatroom_id: str,
    announcement: str
) -> bool
```

**参数：**
- `chatroom_id`: 群聊 ID
- `announcement`: 群公告内容

**示例：**
```python
await client.set_chatroom_announcement("123@chatroom", "群公告内容")
```

---

### set_my_chatroom_nickname - 修改我的群昵称

```python
await client.set_my_chatroom_nickname(
    chatroom_id: str,
    nickname: str
) -> bool
```

**参数：**
- `chatroom_id`: 群聊 ID
- `nickname`: 新昵称

**示例：**
```python
await client.set_my_chatroom_nickname("123@chatroom", "我的群昵称")
```

---

## 登录信息

### get_login_info - 获取当前登录信息

```python
await client.get_login_info() -> dict
```

**返回：** 登录账号信息

**示例：**
```python
info = await client.get_login_info()
print(info["wxid"], info["nickname"])
```

---

## CDN 功能

### cdn_upload - CDN 上传

```python
await client.cdn_upload(file_path: str) -> dict
```

**参数：**
- `file_path`: 文件路径

**返回：** CDN 信息（包含 aes_key, file_id 等）

**示例：**
```python
cdn_info = await client.cdn_upload("D:/files/image.jpg")
```

---

### cdn_download - CDN 下载

```python
await client.cdn_download(
    aes_key: str,
    file_id: str,
    save_path: str
) -> bool
```

**参数：**
- `aes_key`: AES 密钥
- `file_id`: 文件 ID
- `save_path`: 保存路径

**示例：**
```python
await client.cdn_download(aes_key, file_id, "D:/downloads/file.jpg")
```

---

## 企业微信

### get_work_chatroom_list - 获取企业群列表

```python
await client.get_work_chatroom_list() -> list[dict]
```

---

### get_work_friend_list - 获取企业好友列表

```python
await client.get_work_friend_list() -> list[dict]
```

---

### get_work_chatroom_members - 获取企业群成员

```python
await client.get_work_chatroom_members(chatroom_id: str) -> list[dict]
```

---

## 错误处理

所有 API 调用失败时会抛出异常或返回 False/None，建议使用 try-except 处理：

```python
try:
    result = await client.send_text("wxid_xxx", "消息")
    if result:
        logger.info("发送成功")
    else:
        logger.error("发送失败")
except Exception as e:
    logger.error(f"发送异常: {e}")
```

---

## 注意事项

1. 所有 API 都是异步函数，必须使用 `await` 调用
2. wxid 格式：个人为 `wxid_xxx`，群聊为 `xxx@chatroom`
3. 文件路径建议使用绝对路径
4. 部分 API 需要特定权限（如群主才能踢人）
5. API 调用频率不宜过高，避免风控