---
path: app-docs/develop/server/community-api/messaging/overview.md
audience: app
category: guide
summary: Send messages to channels, respond to user activity, and manage message features like reactions and pins.
---

# Channel messages

Send messages to channels, respond to user activity, and manage message features like reactions and pins.

## What are channel messages?

A *channel message* is a piece of content posted to a text channel. Messages are the primary way users communicate within a community.

Each message contains:

- **Content**: Text with optional mentions (users, roles, channels)
- **Attachments**: Files uploaded through the asset system
- **Metadata**: Author, timestamps, edit history, pin status
- **Reactions**: Emoji responses from users
- **Parent references**: Links to messages this one replies to

```ts
// ChannelMessage structure
{
  id: MessageGuid,
  channelId: ChannelGuid,
  userId: UserGuid,
  messageContent: string,
  messageType: MessageType,
  messageUris?: MessageUri[],      // Attachments
  reactions?: MessageReaction[],
  parentMessages?: ParentMessage[],
  editedAt?: Date,
  pinnedAt?: Date,
  deletedAt?: Date
}
```

### Message types

Every message has a `messageType` property indicating its origin:

| Type | Value | Description |
|------|-------|-------------|
| `UserMessage` | 1 | Created by a user or server code |
| `System` | 2 | Generated by the system (joins, channel updates) |

Check this property when processing messages to distinguish between user-generated content and system notifications. For example, a command handler should only respond to `UserMessage` types to avoid processing system announcements as commands.

## How channel messages work

Understanding message flow helps you design responsive integrations that react naturally to user activity.

### Message lifecycle

1. **Create**: User or server code posts a message to a channel
2. **Distribute**: Server broadcasts `channelMessage.created` to all connected clients with channel access
3. **Interact**: Users add reactions, pin, or reply
4. **Edit** (optional): Author modifies content; server broadcasts `channelMessage.edited`
5. **Delete** (optional): Author or moderator removes; server broadcasts `channelMessage.deleted`

When you subscribe to message events, you receive notifications for all messages in channels you can access, regardless of who sent them. This lets you react to user activity, moderate content, or aggregate data.

### Pagination model

The `list` method retrieves messages using timestamp-based pagination rather than page numbers. This approach handles the continuously-updating nature of chat, where new messages arrive while you're fetching older ones.

To paginate, provide a `timestamp` and `direction` in your `ChannelMessageListRequest`:

| Direction | Behavior | Use case |
|-----------|----------|----------|
| `Older` | Messages before the timestamp | Scrolling up through history |
| `Newer` | Messages after the timestamp | Catching up after reconnect |
| `Both` | Messages in both directions | Initial channel load |

The response includes `oldCount` and `newCount` indicating how many more messages exist in each direction. When these values are greater than zero, you can make additional requests to fetch more messages.

The `get` method retrieves a single message by ID and does not use pagination.

### Reference resolution

Message content can include mentions using URI syntax (e.g., `root://user/{userId}`). When you retrieve messages, the `referenceMaps` property provides resolved display names for all referenced entities, so you don't need additional API calls.

### Content flagging

The `flag` method reports a message to Root's moderation system. Use this when your code detects content that violates community guidelines or platform policies.

When flagging, specify a `ContentFlagReason`:

| Reason | Description |
|--------|-------------|
| `Spam` | Spam or unsolicited content |
| `Hatespeech` | Hate speech or discriminatory content |
| `Violence` | Violent or threatening content |
| `Harassment` | Harassment or bullying |
| `Sexualcontent` | Sexual or explicit content |
| `Misinformation` | False or misleading information |
| `Impersonation` | Impersonating another person or entity |
| `Copyright` | Copyright infringement |
| `Dmca` | DMCA takedown request |
| `Objectionable` | Generally objectionable content |
| `Other` | Other reason not covered above |

Flagging does not automatically remove the message. Root's moderation team reviews flagged content and takes appropriate action based on platform policies.

## When to use channel messages

- **Respond to commands**: Listen for `channelMessage.created` events, parse content for command prefixes, and reply with results
- **Moderate content**: Monitor messages for policy violations and use `flag` to report or `delete` to remove
- **Aggregate activity**: Track message volume, popular reactions, or active hours for analytics
- **Broadcast announcements**: Post scheduled messages to announcement channels
- **Provide feedback**: Use typing indicators to show users that their request is being processed

For building conversational flows, combine message events with [replies](replies.md) to maintain context. For notifying specific users, use [mentions](../mentions/overview.md) in your message content.