129 lines
3.3 KiB
Markdown
129 lines
3.3 KiB
Markdown
# 消息发送API使用说明
|
||
|
||
## 概述
|
||
|
||
新的消息发送API允许插件直接向指定的平台和ID发送消息，无需依赖当前聊天上下文。API会自动从数据库中匹配chat_stream并构建相应的发送消息对象。
|
||
|
||
## 可用方法
|
||
|
||
### 1. `send_message_to_target()`
|
||
|
||
最通用的消息发送方法，支持各种类型的消息。
|
||
|
||
```python
|
||
async def send_message_to_target(
|
||
self,
|
||
message_type: str, # 消息类型：text, image, emoji等
|
||
content: str, # 消息内容
|
||
platform: str, # 目标平台：qq等
|
||
target_id: str, # 目标ID（群ID或用户ID）
|
||
is_group: bool = True, # 是否为群聊
|
||
display_message: str = "", # 显示消息（可选）
|
||
) -> bool:
|
||
```
|
||
|
||
**示例用法：**
|
||
```python
|
||
# 发送文本消息到群聊
|
||
success = await self.send_message_to_target(
|
||
message_type="text",
|
||
content="Hello, 这是一条测试消息！",
|
||
platform="qq",
|
||
target_id="123456789",
|
||
is_group=True
|
||
)
|
||
|
||
# 发送图片到私聊
|
||
success = await self.send_message_to_target(
|
||
message_type="image",
|
||
content="https://example.com/image.jpg",
|
||
platform="qq",
|
||
target_id="987654321",
|
||
is_group=False
|
||
)
|
||
|
||
# 发送表情包
|
||
success = await self.send_message_to_target(
|
||
message_type="emoji",
|
||
content="😄",
|
||
platform="qq",
|
||
target_id="123456789",
|
||
is_group=True
|
||
)
|
||
```
|
||
|
||
### 2. `send_text_to_group()`
|
||
|
||
便捷方法，专门用于向群聊发送文本消息。
|
||
|
||
```python
|
||
async def send_text_to_group(
|
||
self,
|
||
text: str, # 文本内容
|
||
group_id: str, # 群聊ID
|
||
platform: str = "qq" # 平台，默认为qq
|
||
) -> bool:
|
||
```
|
||
|
||
**示例用法：**
|
||
```python
|
||
success = await self.send_text_to_group(
|
||
text="群聊测试消息",
|
||
group_id="123456789"
|
||
)
|
||
```
|
||
|
||
### 3. `send_text_to_user()`
|
||
|
||
便捷方法，专门用于向用户发送私聊文本消息。
|
||
|
||
```python
|
||
async def send_text_to_user(
|
||
self,
|
||
text: str, # 文本内容
|
||
user_id: str, # 用户ID
|
||
platform: str = "qq" # 平台，默认为qq
|
||
) -> bool:
|
||
```
|
||
|
||
**示例用法：**
|
||
```python
|
||
success = await self.send_text_to_user(
|
||
text="私聊测试消息",
|
||
user_id="987654321"
|
||
)
|
||
```
|
||
|
||
## 支持的消息类型
|
||
|
||
- `"text"` - 文本消息
|
||
- `"image"` - 图片消息（需要提供图片URL或路径）
|
||
- `"emoji"` - 表情消息
|
||
- `"voice"` - 语音消息
|
||
- `"video"` - 视频消息
|
||
- 其他类型根据平台支持情况
|
||
|
||
## 注意事项
|
||
|
||
1. **前提条件**：目标群聊或用户必须已经在数据库中存在对应的chat_stream记录
|
||
2. **权限要求**：机器人必须在目标群聊中有发言权限
|
||
3. **错误处理**：所有方法都会返回bool值表示发送成功与否，同时会在日志中记录详细错误信息
|
||
4. **异步调用**：所有方法都是异步的，需要使用`await`调用
|
||
|
||
## 完整示例插件
|
||
|
||
参考 `example_send_message_plugin.py` 文件，该文件展示了如何在插件中使用新的消息发送API。
|
||
|
||
## 配置文件支持
|
||
|
||
可以通过TOML配置文件管理目标ID、默认平台等设置。参考 `example_config.toml` 文件。
|
||
|
||
## 错误排查
|
||
|
||
如果消息发送失败，请检查：
|
||
|
||
1. 目标ID是否正确
|
||
2. chat_stream是否已加载到ChatManager中
|
||
3. 机器人是否有相应权限
|
||
4. 网络连接是否正常
|
||
5. 查看日志中的详细错误信息 |