Use conversations

Fetch a paginated list of the current user’s conversations

Overview

Fetches the authenticated user’s conversation list with cursor-based pagination. Conversations are sorted by most recent activity. The hook also exposes a createGroup function to create new group conversations.

Requires ChatProvider in the component tree.

Usage Example

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

function ConversationList() {
  const { conversations, loading, hasMore, loadMore, refresh } =
    useConversations({ types: ["direct", "group"] });

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

Props

types · ('direct' | 'group' | 'space')[]

Filter conversations by type. If omitted, all types are returned.

Returns

conversations · ConversationPreview[]

The loaded conversations sorted by most recent activity. Each item is a Conversation extended with unreadCount, a truncated lastMessage, and otherMembers — up to 5 active members other than the current user (public fields id, name, username, avatar), populated for direct/group conversations so a DM/group row can render the counterparty’s name and avatar. Capped at 5 (use memberCount for the group total); empty for space conversations.

loading · boolean

true while a fetch is in progress.

hasMore · boolean

true if there are more conversations to load.

loadMore · () => Promise<void>

Fetches the next page of conversations and appends them to the list. No-ops if loading is true or hasMore is false.

refresh · () => Promise<void>

Resets the cursor and re-fetches the conversation list from the beginning.

createGroup · (params: { name?: string; metadata?: Record<string, unknown>; memberIds?: string[] }) => Promise<ConversationPreview>

Creates a new group conversation and prepends it to the loaded list. Resolves to the created ConversationPreview. Pass memberIds to add initial members in the same request — the server creates their member rows in one transaction. The creator is added as admin automatically and is de-duplicated if also present in memberIds.

Notes

• The initial fetch runs on mount. Re-runs automatically when the authenticated project changes.
• New messages received via socket update the lastMessage and lastMessageAt of the relevant conversation in the list automatically — no manual refresh needed.
• For integration guidance, see Chat: Conversations.