# Add Rate Limiting to a grammY Telegram Bot

Yes. An agent reads your bot's middleware chain, adds the ratelimiter plugin per user ahead of your handlers, tests it with a fake update, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-rate-limiting/grammy/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with how the bot is wired, because a rate limit is middleware and its place in the chain decides what it protects. In a bot laid out like grammyjs/examples, `package.json` depends on `grammy` with `@grammyjs/menu`, `@grammyjs/router`, `@grammyjs/runner`, `@grammyjs/hydrate` and `@grammyjs/transformer-throttler`, runs every example with `npm run bot <name>` through `ts-node`, and has no lockfile and no test script. `stats.ts` registers `session()` first, then two counting handlers on `message` and `edited_message` that call `next()`, then `/start` and `/stats`, and ends with `bot.catch`. `scaling/index.ts` attaches `apiThrottler()` to `bot.api.config`, which slows the bot's own calls to Telegram and does nothing about how fast one user can send.

Rate limiting what comes in is `@grammyjs/ratelimiter`. The agent adds it to `package.json` and registers `limit()` before `session()` in `stats.ts`, keyed on `ctx.from?.id` so a limit is per person and not per chat, with a `timeFrame` and `limit` named at the top of the file as two constants, and an `onLimitExceeded` that answers once per window rather than on every dropped update. Updates with no `from`, such as channel posts, pass through, because the key generator returns nothing for them and the plugin lets those by. The counting handlers stay where they are, so a message the limiter drops is not counted as sent.

Two choices come from reading rather than from the plugin's README. The limiter sits ahead of `session()` so the session store is never read for a dropped update, which matters once the in-memory session the file warns about is replaced by a database. And the `/stats` reply, which does a division and formats HTML, is the one handler a flood would make expensive, so the agent writes the limit around it rather than around everything, leaving `/start` and the `:new_chat_members:me` greeting unlimited.

In its sandbox the agent runs `npm install`, then `npx tsc --noEmit` against the repository's `tsconfig.json`, whose `strict` and `noUncheckedIndexedAccess` settings are what a wrong `ctx.from` access trips. It then writes a small test with Node's built-in `node:test` that builds a `Bot` with a fake token, calls `bot.handleUpdate` with the same text message from one user more times than the limit allows within the window, and asserts how many times the handler ran and that `onLimitExceeded` ran once; a second user's message in the same window still goes through. No token is needed, since `handleUpdate` never calls Telegram.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add per-user rate limiting to this grammY bot. Read package.json, tsconfig.json, stats.ts and scaling/index.ts first. Add @grammyjs/ratelimiter and register limit() in stats.ts before session(), keyed on ctx.from?.id, with timeFrame and limit as named constants and an onLimitExceeded that replies once per window. Let updates with no from through. Do not change the counting handlers or the /stats reply text. Run npm install and npx tsc --noEmit, then write a node:test file that drives bot.handleUpdate with the same user's message past the limit inside one window and asserts the handler count and a single onLimitExceeded, and that another user's message still passes. Add a test script to package.json and run it. Open a pull request whose description quotes the tsc and test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `package.json` (the new dependency and a `test` script), `stats.ts` (the import, two constants and the `limit()` registration ahead of `session()`), and adds one test file. The description quotes the `tsc --noEmit` run and the `node --test` output with each assertion named, and says in one sentence where the limiter sits in the chain and why.

The run's record keeps the `npm install` log and every command the agent ran, so a reviewer who wants to know which `@grammyjs/ratelimiter` version was resolved reads it there rather than guessing from a caret range.

Before merging, a reviewer decides two numbers: the window and the count, which the pull request leaves as constants with the values the agent chose, and whether `onLimitExceeded` should reply at all in group chats, where a bot answering a flood adds to it.

## Run it on every Linear issue labelled abuse

A team running several bots makes this a rule. In the Project for each bot's repository, an automation with the prompt above and a `linear` trigger on `linear.issue.labeled` for the label `abuse` starts a run when someone files "user X is spamming /stats in the support group". The trigger adds the issue after the prompt, so the run reads which command and which chat type the report names and places the limit there.

Each run opens its own pull request on its own branch and links the issue. The automation's `max_runs_per_hour` caps how many such runs start when several reports arrive at once, and a second issue about the same bot while a run is open gets its own branch rather than a push to the first.

## Why run it on Rush?

Middleware order is the whole job, and it is the thing a quick edit on a laptop gets wrong: a limiter registered after `session()` still reads the store for every dropped update, and one registered after the counting handlers counts the messages it drops. In a Rush sandbox the agent reads the chain, places the plugin, and proves the placement with a test that drives `handleUpdate` directly, with no bot token and no Telegram call.

The test and the type check stay with the run and the pull request quotes them, so the reviewer reads the assertion that the sixth message in a window did not reach the handler rather than taking it on faith. Across a fleet of bots the job runs in parallel, one sandbox and one pull request each.

## Frequently asked questions

### Does this slow down the bot's own API calls too?

No. That is what `apiThrottler()` in `scaling/index.ts` already does on the outgoing side. `@grammyjs/ratelimiter` works on incoming updates: it decides whether a given user's update reaches your handlers at all.

### What happens to a message the limiter drops?

The middleware chain stops there: `session()` is not read, the counting handlers do not run and no reply is sent, except the one `onLimitExceeded` message per window. Telegram still considers the update delivered, so nothing is retried.

### Does the limit survive a restart or work across several processes?

With the default in-memory storage, no: counters reset when the process exits and each process keeps its own. The plugin takes a Redis storage for a bot run under the runner across several machines; say so in the prompt and the agent wires it with a `REDIS_URL` from the environment.

### Why key on the user and not the chat?

In a group, one flooding user should not silence everyone else's `/stats`. Keying on `ctx.from.id` limits the person; a chat-level limit is one line to change in the key generator if a group as a whole needs capping.

## More grammY jobs

- [Migrate a grammY Bot From Long Polling to Webhooks](https://getrush.ai/run/migrate-polling-to-webhooks/grammy/)
- [Write Unit Tests for a grammY Telegram Bot](https://getrush.ai/run/write-unit-tests/grammy/)
- [Add Error Handling to a grammY Bot](https://getrush.ai/run/add-error-handling/grammy/)

## The same job on other stacks

- [Add Rate Limiting to a Hono API from a Linear Issue](https://getrush.ai/run/add-rate-limiting/hono/)
- [Add Rate Limiting to a Koa App](https://getrush.ai/run/add-rate-limiting/koa/)
- [Add Rate Limiting to a Ktor API](https://getrush.ai/run/add-rate-limiting/ktor/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
