DEV Community: Nikita Zavada

How to Handle Telegram Albums in Telegraf

Nikita Zavada — Mon, 25 May 2026 20:14:33 +0000

When building Telegram bots with Telegraf, it is easy to expect that a media album arrives as a single message.

In reality, Telegram sends every media item as a separate update.

For example, if a user sends an album with 3 photos, your bot receives:

update #1 -> photo_1
update #2 -> photo_2
update #3 -> photo_3

instead of:

single_post -> [photo_1, photo_2, photo_3]

This creates several annoying production problems:

duplicate database records
race conditions
buffering logic
ordering issues
timeout handling

At first, the solution usually starts with something simple:

const mediaGroups = new Map();

// buffering
// sorting
// cleanup
// timeout handling

But once Redis, multiple workers, or higher traffic enter the picture, the logic becomes much harder to maintain.

The Solution

I built telegram-media — a TypeScript library for Node.js that collects Telegram media groups into a single normalized object.

Installation

npm install telegram-media

Telegraf Example

import { Telegraf } from "telegraf";
import {
  createRedisMediaGroupStorage,
  createTelegramMediaGroup,
} from "telegram-media";

const bot = new Telegraf(process.env.BOT_TOKEN!);

const collector = createTelegramMediaGroup({
  storage: createRedisMediaGroupStorage(redisClient),

  timeoutMs: 3000,

  supportedMediaTypes: ["photo", "video", "audio"],

  async onCollected(post) {
    console.log("Collected media group:", post);
  },
});

bot.on("message", async (ctx) => {
  await collector.collect(ctx.update);
});

bot.launch();

Why This Helps?

Instead of manually buffering Telegram updates, the collector:

groups related media automatically
preserves media ordering
prevents duplicate processing
works with Redis
returns a single normalized post object
Features
Media group aggregation
Redis support
Duplicate prevention
Media ordering
Configurable timeout
TypeScript support
Links
npm: https://www.npmjs.com/package/telegram-media
GitHub: https://github.com/NikitosIT/telegram-media

How to Handle Telegram Albums in grammY

Nikita Zavada — Mon, 25 May 2026 20:12:10 +0000

When building Telegram bots with grammY, it is natural to expect that a media album arrives as a single message.

In reality, Telegram works differently.

If a user sends an album with multiple photos or videos, your bot receives multiple separate update events instead of one complete post.

For example:

update #1 -> photo_1
update #2 -> photo_2
update #3 -> photo_3

instead of:

single_post -> [photo_1, photo_2, photo_3]

This quickly creates several annoying problems:

duplicate database records
race conditions
buffering logic
ordering issues
timeout handling

At first, handling this manually may seem simple.

Usually the implementation starts with something like this:

const mediaGroups = new Map();

// buffering
// sorting
// cleanup
// timeout handling

But once Redis, multiple workers, or production traffic enter the picture, the logic becomes much more complicated.

The Solution

Install the library telegram-media — a TypeScript library for Node.js that collects Telegram media groups into a single normalized object.

Installation
npm install telegram-media
grammY Example

import { Bot } from "grammy";
import {
  createRedisMediaGroupStorage,
  createTelegramMediaGroup,
} from "telegram-media";

const bot = new Bot(process.env.BOT_TOKEN!);

const collector = createTelegramMediaGroup({
  storage: createRedisMediaGroupStorage(redisClient),

  timeoutMs: 3000,

  supportedMediaTypes: ["photo", "video", "audio"],

  async onCollected(post) {
    console.log("Collected media group:", post);
  },
});

bot.on("message", async (ctx) => {
  await collector.collect(ctx.update);
});

bot.start();

Why This Helps

Instead of manually buffering Telegram updates, the collector:

groups related media automatically
preserves media ordering
prevents duplicate processing
works with Redis
returns a single normalized post object
Features
Media group aggregation
Redis support
Duplicate prevention Media ordering
Configurable timeout
TypeScript support Links npm: https://www.npmjs.com/package/telegram-media GitHub: https://github.com/NikitosIT/telegram-media

How to Collect Telegram Media Groups in Node.js

Nikita Zavada — Fri, 22 May 2026 20:12:52 +0000

When working with the Telegram Bot API, it is easy to expect that an album with multiple photos will arrive as a single event.

But Telegram works differently.

If a user sends an album of 3 photos, your bot doesn't receive one "post" object. Instead, it receives 3 separate updates in rapid succession:

Update #1 -> photo_1
Update #2 -> photo_2
Update #3 -> photo_3

instead of:

single_post -> [photo_1, photo_2, photo_3]

The Headache: Why this is hard
Handling these updates manually forces you to deal with a lot of "plumbing" code that has nothing to do with your actual bot logic:

Duplicate database records: Accidentally creating 3 posts instead of 1.
Race conditions: Multiple updates hitting your server at the exact same time.
Buffering & Timeouts: Deciding how long to wait for the "next" photo before assuming the group is complete.
Ordering: Ensuring the photos stay in the order the user intended.
Typical "infrastructure" code usually starts looking like this mess:

const mediaGroups = new Map();
// buffering logic...
// sorting logic...
// duplicate prevention...
// cleanup jobs...
// timeout handling...

At some point, you realize you are rewriting low-level infrastructure instead of building your actual features.

The Solution: telegram-media
I built telegram-media—a lightweight TypeScript library for Node.js that collects these scattered Telegram updates into a single, normalized object.

Installation

npm install telegram-media

Usage Example
Here is how you can use it to collect media and save it to a database (like Prisma) using a Redis storage backend:

const collector = createTelegramMediaGroup({
  async onCollected(post) {
    // This only fires ONCE per media group
    await prisma.telegramPost.create({
      data: mapCollectedPostToPrismaInput(post),
    });
  },

  // Use Redis for distributed environments
  storage: createRedisMediaGroupStorage(redisClient),

  timeoutMs: 3000,

  supportedMediaTypes: ["photo", "video", "audio"],
});

Why I Built This?
I ran into this problem while building a Telegram ingestion system for a personal project. At first, the logic seemed simple—just a small Set and a setTimeout.

Then the edge cases hit: distributed workers fighting over the same group, incomplete groups caused by network lag, and Redis synchronization issues. I extracted the logic into a standalone package so no one else has to solve this from scratch.

Key Features

Media Group Aggregation — Automatically groups related Telegram updates into a single normalized post.
Redis Support — Ready for production and distributed environments.
Duplicate Prevention — Handles Telegram retry updates safely.
Ordering — Preserves the original media sequence.
TypeScript — Fully typed for a better developer experience.

Explore

What do you think?
I'd love to hear how others are handling media groups. Do you use a custom buffer, or do you just process each image individually and update the record as you go?

Let me know in the comments!