Conversations

This guide covers how to work with conversations: listing the user’s conversations, creating new ones, fetching a single conversation, and managing members.

Listing Conversations

useConversations fetches the authenticated user’s conversation list with cursor-based pagination. The list is sorted by most recent activity.

import { useConversations } from "@sublay/react-js";

function ConversationList() {
  const { conversations, loading, hasMore, loadMore } = useConversations();

  return (
    <div>
      {conversations.map((convo) => (
        <div key={convo.id}>
          <strong>{convo.name ?? "Direct Message"}</strong>
          <span>{convo.unreadCount > 0 ? `${convo.unreadCount} unread` : ""}</span>
        </div>
      ))}
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}

To filter by conversation type, pass a types array:

// Only show direct and group conversations (no space chats)
const { conversations } = useConversations({ types: ["direct", "group"] });

Each item in the list is a ConversationPreview — a Conversation extended with unreadCount and a truncated lastMessage.

The list is live. It reorders on new messages, inserts conversations as they’re created or added (including ones paginated out that receive a new message), removes conversations you leave or that are deleted, and self-heals on socket reconnect — across direct, group, and space chats. You don’t need to refetch it manually. See Real-time › Live Conversation List.

See useConversations for the full API.

Creating a Direct Conversation

Use useCreateDirectConversation to start a 1:1 conversation with another user. If a direct conversation between the two users already exists, the server returns the existing one.

import { useCreateDirectConversation } from "@sublay/react-js";

function StartChat({ userId }: { userId: string }) {
  const createDirect = useCreateDirectConversation();

  const handleClick = async () => {
    const conversation = await createDirect({ userId });
    // Navigate to the conversation view
  };

  return <button onClick={handleClick}>Send a message</button>;
}

See useCreateDirectConversation.

Creating a Group Conversation

Group conversations are created via useConversations, which exposes a createGroup function:

import { useConversations } from "@sublay/react-js";

function NewGroupButton() {
  const { createGroup } = useConversations();

  const handleCreate = async () => {
    const conversation = await createGroup({
      name: "Project Team",
      metadata: { color: "#4f46e5" },
    });
    // Navigate to the new group
  };

  return <button onClick={handleCreate}>New Group</button>;
}

After creation, the new conversation is prepended to the conversation list in Redux state.

Accessing a Single Conversation

useConversation fetches full details for one conversation and provides update and deleteConversation actions:

import { useConversation } from "@sublay/react-js";

function ConversationHeader({ conversationId }: { conversationId: string }) {
  const { conversation, loading, update } = useConversation({ conversationId });

  if (loading || !conversation) return <div>Loading...</div>;

  return (
    <div>
      <h2>{conversation.name ?? "Direct Message"}</h2>
      <button onClick={() => update({ name: "New Name" })}>Rename</button>
    </div>
  );
}

The conversation is fetched once on mount if not already in Redux state. Real-time conversation:updated socket events keep it current automatically. See useConversation.

Managing Members

useConversationMembers loads the member list and exposes add, remove, leave, and role-change actions:

import { useConversationMembers } from "@sublay/react-js";

function MemberList({ conversationId }: { conversationId: string }) {
  const { members, addMember, removeMember, changeRole, leave } =
    useConversationMembers({ conversationId });

  return (
    <ul>
      {members.map((member) => (
        <li key={member.userId}>
          {member.user?.name} — {member.role}
          <button onClick={() => removeMember({ userId: member.userId })}>
            Remove
          </button>
        </li>
      ))}
    </ul>
  );
}

See useConversationMembers.

Space Conversations

Every Space has a single associated conversation. Use useFetchSpaceConversation to retrieve it:

import { useFetchSpaceConversation } from "@sublay/react-js";

function SpaceChat({ spaceId }: { spaceId: string }) {
  const { conversation, loading } = useFetchSpaceConversation({ spaceId });

  if (!conversation) return null;

  // Use conversation.id with message hooks
}

See useFetchSpaceConversation.

Next Steps

Messages

Send and receive messages in a conversation

Real-time

Typing indicators, unread counts, read receipts

Setup

Authentication

Users

Entities

Entity Lists

Comments

Reactions

Spaces

Events

Chat

Collections

Relationships

App Notifications

Push Notifications

Search & AI

Storage

Moderation

Custom Tables

Listing Conversations

Creating a Direct Conversation

Creating a Group Conversation

Accessing a Single Conversation

Managing Members

Space Conversations

Next Steps

Messages

Real-time

​Listing Conversations

​Creating a Direct Conversation

​Creating a Group Conversation

​Accessing a Single Conversation

​Managing Members

​Space Conversations

​Next Steps

Messages

Real-time

Listing Conversations

Creating a Direct Conversation

Creating a Group Conversation

Accessing a Single Conversation

Managing Members

Space Conversations

Next Steps