botrs 0.13.0

A Rust QQ Bot framework based on QQ Guild Bot API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# Messages

Message data structures for the QQ Guild Bot API. The framework distinguishes incoming events (gateway payloads) from outgoing parameter objects.

## Incoming messages

### `Message`

Guild channel messages, including @-mentions.

```rust
pub struct Message {
    pub id: Option<Snowflake>,
    pub content: Option<String>,
    pub channel_id: Option<Snowflake>,
    pub guild_id: Option<Snowflake>,
    pub group_id: Option<Snowflake>,
    pub author: Option<MessageUser>,
    pub member: Option<MessageMember>,
    pub message_reference: Option<MessageReference>,
    pub mentions: Vec<MessageUser>,
    pub attachments: Vec<MessageAttachment>,
    pub embeds: Vec<Embed>,
    pub ark: Option<Ark>,
    pub direct_message: Option<bool>,
    pub seq: Option<u64>,
    pub seq_in_channel: Option<String>,
    pub timestamp: Option<Timestamp>,
    pub edited_timestamp: Option<Timestamp>,
    pub mention_everyone: Option<bool>,
    pub src_guild_id: Option<Snowflake>,
    pub file_info: Option<String>,
    pub ttl: Option<u32>,
    pub message_scene: Option<MessageScene>,
    pub event_id: Option<String>,
}
```

Most string fields use `Option<Snowflake>` because the QQ Open API may omit them on partial payloads. Convenience methods on `Message`:

- `reply(api, token, content)` — text reply that sets `msg_id` for passive routing.

Inspect fields such as `author.bot`, `content`, `attachments`, and `mentions` directly for message predicates.

### `GroupMessage` and `C2CMessage`

Group messages (group `@bot`) and C2C (private/direct) messages share a similar shape but use OpenID-based identification:

```rust
pub struct GroupMessage {
    pub id: Option<Snowflake>,
    pub content: Option<String>,
    pub message_reference: Option<MessageReference>,
    pub mentions: Vec<GroupMessageUser>,
    pub attachments: Vec<MessageAttachment>,
    pub msg_seq: Option<u64>,
    pub timestamp: Option<Timestamp>,
    pub author: Option<GroupMessageUser>,
    pub group_openid: Option<String>,
    pub event_id: Option<String>,
}
```

`C2CMessage` is structurally identical except its `author`/`mentions` use `C2CMessageUser`.

### `DirectMessage`

`DirectMessage` is the **session** record returned by the direct-message creation API — not the gateway message. Direct-message gateway events use `Message` with `direct_message: Some(true)`.

```rust
pub struct DirectMessage {
    pub guild_id: Snowflake,
    pub channel_id: Snowflake,
    pub create_time: String,
}
```

## Outgoing parameters

Send-side payloads use builder structs to avoid the long `Option<...>` argument lists of older APIs:

| Struct                  | Used by                                    |
|-------------------------|--------------------------------------------|
| `MessageParams`         | `BotApi::send_message`         |
| `DirectMessageParams`   | `BotApi::send_direct_message`  |
| `GroupMessageParams`    | `BotApi::send_group_message`   |
| `C2CMessageParams`      | `BotApi::send_c2c_message`     |

Each exposes `new_text(content)` and reply/file helpers where they apply. For embed, markdown, ark, keyboard, media, and other optional payloads, set the corresponding field on the params struct and pass it to the matching send method.

```rust
let params = MessageParams::new_text("Pong!").with_reply(message_id);
api.send_message(&channel_id, params).await?;
```

## Supporting types

| Type                | Purpose                                              |
|---------------------|------------------------------------------------------|
| `Embed`             | Embed body (title, description, fields, thumbnail).  |
| `Ark`               | Ark template payload (`template_id` + `kv` array).   |
| `MarkdownPayload`   | Markdown send body (template id, content, params).   |
| `Keyboard`          | Inline keyboard (rows of buttons).                   |
| `MessageReference`  | `{ message_id, ignore_get_message_error }`.          |
| `MessageAttachment` | File attachment metadata (URL, filename, size, …).   |
| `MessageAudit`      | Audit-result payload from the audit gateway events.  |
| `MessageDelete`     | Delete-event payload with `message` and `op_user`.   |
| `MessageScene`      | Scene marker (group, c2c, channel) on inbound events.|

## Message author types

See [Users and Members](./users-members.md#message-author-types) for `MessageUser`, `DirectMessageUser`, `GroupMessageUser`, and `C2CMessageUser`.

## See also

- [Messages guide](../../guide/messages.md) — task-oriented usage.
- [Bot API](../bot-api.md) — every message route.
- [Other types](./other-types.md) — embeds, keyboards, ark, attachments.