Registry / database / telegraf-session-redis

telegraf-session-redis

library5.1.0jsnpmunverified

Redis-powered session middleware for Telegraf, the Telegram Bot API framework. Version 5.1.0 is the latest stable release, with regular updates following Telegraf releases. It stores session data in Redis for persistence across bot restarts and horizontal scaling. Key differentiators include support for custom TTL, custom session key resolvers, and manual session access without a context object (useful for OAuth flows). Requires Telegraf ^3.9.0 as a peer dependency.

database

npm install telegraf-session-redis

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TELEGRAF-SESSION-R

telegraf-session-redis

databasejavascriptv5.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RedisSession

✓ import RedisSession from 'telegraf-session-redis'

✗ const RedisSession = require('telegraf-session-redis').default

Default export: use import or const RedisSession = require('telegraf-session-redis')

RedisSession type

✓ import type { RedisSession } from 'telegraf-session-redis' or import RedisSession from 'telegraf-session-redis'

✗ import { RedisSession } from 'telegraf-session-redis'

TypeScript: default export is the class, so use default import syntax. Named type exports are not available.

getSessionKey function

✓ const session = new RedisSession({ getSessionKey: (ctx) => `${ctx.from.id}:${ctx.chat.id}` })

✗ const session = new RedisSession({ getSessionKey: (ctx) => ctx.from.id + ':' + ctx.chat.id })

Default getSessionKey uses template literal; custom function must return a string or undefined.

Sets up a Telegraf bot with Redis session middleware, incrementing a counter on each text message.

Debug

Known issues

breakingv5.0.0 changed the constructor signature: options are now passed as an object instead of separate arguments.

fix

Use new RedisSession({ store: {...}, ttl: ... }) instead of new RedisSession(host, port, ttl).

affects: >=5.0.0

gotchaIf store is not configured, it defaults to 127.0.0.1:6379 with no auth. In production, always set REDIS_URL or store.host/port with password.

fix

Use new RedisSession({ store: { url: process.env.REDIS_URL } }) or provide host, port, password.

affects: all

gotchaThe default getSessionKey uses ctx.from.id and ctx.chat.id. If either is undefined (e.g., in callback queries without chat), session key becomes undefined and session is not stored.

fix

Override getSessionKey to handle missing values: getSessionKey: (ctx) => { if (!ctx.from || !ctx.chat) return null; return `${ctx.from.id}:${ctx.chat.id}`; }

affects: all

deprecatedSetting ctx.session = null destroys the session. This behavior is deprecated; use ctx.session = {} for reset in future versions.

fix

To clear session data, set ctx.session = {} (empty object) instead of null.

affects: >=5.0.0 <6.0.0

Errors

Common errors & fixes

TypeError: Cannot read property 'session' of undefined

Session middleware not applied before accessing ctx.session

fix

Ensure bot.use(session) is called before any handlers that use ctx.session.

Redis connection error: connect ECONNREFUSED 127.0.0.1:6379

Redis server not running or wrong host/port

fix

Start Redis or set correct store.host/store.port in options.

Session key is undefined

getSessionKey returned undefined (e.g., missing from or chat)

fix

Override getSessionKey to handle missing fields or ensure message has from and chat (e.g., not a callback query).

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

telegrafrequiredPeer dependency: session middleware integrates with Telegraf's context and middleware system

redisrequiredRuntime dependency: communicates with Redis server

Agent activity

22 hits · last 30 days

node