All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading