Transcripts (deprecated)

bot.transcripts provides per-user message persistence keyed by a stable cross-platform identifier. See the History guide for setup, usage patterns, and migration steps.

import { Chat } from "chat";

Configuration

history.user (or the deprecated transcripts) requires an identity resolver. Set history.user.identity or the deprecated top-level identity field. Passing history.user without either throws at construction.

ChatConfig.transcripts (deprecated → history.user)

ChatConfig.identity

identity: (context: IdentityContext) => string | null | Promise<string | null>;

Called once per inbound message during dispatch. The result is attached to the Message instance as message.userKey. Return null to skip persistence for an event.

IdentityContext

Methods

Access via bot.history.user (preferred) or bot.transcripts (deprecated alias). Throws if neither history.user nor transcripts was configured on the Chat instance.

append

Persist a Message (typically the inbound user message) or an AppendInput (typically a bot reply you just posted).

append(
  thread: Postable,
  message: Message | AppendInput,
  options?: AppendOptions,
): Promise<TranscriptEntry | null>;

When message is a Message, userKey is read from the instance. If it's undefined (the resolver returned null), the call is a no-op and returns null. When message is an AppendInput, options.userKey is required.

AppendInput

AppendOptions

list

Returns entries in chronological order (oldest first). When limit is set, returns the newest N entries, still in chronological order.

list(query: ListQuery): Promise<TranscriptEntry[]>;

ListQuery

count

count(query: CountQuery): Promise<number>;

Returns the total number of entries stored under the user key. CountQuery has a single field, userKey: string.

delete

delete(target: { userKey: string }): Promise<{ deleted: number }>;

Wipes every entry stored under the user key. Returns the count that was removed. Single-entry and time-range deletes are not supported, because the underlying appendToList primitive can't support them safely under concurrent writes.

TranscriptEntry

Returned by append and list.

Storage

Backed by StateAdapter.appendToList / getList / delete. Every built-in state adapter (memory, redis, ioredis, pg) supports these primitives.

Entries are stored under transcripts:user:{userKey} as a capped list. appendToList is atomic, so concurrent inbound messages don't race.

The retention value is applied as the list TTL and refreshed on every append. With retention: "30d", a user who hasn't talked to the bot in 30 days has their transcript expire automatically.

See also

• History API reference: the current API (bot.history.user, bot.history.thread, bot.history.channel)
• History guide: setup, patterns, and migration