Overview
Fetches the authenticated user’s conversation list with cursor-based pagination. Conversations are sorted by most recent activity. The hook also exposes acreateGroup function to create new group conversations.
Requires
ChatProvider in the component tree.Usage Example
Props
Filter conversations by type. If omitted, all types are returned.
Returns
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.true while a fetch is in progress.true if there are more conversations to load.Fetches the next page of conversations and appends them to the list. No-ops if
loading is true or hasMore is false.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
lastMessageandlastMessageAtof the relevant conversation in the list automatically — no manual refresh needed. - For integration guidance, see Chat: Conversations.

