Skip to content

Let users browse past threads

Let users return to previous conversations, see readable titles in a history list, and decide which threads can be continued.

Enable thread history in the client

The ChatKit React hooks support a built-in history view that lists past threads. History is enabled by default, but you can configure it explicitly when you create your ChatKit controller:

const chatkit = useChatKit({
  // ...
  history: {
    enabled: true,
    showDelete: true,
    showRename: true,
  },
});

With history.enabled: true, ChatKit.js will:

  • Fetch threads from your ChatKit server.
  • Show them in a history list using thread.title when available.
  • Let users click a past thread to load its items and continue the conversation.
  • Let users delete and rename threads.

Set history.enabled: false to hide the history UI. Your store still persists the current conversation.

When you reopen a thread, threads.get_by_id returns its metadata and the first page of up to 20 visible items, oldest first. The browser fetches the rest with items.list. In a custom client, while has_more is true, use the returned page’s after cursor and set order to "asc" on each request. Omitting order makes items.list read in descending order.

Show readable titles in history

Threads start untitled. Give them short, descriptive titles so the history list is easy to scan.

Set a title directly

Call update_thread with the active turn ID and yield the returned event.

from chatkit.server import ChatKitServer
from chatkit.turns import Turn


class MyChatKitServer(ChatKitServer[RequestContext]):
    async def respond(self, turn: Turn[RequestContext]):
        ...
        if not turn.thread.title:
            yield await self.update_thread(
                turn.thread.id,
                {"title": "Order #1234"},
                turn.context,
                turn_id=turn.id,
            )

ChatKit applies the patch to the latest stored thread. Yielding the ThreadUpdatedEvent updates the title in the connected client's history view.

Auto-generate a title after the first turn

Generate a concise title after the first assistant turn once you have enough context. Skip if the thread already has a title or if there isn’t enough content to summarize.

from contextlib import aclosing

from chatkit.agents import stream_agent_response
from chatkit.turns import Turn


class MyChatKitServer(ChatKitServer[RequestContext]):
    async def respond(self, turn: Turn[RequestContext]):
        agent_context, result = start_agent_run(turn)

        async with aclosing(stream_agent_response(agent_context, result)) as events:
            async for event in events:
                yield event

        if turn.thread.title is None:
            items = await self.store.load_thread_items(
                turn.thread.id, after=None, limit=6, order="desc", context=turn.context
            )
            title = await generate_short_title(list(reversed(items.data)))
            yield await self.update_thread(
                turn.thread.id, {"title": title}, turn.context, turn_id=turn.id
            )

Use any model call you like for generate_short_title: run a tiny Agent, a simple completion, or your own heuristic. Keep titles brief (for example, 3–6 words).

Decide which threads can be continued

By default, users can continue any past thread: selecting it in the history view loads its items and reuses the same thread when they send a new message.

Use thread.status to mark conversations that should no longer accept new messages. Locked and closed threads still appear in history, but the composer UI changes.

Use the locked state for a temporary pause and the closed state when the conversation is finished.

State When to use Input UI What the user sees
Locked Temporary pause for moderation or admin action Composer stays on screen but is disabled; the placeholder shows the lock reason. The reason for the lock in the disabled composer.
Closed Final state when the conversation is done The input UI is replaced with an informational banner. A static default message or a custom reason, if provided.

Update thread status (lock, close, or re-open)

from chatkit.models import ActiveStatus, LockedStatus, ClosedStatus

# lock (temporary pause)
await store.patch_thread(
    thread.id, {"status": LockedStatus(reason="Escalated to support.")}, context
)

# close (final state)
await store.patch_thread(
    thread.id, {"status": ClosedStatus(reason="Resolved.")}, context
)

# re-open
await store.patch_thread(thread.id, {"status": ActiveStatus()}, context)

To update the connected client, yield the event returned by await self.update_thread(thread.id, {"status": status}, context, turn_id=turn_id). Use turn.id in respond or the supplied turn_id in a streaming action. Calling the store directly only saves the status.

You can also update the thread status from a custom client-facing endpoint that updates the store directly (outside of the ChatKit server request flow). If the user is currently viewing the thread, have the client call chatkit.fetchUpdates() after the status is persisted so the UI picks up the latest thread state.

Block server-side work when locked or closed

Thread status controls how the client displays the composer. Enforce your write policy in the backend for locked or closed threads. Check it before dispatching a write operation, or enforce it in your store transaction when a thread could close concurrently. respond runs after ChatKit saves an incoming message or tool result, so it is too late to prevent that write.