Chat - Brainbox

Brainbox includes real-time chat functionality for team communication. Create channels for group discussions or send direct messages to individuals.

Chat Types

Brainbox supports two types of chat conversations:

Channels

Group conversations for teams and projects. Public or private with configurable membership.

Direct Messages

One-on-one conversations between workspace members, including self-chat for personal notes.

Channels

Channels are persistent chat rooms for team discussions:

Creating Channels

Open channels sidebar

Click the Channels section in your workspace sidebar.

Create new channel

Click the + button next to Channels.

Configure channel

Name - Channel identifier (e.g., “general”, “project-alpha”)
Visibility - Public (all members can join) or Private (invite-only)
Collaborators - Initial channel members and their roles

Start chatting

Send your first message to kick off the conversation.

Channel Structure

{
  type: "channel",
  name: "project-alpha",
  avatar: "🚀",
  parentId: "space_xyz",
  visibility: "public" | "private",
  collaborators: {
    "user_abc": "admin",
    "user_def": "member",
    "user_ghi": "viewer"
  }
}

Channel Permissions

Channels have role-based access control:

Role	View	Send Messages	Add Members	Edit Channel	Delete
Admin	✓	✓	✓	✓	✓
Member	✓	✓	✗	✗	✗
Viewer	✓	✓	✗	✗	✗

Channel admins can modify collaborators, rename the channel, and delete it. Members and viewers can view and send messages but cannot manage the channel.

Public vs Private Channels

Public Channels
Private Channels

Public channels are visible to all workspace members:

Appear in the channels list for everyone
Any member can join without invitation
Great for company-wide announcements, general chat, or open discussions

Public channels still require workspace membership to access. They are not publicly accessible outside your workspace.

Direct Messages

Direct messages (DMs) are private 1-on-1 conversations:

Starting a DM

Find a user

Click the Direct Messages section in the sidebar.

Start conversation

Select a user from your workspace to begin chatting.

Self-chat

You can also message yourself for personal notes and reminders.

DM Structure

{
  type: "chat",
  collaborators: {
    "user_abc": "admin",
    "user_def": "admin"  // Both users have equal permissions
  }
}

Direct messages support 1 or 2 collaborators. Single collaborator creates a self-chat, while two collaborators create a standard DM.

Messages

Messages are the core content units in channels and DMs:

Message Types

Standard Messages
Questions
Answers

Regular text messages with optional formatting and attachments.

{
  type: "message",
  subtype: "standard",
  parentId: "channel_abc",
  content: {
    "block_1": {
      id: "block_1",
      type: "paragraph",
      content: [{ type: "text", text: "Hello team!" }],
      index: "a0"
    }
  }
}

Messages marked as questions for Q&A threads.

{
  type: "message",
  subtype: "question",
  content: { /* blocks */ }
}

Questions can have linked answer messages for structured knowledge sharing.

Responses to question messages.

{
  type: "message",
  subtype: "answer",
  referenceId: "message_question_xyz",
  content: { /* blocks */ }
}

Message Content

Messages support rich content with blocks:

Text

Formatted text with bold, italic, code, and links

Code Blocks

Syntax-highlighted code snippets

Lists

Ordered and unordered lists

Mentions

@mention other users to notify them

File Attachments

Messages can include file attachments:

Click attach button

Use the paperclip icon in the message composer.

Select files

Choose files from your device to upload.

Send message

Files upload with your message.

See Files for more details on file handling.

Message Context

Messages can reference nodes from your workspace:

{
  type: "message",
  content: { /* blocks */ },
  selectedContextNodeIds: [
    "page_abc",
    "database_def",
    "record_ghi"
  ]
}

Context nodes provide additional information or references for AI-assisted features and conversation context.

Message Reactions

React to messages with emoji:

Click the reaction button on any message
Select an emoji
See who reacted with each emoji
Remove your reaction by clicking it again

All channel and DM participants (viewers and above) can add reactions to messages.

Message Permissions

Action	Creator	Channel Admin	Others
View	✓	✓	✓ (if member)
Edit	✓	✗	✗
Delete	✓	✓	✗
React	✓	✓	✓ (if viewer+)

Only message creators can edit their messages. Channel admins can delete any message, but regular members can only delete their own.

Real-Time Updates

Chat messages sync in real-time across all connected clients:

Instant Delivery

Messages appear immediately for all online users

Typing Indicators

See when others are composing messages

Read Receipts

Track message delivery and read status

Offline Queueing

Messages queue locally and send when reconnected

Offline Chat

Chat works offline with local-first architecture:

View cached messages

Previously loaded messages remain accessible offline.

Compose offline

Write messages that queue in your local database.

Automatic sync

When reconnected, queued messages send automatically.

Conflict resolution

CRDTs handle concurrent messages from multiple users.

See Collaboration for details on offline sync and conflict resolution.

Notifications

Stay updated on new messages:

Desktop notifications - System notifications for new messages
Unread badges - Visual indicators on channels with new messages
Mentions - Highlighted when someone @mentions you
DM alerts - Special notifications for direct messages

Search

Find messages across all channels:

Search message content
Filter by channel, user, or date
Search file attachments
Find mentions and references

Best Practices

Use channels for topics

Create dedicated channels for projects, teams, or topics rather than having all discussions in one place. This keeps conversations organized and searchable.

@mention for attention

Use @mentions when you need someone’s specific attention or input. This sends them a notification and highlights the message.

Threads for discussions

Use question/answer message types for structured Q&A or threaded discussions to keep related messages together.

Reference context

Link to relevant pages, databases, or records when discussing them in chat to provide easy access.

Archive inactive channels

Delete or archive channels that are no longer active to keep your sidebar clean and organized.

Next Steps

Files

Learn about file attachments in messages

Collaboration

Understand real-time sync

Pages

Reference pages in conversations

Databases

Share database records in chat

Get Started

Core Features

Self-Hosting

Architecture

​Chat Types

Channels

Direct Messages

​Channels

​Creating Channels

​Channel Structure

​Channel Permissions

​Public vs Private Channels

​Direct Messages

​Starting a DM

​DM Structure

​Messages

​Message Types

​Message Content

Text

Code Blocks

Lists

Mentions

​File Attachments

​Message Context

​Message Reactions

​Message Permissions

​Real-Time Updates

Instant Delivery

Typing Indicators

Read Receipts

Offline Queueing

​Offline Chat

​Notifications

​Search

​Best Practices

​Next Steps

Files

Collaboration

Pages

Databases

Build docs developers (and LLMs) love

Chat Types

Channels

Creating Channels

Channel Structure

Channel Permissions

Public vs Private Channels

Direct Messages

Starting a DM

DM Structure

Messages

Message Types

Message Content

File Attachments

Message Context

Message Reactions

Message Permissions

Real-Time Updates

Offline Chat

Notifications

Search

Best Practices

Next Steps