Rocket.Chat User Guide

Rocket.Chat is an open-source, self-hostable communications platform for team chat, customer engagement, and secure collaboration. This guide shows you how to get into a workspace and use every part of the product — messaging, channels, teams, threads, search, calls, file sharing, apps, and the omnichannel (Live Chat) agent experience.

Note

Rocket.Chat is built in TypeScript on the Meteor framework with a React web client. It runs as a self-hosted server, in Rocket.Chat Cloud, or air-gapped. This guide focuses on using a workspace. For installing the server, scaling it, configuring authentication, and tuning settings, see the companion Rocket.Chat Admin Guide.

Table of Contents

1. What Rocket.Chat Is
2. Quick Start
3. Getting Access: Web, Desktop, and Mobile
4. The Interface at a Glance
5. Rooms: Channels, Private Groups, DMs, Discussions, and Teams
6. Sending and Formatting Messages
7. Message Actions
8. Threads
9. Mentions and Notifications
10. Search
11. Files, Media, and Emoji
12. Slash Commands Reference
13. Voice and Video Calls
14. Your Account and Preferences
15. Security: 2FA and End-to-End Encryption
16. Apps, Integrations, and Bots
17. Federation
18. Omnichannel (Live Chat) for Agents
19. Troubleshooting
20. FAQ
21. Reference Tables

1. What Rocket.Chat Is

Rocket.Chat is a team communications platform — a self-hosted alternative to closed SaaS chat tools. A single workspace gives you:

• Real-time messaging in public channels, private groups, and direct messages.
• Teams that group related channels under shared membership.
• Threads for focused side-conversations.
• Voice and video calls, including conferencing and screen sharing.
• File sharing with drag-and-drop uploads and inline media previews.
• Search across messages and rooms, including full-text and regex search.
• Apps and integrations from the Rocket.Chat Marketplace, plus incoming/outgoing webhooks and bots.
• Omnichannel customer engagement (Live Chat), letting agents handle external visitors inside the same client.
• Federation, so users on separate Rocket.Chat or Matrix servers can talk to each other.

Tip

Everything you do happens inside a workspace — one Rocket.Chat server with its own users, channels, and settings. Your administrator controls which features (registration, encryption, calling, federation, apps) are turned on, so some capabilities in this guide may be disabled in your workspace.

Rocket.Chat ships as Community Edition (CE), licensed MIT, plus Enterprise Edition (EE) features that unlock with a license key. Features such as advanced Omnichannel routing, attribute-based access control, and the microservices deployment are EE; the core chat experience is fully open source.

2. Quick Start

This is the fastest path from zero to chatting, assuming someone has given you a workspace URL (for example https://chat.example.com).

1. Open the workspace in your browser, or install the desktop/mobile app and enter the workspace URL.
2. Register or sign in. Depending on your workspace, you'll either create an account with email + password, register through a secret invite URL, or sign in with SSO (Google, GitHub, SAML, LDAP, etc.).
3. Verify your email if your workspace requires it (check your inbox for a verification link).
4. Set your display name and avatar — click your avatar (top-left) → My Account → Profile.
5. Find a channel. Click the Search icon at the top of the sidebar, type a channel name (try general), and open it.
6. Send your first message. Type in the composer at the bottom and press Enter.
7. Set your status. Click your avatar → choose Online, Away, Busy, or Offline.

Tip

Press the Search shortcut (the magnifying glass in the sidebar header) to jump to any channel or person instantly — it's the quickest way to navigate.

You're now live. The rest of this guide covers everything in depth.

3. Getting Access: Web, Desktop, and Mobile

Rocket.Chat meets you wherever you work.

Web app

The web app is the full client and requires no installation. Open your workspace URL in any modern browser (Chrome, Firefox, Edge, Safari). The web app supports the complete feature set described in this guide.

Desktop app

The desktop app wraps the web client and adds native notifications, multi-server switching, and a system-tray presence indicator.

macOS

Install from the Mac App Store, then add your server URL on first launch.

Windows

Install from the Microsoft Store, then add your server URL.

Linux

Install via Snap:

sudo snap install rocketchat-desktop

After launch, add a server by entering its workspace URL. You can connect to multiple servers and switch between them from the left rail.

Mobile apps

Download the native mobile app for on-the-go messaging and push notifications:

• iOS — Rocket.Chat on the App Store
• Android — Rocket.Chat on Google Play

On first run, enter your workspace URL, then sign in. Push notifications are delivered through your workspace's configured gateway.

Note

Mobile push notifications require the administrator to have push enabled. If you don't receive push notifications, ask your admin whether the Push gateway is configured for your workspace.

4. The Interface at a Glance

The web and desktop clients share the same layout:

The sidebar grouping and sort order are configurable in your preferences (see Your Account and Preferences). By default rooms are grouped by type and sorted by recent activity.

Tip

The contextual bar is your friend. Almost every "show me more about this room" action — members, files, pinned messages, threads, settings — opens there rather than navigating away from the conversation.

5. Rooms: Channels, Private Groups, DMs, Discussions, and Teams

Every conversation in Rocket.Chat lives in a room. There are several room types, each with different visibility and membership rules.

Room types

Creating a room

Click the pencil / "Create new" icon in the sidebar header and choose:

• Channel — give it a name, choose Private or Public, optionally add members and set it Encrypted, Read Only, or Broadcast.
• Direct Message — pick one or more people.
• Discussion — choose a parent channel, name the discussion, and optionally seed it with a first message.
• Team — name it and add members; the team gets a "main" channel and can own additional channels.

Note

Whether you can create channels, teams, or discussions depends on permissions your admin assigns to your role. By default the user role can create public channels (create-c), private groups (create-p), direct messages (create-d), teams (create-team), and discussions (start-discussion).

Channels in depth

A channel is the standard group room. Channel options (from the kebab menu / room admin):

• Topic / Announcement / Description — short context shown in the header and info panel.
• Read Only — only owners/moderators (and roles with post-readonly) can post; everyone else reads.
• Broadcast — like read-only, but replies are routed back to the broadcaster privately.
• Encrypted — turns on end-to-end encryption for the room (see Security).
• Join Code — a password required to join a public channel.
• Archive — freeze a channel (no new messages) while preserving history.

Teams

A Team groups people and channels. Members of a team share visibility into the team's channels, and you can move existing channels into a team or create new channels owned by it. Teams are ideal when a group of people collaborate across many related rooms — instead of inviting everyone to each channel, you manage membership once at the team level.

Team actions include creating team channels (create-team-channel), adding/removing members, converting a channel to a team, and converting a team back to a channel — subject to your role's permissions.

Discussions

A Discussion is a child room created from a parent channel to keep a side-topic from cluttering the main conversation. It has its own membership and message history but stays linked to its parent so people can find it. Start one from the + / plus menu in the composer or the room kebab menu → Discussions.

Favorites

Star a room (the star icon in the room header) to pin it to the Favorites section at the top of your sidebar. Favorites are personal — only you see them.

6. Sending and Formatting Messages

Type in the composer at the bottom of a room and press Enter to send. The send behavior is configurable (see preferences): by default Enter sends and Shift+Enter inserts a newline.

Markdown formatting

Rocket.Chat renders a rich subset of Markdown:

Additional rich rendering supported by the message parser:

• Emoji via :shortcode: (e.g. :smile:) and ASCII emoji auto-conversion (e.g. :-)), both toggleable in your preferences.
• Mentions with @username, plus @all and @here (see Mentions).
• Channel links with #channel-name.
• Math rendering via KaTeX (if enabled by your admin): inline and block TeX math.
• Link previews (oEmbed) and embedded media for supported URLs (videos, images), which you can collapse.

Tip

Press the up arrow in an empty composer to edit your last message — a fast way to fix a typo without reaching for the mouse.

The composer toolbar

The composer offers quick actions: emoji picker, file upload, audio/video message recording, and the + actions menu (create discussion, share location, and app-provided actions). Available actions depend on which features and apps your admin has enabled.

7. Message Actions

Hover over any message (or long-press on mobile) to reveal the message action toolbar. Available actions depend on your role and the room:

Note

Whether you can edit or delete your own messages, and for how long after posting, is governed by admin settings and permissions. Some workspaces keep an edit history and show an "edited" indicator; others may disable editing entirely.

Starred and Pinned messages

• Starred messages are personal bookmarks. Open the room kebab menu → Starred Messages to review them.
• Pinned messages are visible to everyone in the room. Open the kebab menu → Pinned Messages. Pinning requires the pin-message permission.

8. Threads

Threads keep focused replies attached to a specific message instead of scrolling the main timeline.

• Start a thread: hover a message → Reply in Thread, then type your reply. The original message becomes the thread's root.
• Open the threads list: click the Threads icon in the room header to see all active threads.
• Also send to channel: when replying in a thread, you can optionally mirror the reply into the main channel. Your default for this is configurable (Selected first reply, unselected following replies, Selected by default, or Unselected by default).
• Unread threads: a room stays unread while it has unread thread replies, even if the main timeline is read.

Tip

If you prefer to see thread replies inline with the main conversation, enable Always show thread replies in main channel in your account preferences.

9. Mentions and Notifications

Mentions

• @username notifies a specific person.
• @here notifies everyone currently online in the room.
• @all notifies every member of the room.

Using @all and @here requires the mention-all / mention-here permissions (granted by default to admins, owners, moderators, and regular users). Admins can cap how many users @all/@here may notify to prevent noise in large rooms.

Notification channels

Rocket.Chat can notify you four ways:

Per-room notification preferences

Open a room's kebab menu → Notification Preferences to override defaults for that room: turn desktop/mobile/email alerts on or off, choose All messages / Mentions / Nothing, pick alert sounds, and mute the room entirely.

Default notification behavior

Your workspace ships sensible defaults (configurable by your admin and overridable per-user in preferences):

• Desktop: all messages
• Push (mobile): all messages
• Email notification mode: mentions only
• Auto-away after an idle period (default 5 minutes)

Tip

Use Mute Focused Conversations (on by default) so you don't get a notification sound for the room you're actively looking at.

10. Search

Rocket.Chat offers two kinds of search:

Spotlight / global search

Click the Search icon in the sidebar header to jump to any room or person by name. This is navigation, not message search — start typing and select a result to open it.

Message search (within a room)

Click the search-in-room (magnifier) icon in the room header to search messages in the current room. Depending on your workspace's search provider, you can use:

• Full-text search across message content.
• Regex search for pattern matching (if enabled by your admin).

Note

Message search capabilities depend on the search provider your administrator configured. The default provider indexes message text; some advanced providers add cross-room search and ranking.

11. Files, Media, and Emoji

Uploading files

• Drag and drop a file onto a room, or click the upload icon in the composer.
• Add an optional description and confirm in the upload dialog.
• Images, audio, and video render inline with previews; other file types show as download cards.

The maximum file size and allowed file types are set by your admin. Uploaded files are stored in the workspace's configured backend (GridFS, filesystem, Amazon S3, Google Cloud Storage, or WebDAV) — transparent to you as a user.

Room files

Open the room kebab menu → Files to browse everything shared in that room, filter by type, and download.

Audio and video messages

The composer can record short audio and video messages directly, if your admin has enabled them. Click the microphone/camera icons in the composer toolbar, record, and send.

Emoji and reactions

• Emoji picker: click the emoji icon in the composer, or type : followed by a shortcode.
• Custom emoji: your workspace may include custom emoji uploaded by admins.
• Reactions: hover a message → React to add an emoji reaction. Reactions are a lightweight way to acknowledge without posting.

12. Slash Commands Reference

Type / at the start of the composer to run a slash command. The following commands ship with Rocket.Chat (your workspace may add more via apps):

Note

Slash commands respect permissions. For example, /kick, /ban, and /mute require moderation permissions in the room; /archive requires archive-room. If a command does nothing, you may lack the permission for it.

Tip

Start typing / and Rocket.Chat autocompletes available commands with their descriptions — you don't have to memorize this table.

13. Voice and Video Calls

Rocket.Chat supports real-time calling. Exactly which options you see depends on what your admin enabled.

Video conferencing

Start a conference from a room's header call button or the + menu. Rocket.Chat integrates with video providers (such as Jitsi or the Rocket.Chat conferencing app); participants join from the room, and conferences support screen sharing. You can ring other users to invite them into a call (videoconf-ring-users permission). Mobile users can receive ringing if VideoConf Mobile Ringing is enabled.

Voice calls

Workspaces with voice calling enabled allow internal voice calls between users (allow-internal-voice-calls) and, where configured, external calls (allow-external-voice-calls). A call widget shows call state, and you can adjust your ringer volume in preferences.

Note

Voice/video features rely on WebRTC and a signaling service that your admin configures. If call buttons are missing, calling is not enabled in your workspace.

14. Your Account and Preferences

Open your avatar (top-left) → My Account to manage your identity and tune the client.

Profile

• Name, username, and avatar — change these if your admin allows (Accounts_AllowRealNameChange, Accounts_AllowUsernameChange, Accounts_AllowUserAvatarChange). Avatars can be uploaded, set from a URL, or pulled from a provider.
• Status message and status (Online / Away / Busy / Offline). An Invisible option may be available.
• Email and password — change them if permitted; password changes are subject to the workspace password policy.
• Bio and nickname.

Preferences

The Preferences tab controls how the client behaves. Highlights:

Personal Access Tokens

Under My Account → Personal Access Tokens, you can generate tokens to authenticate with the REST API as yourself (requires the create-personal-access-tokens permission). Treat these like passwords. See the Admin Guide for API usage.

Accessibility

An Accessibility section lets you tune the experience (e.g. font and motion preferences) for comfortable use.

15. Security: 2FA and End-to-End Encryption

Two-Factor Authentication (2FA)

If your workspace has 2FA enabled, secure your account under My Account → Security → Two-Factor Authentication:

• TOTP — scan the QR code with an authenticator app (Google Authenticator, Authy, etc.) and enter the 6-digit code. Save your backup codes.
• Email 2FA — receive a one-time code by email when you log in (if enabled).

After enabling, you'll be prompted for a second factor on sign-in and for sensitive actions.

Important

Store your TOTP backup codes somewhere safe. If you lose your authenticator and your codes, an administrator may need to reset 2FA on your account.

End-to-End Encryption (E2EE)

When E2EE is enabled in your workspace, channels, private groups, and DMs can be encrypted so only participants can read the content — not even the server can.

1. On first use you'll be asked to set an encryption password that protects your private key.
2. Mark a room Encrypted (room admin / creation) — the lock indicator appears.
3. To read encrypted history on a new device, enter your encryption password to unlock your key.

Caution

If you forget your E2EE encryption password and have no other logged-in session to re-key from, you may permanently lose access to encrypted message history. Keep it safe.

Encrypted rooms also support encrypting file uploads and mentions, depending on workspace settings.

16. Apps, Integrations, and Bots

The Marketplace

Open Apps from the admin area (or your avatar menu, if you have access-marketplace) to browse the Rocket.Chat Marketplace. Apps extend the workspace with new slash commands, message actions, bots, and integrations with external services. Installing apps requires the manage-apps permission (usually admins).

Webhooks and integrations

Rocket.Chat supports:

• Incoming webhooks — external systems post messages into a room via a URL.
• Outgoing webhooks — Rocket.Chat calls an external URL when messages match a trigger (e.g. a keyword or a command).
• Slack-compatible webhook payloads, easing migration from Slack.

You can manage your own integrations if granted manage-own-incoming-integrations / manage-own-outgoing-integrations.

Bots

Bots are automated users. Rocket.Chat works with Hubot (via the Rocket.Chat adapter) and bots built on the Apps-Engine. Bots can post messages, respond to commands, and react — and have their own permission set (bot, app roles).

Slack Bridge

If your admin configured the Slack Bridge, messages, edits, and reactions sync bi-directionally between a Slack workspace and yours — useful during a migration or for connecting two communities.

17. Federation

Federation lets you talk to users who live on a different server.

• Matrix federation connects your workspace to the broader Matrix network. A federated user is addressed like @user:their-server.org. You can add them to rooms and DM them as if they were local (subject to access-federation).
• Rocket.Chat-to-Rocket.Chat federation connects two Rocket.Chat workspaces.

When federation is enabled, search and invites accept remote handles. Federated users carry a federated-external role with a tailored permission set.

Note

Federation must be enabled and configured by your administrator. If you can't find a remote user, federation may be off, or that server may not be reachable from yours.

18. Omnichannel (Live Chat) for Agents

Omnichannel turns Rocket.Chat into a customer-engagement console. External visitors start conversations from a website Live Chat widget (or SMS, email, and other channels), and agents handle them inside the normal Rocket.Chat client. This section is for users with an agent or manager role.

Roles

Handling a conversation

1. Incoming chats appear in your sidebar's Omnichannel section and the queue.
2. Take a chat (or it's routed to you automatically, depending on the routing method).
3. Respond as you would in any room. Use canned responses for common replies.
4. Transfer to another agent or department if needed (transfer-livechat-guest).
5. Put on hold if you're waiting on the customer (on-hold-livechat-room).
6. Close the chat with a closing comment; optionally send the visitor a transcript (send-omnichannel-chat-transcript, including PDF export).

Contacts and history

Omnichannel maintains a contact center with visitor profiles and conversation history, so you can see a customer's past interactions and custom fields (view-livechat-contact, view-livechat-contact-history).

Business hours and triggers

Managers configure business hours (when agents are available and how off-hours chats are handled) and triggers (automated proactive messages based on visitor behavior). Agents simply see the effects: chats route to on-duty agents, and triggered greetings fire automatically.

Tip

Set yourself available for Omnichannel (a toggle in the Omnichannel section) when you start your shift, or chats won't route to you.

19. Troubleshooting

Common issues and exact fixes. Format: symptom → cause → solution.

Error: error-invalid-user / can't sign in

Cause: Wrong credentials, an unverified email, or an account pending admin approval.

Solution: Confirm your username/email and password. If your workspace requires email verification, click the link in your verification email. If registration uses manual approval, wait for an admin to approve your account. Use Forgot Password to reset if password reset is enabled.

"This room does not exist" / error-room-does-not-exist

Cause: The room was deleted or archived, or you followed a stale link.

Solution: Search for the room again. If it was archived, an admin/owner can unarchive it. If it was private and you were removed, you'll need a new invite.

"Not allowed" / error-not-allowed

Cause: Your role lacks the permission for that action (e.g. deleting someone else's message, kicking a user, pinning).

Solution: Ask a room owner/moderator or workspace admin. Permissions are role-based (see Reference Tables).

error-invalid-subscription when marking read

Cause: You're not (or no longer) a member of the room you tried to mark read.

Solution: Rejoin or reopen the room from search.

I'm not getting notifications

Cause: Notifications muted at the room or account level, "Mute Focused Conversations" hiding alerts for the active room, or push not configured.

Solution: Check Notification Preferences on the room and your account Preferences → Notifications. For mobile push, confirm with your admin that a push gateway is configured.

Messages won't send / I see a connection warning

Cause: Lost connection to the server (DDP websocket dropped), or the server is restarting.

Solution: Wait for the connection status banner to clear; Rocket.Chat reconnects automatically and re-sends queued messages. If it persists, reload the page or check the workspace URL with your admin.

I can't read an encrypted room

Cause: Your E2EE key isn't unlocked on this device.

Solution: Enter your encryption password when prompted to decrypt. If you've forgotten it, see the E2EE warning.

A file won't upload

Cause: The file exceeds the workspace size limit, or its type is blocked.

Solution: Compress or convert the file, or ask your admin about the allowed size/type limits.

@all / @here did nothing

Cause: You lack mention-all / mention-here, or the room exceeds the admin's broadcast cap.

Solution: Ask a moderator to broadcast, or notify people individually.

Login keeps logging me out

Cause: Login expiration, "Forget user session on window close," or a limit on simultaneous sessions.

Solution: This is governed by admin account settings. If it's disruptive, ask your admin to review login-expiration settings.

20. FAQ

Q: Is Rocket.Chat free? The core platform (Community Edition) is open source under the MIT license and free to self-host. Some advanced features require an Enterprise license; your workspace owner decides what's enabled.

Q: How do I change my display name or avatar? My Account → Profile. If the fields are locked, your admin has disabled self-service changes for those fields.

Q: What's the difference between a channel and a team? A channel is one room. A team groups people and owns multiple channels with shared membership — use a team when many people collaborate across several related channels.

Q: What's the difference between a thread and a discussion? A thread is replies attached to one message inside the same room. A discussion is a whole separate room spun off a parent channel, with its own membership and history.

Q: Who can see a private group? Only invited members. Private groups are not discoverable in search by non-members.

Q: Can I message someone on another company's Rocket.Chat? Yes, if both workspaces have federation enabled. Address them by their federated handle (e.g. @user:server.org).

Q: How do I star vs. pin a message? Star is a private bookmark only you see. Pin makes a message prominent for everyone in the room (requires permission).

Q: Can I edit or delete a message after sending? Usually yes, within limits your admin sets. Hover the message → Edit / Delete. Some workspaces keep an edit history or restrict the time window.

Q: How do I stop a noisy channel from notifying me? Open the room → Notification Preferences → set alerts to Mentions or Nothing, or mute the room. You can also /hide it from your sidebar.

Q: How do I use the REST API as myself? Generate a Personal Access Token under My Account, then authenticate API requests with your X-User-Id and X-Auth-Token. See the Admin Guide's API section.

Q: What languages does the interface support? More than 30. Change it under Preferences → Language.

Q: Where are my files stored? In whatever backend your admin configured (GridFS, filesystem, S3, Google Cloud Storage, or WebDAV). As a user you just upload and download — the location is transparent.

Q: How do I become available for customer (Omnichannel) chats? You need an agent role; then toggle yourself available in the Omnichannel section of the sidebar.

21. Reference Tables

Built-in roles

Common permissions (selected)

Note

Your administrator can change which roles hold which permissions, so the defaults above may differ in your workspace.

Useful keyboard actions