# 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.
- `is_from_bot()`, `has_content()`, `has_attachments()`, `has_mentions()` — quick 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: Option<Snowflake>,
    pub channel_id: Option<Snowflake>,
    pub create_time: Option<String>,
}
```

`DirectMessageSession` is a type alias of `DirectMessage`.

## Outgoing parameters

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

| Struct                  | Used by                                    |
|-------------------------|--------------------------------------------|
| `MessageParams`         | `BotApi::post_message_with_params`         |
| `DirectMessageParams`   | `BotApi::post_direct_message_with_params`  |
| `GroupMessageParams`    | `BotApi::post_group_message_with_params`   |
| `C2CMessageParams`      | `BotApi::post_c2c_message_with_params`     |

Each exposes `new_text(content)`, `new_embed(embed)`, `new_markdown(...)`, etc., plus chainable setters such as `with_reply(message_id)`, `with_keyboard(keyboard)`, `with_file_image(bytes)`. Pass them to the matching `post_*_with_params` method.

```rust
let params = MessageParams::new_text("Pong!").with_reply(message_id);
api.post_message_with_params(&token, &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).   |
| `MessageKeyboard`   | 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 `post_*_with_params` route.
- [Other types](./other-types.md) — embeds, keyboards, ark, attachments.
