Interface Persistence

Contract for bot state persistence backends.

Enables storing and retrieving user data, chat data, bot data, conversation states, and scheduled background jobs across bot restarts.

Example

class MyCustomPersistence implements Persistence {
  async getUserData(userId: number) { return {}; }
  async setUserData(userId: number, data: Record<string, unknown>) {}
  // ... other methods
}

interface Persistence {
    deleteChatData?(chatId: string | number): Promise<void>;
    deleteConversation?(key: string): Promise<void>;
    deleteUserData?(userId: number): Promise<void>;
    flush?(): Promise<void>;
    getBotData(): Promise<Record<string, unknown>>;
    getChatData(chatId: string | number): Promise<Record<string, unknown>>;
    getConversations(): Promise<Map<string, string | number>>;
    getJobs(): Promise<PersistedJob[]>;
    getUserData(userId: number): Promise<Record<string, unknown>>;
    setBotData(data: Record<string, unknown>): Promise<void>;
    setChatData(
        chatId: string | number,
        data: Record<string, unknown>,
    ): Promise<void>;
    setJobs(jobs: PersistedJob[]): Promise<void>;
    setUserData(userId: number, data: Record<string, unknown>): Promise<void>;
    updateConversation(key: string, state: string | number): Promise<void>;
}

Implemented by

Index

Methods

deleteChatData? deleteConversation? deleteUserData? flush? getBotData getChatData getConversations getJobs getUserData setBotData setChatData setJobs setUserData updateConversation

Methods

`Optional`deleteChatData

deleteChatData?(chatId: string | number): Promise<void>
Optional method to delete chat data for a specific chat ID.
Parameters
- chatId: string | number
  Telegram chat ID.
Returns Promise<void>

`Optional`deleteConversation

deleteConversation?(key: string): Promise<void>
Optional method to delete conversation state.
Parameters
- key: string
  Conversation key composite.
Returns Promise<void>

`Optional`deleteUserData

deleteUserData?(userId: number): Promise<void>
Optional method to delete user data for a specific user ID.
Parameters
- userId: number
  Telegram user ID.
Returns Promise<void>

`Optional`flush

flush?(): Promise<void>

Optional lifecycle hook to flush in-memory buffers to underlying disk or database.

Returns Promise<void>
Resolves when flushing completes.

getBotData

getBotData(): Promise<Record<string, unknown>>

Retrieves global bot data.

Returns Promise<Record<string, unknown>>
Bot data object.

getChatData

getChatData(chatId: string | number): Promise<Record<string, unknown>>
Retrieves stored chat data for a specific chat ID.
Parameters
- chatId: string | number
  Telegram chat ID (number or string).
Returns Promise<Record<string, unknown>>
Chat data object (returns empty object if none found).

getConversations

getConversations(): Promise<Map<string, string | number>>

Retrieves all active conversation states.

Returns Promise<Map<string, string | number>>
A map of conversation keys to state values.

getJobs

getJobs(): Promise<PersistedJob[]>

Retrieves all persisted scheduled jobs.

Returns Promise<PersistedJob[]>
Array of PersistedJob definitions.

getUserData

getUserData(userId: number): Promise<Record<string, unknown>>
Retrieves stored user data for a specific user ID.
Parameters
- userId: number
  Telegram user ID.
Returns Promise<Record<string, unknown>>
User data object (returns empty object if none found).

setBotData

setBotData(data: Record<string, unknown>): Promise<void>
Stores global bot data.
Parameters
- data: Record<string, unknown>
  Key-value map of global bot state.
Returns Promise<void>
Resolves when data is saved.

setChatData

setChatData(
chatId: string | number,
data: Record<string, unknown>,
): Promise<void>
Stores chat data for a specific chat ID.
Parameters
- chatId: string | number
  Telegram chat ID (number or string).
- data: Record<string, unknown>
  Key-value map of chat state.
Returns Promise<void>
Resolves when data is saved.

setJobs

setJobs(jobs: PersistedJob[]): Promise<void>
Overwrites the list of persisted scheduled jobs.
Parameters
- jobs: PersistedJob[]
  Array of PersistedJob definitions.
Returns Promise<void>
Resolves when jobs are saved.

setUserData

setUserData(userId: number, data: Record<string, unknown>): Promise<void>
Stores user data for a specific user ID.
Parameters
- userId: number
  Telegram user ID.
- data: Record<string, unknown>
  Key-value map of user state.
Returns Promise<void>
Resolves when data is saved.

updateConversation

updateConversation(key: string, state: string | number): Promise<void>
Updates or saves the state for a specific conversation key.
Parameters
- key: string
  Conversation key composite (e.g. chat_id + user_id).
- state: string | number
  Conversation state identifier or step number.
Returns Promise<void>
Resolves when state is updated.

Interface Persistence

Example

Implemented by

Index

Methods

Methods

OptionaldeleteChatData

Parameters

Returns Promise<void>

OptionaldeleteConversation

Parameters

Returns Promise<void>

OptionaldeleteUserData

Parameters

Returns Promise<void>

Optionalflush

Returns Promise<void>

getBotData

Returns Promise<Record<string, unknown>>

getChatData

Parameters

Returns Promise<Record<string, unknown>>

getConversations

Returns Promise<Map<string, string | number>>

getJobs

Returns Promise<PersistedJob[]>

getUserData

Parameters

Returns Promise<Record<string, unknown>>

setBotData

Parameters

Returns Promise<void>

setChatData

Parameters

Returns Promise<void>

setJobs

Parameters

Returns Promise<void>

setUserData

Parameters

Returns Promise<void>

updateConversation

Parameters

Returns Promise<void>

Settings

On This Page

`Optional`deleteChatData

`Optional`deleteConversation

`Optional`deleteUserData

`Optional`flush