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

// 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 to maintain context. For notifying specific users, use mentions in your message content.