Conversations

@10x-media/conversations adds conversations to Payload. A conversation belongs to a target: a document, a global, or a key of your own. Its messages live in channels, and each channel decides who reads and who writes. Threads are one level deep. Mentions go through a Lexical feature and end in a hook. Every user has their own read state, per channel and per thread.

The core has no opinion on what a conversation is for. comments() turns it into a Comments button on edit views, reactions() adds emoji reactions, and attachments() files on messages. A support ticket system or a chat room is another configuration of the same core, with a view you compose from the admin components or, on a website, from the headless hooks and the shadcn registry.

import { conversations, perTarget } from '@10x-media/conversations'
import { comments } from '@10x-media/conversations/comments'

const isStaff = ({ req }) => req.user?.collection === 'users'

export default buildConfig({
  plugins: [
    conversations({
      slug: 'comments',
      access: perTarget(({ req }) => Boolean(req.user)),
      channels: [
        { slug: 'internal', label: 'Internal', access: { read: isStaff, create: isStaff } },
      ],
      extensions: [comments({ collections: { posts: true } })],
    }),
  ],
})

The model

• Instance. One conversations() call, named by slug. It registers <slug>-messages and <slug>-reads and serves its endpoints under /api/conversations/<slug>. Call it again for another use case: comments, tickets, chat.
• Key. A conversation is a string: collection:<slug>:<id>, global:<slug> or custom:<anything>. The target holds no reference to it, so no field is added to your collections.
• Channel. An attribute of each message, with its own access. A target offers the channels you list for it.
• Access. Conversation access answers for many targets in one batch, per target (every channel, some channels, or read only). Channel rules see only the user. Both collections are closed over REST; every read and write goes through the instance endpoints.
• Thread. A reply points at its root. Roots count their replies atomically on Mongo and Postgres.
• Read state. A cursor per user, conversation and channel, plus one per opened thread.
• Transport. How browsers learn that something changed: polling by default, Server-Sent Events, or a Pusher-compatible service.
• Extensions. Shape an instance, add per-message data, endpoints, stored fields, their part of a send, UI slots, composer addons and client data.

Entry points

Where to go next

• Quick start: install, configure access and channels, and add comments.
• Concepts: instances, keys, channels, threads, read state and the data model.
• Access: grants per target, channel rules, read-only conversations, mentions, closed REST.
• Messages: sending, editing, deleting, custom message types, server helpers, hooks and endpoints.
• Rich text: the instance editor and composer features.
• Extensions: how they work, comments, reactions, attachments, and writing your own.
• Admin UI: the components, slots, replacing components, custom views and styling.
• Website UI: customer auth and the provider, the shadcn registry, and the headless hooks.
• Transport: polling, SSE with its buses, and Pusher.
• Recipes: support tickets, chat rooms, multi-tenant.
• Configuration: every option.
• Production notes: cascade, plugin order, database cost, limits.
• i18n: translate the UI and localize channel labels.