All jobs

Migrate a grammY Bot From Long Polling to Webhooks

Yes. An agent replaces bot.start() with an HTTP server around webhookCallback, sets the webhook with a secret token, keeps a polling entry for laptops, in 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 reads how the bot receives updates and how the repository already does webhooks elsewhere. In a repository laid out like grammyjs/examples, setups/docker-node/main.ts creates new Bot(process.env.BOT_TOKEN), replies to message:text, and calls bot.start(), which long-polls Telegram; its Dockerfile runs tsx ./main.ts behind npm run start as the node user and declares EXPOSE 80, though nothing in the file listens on a port. Three setups already take webhooks: setups/vercel-serverless-node/api/webhook.ts exports webhookCallback(bot, "http") and scripts/build.ts calls bot.api.setWebhook at build time with https://${VERCEL_URL}/api/webhook; setups/deno-deploy/server.ts uses webhookCallback(bot, "std/http") and answers only POST on a path equal to the token, with poll.ts for local runs that calls deleteWebhook() then bot.start(); and fastify.ts at the root passes secretToken to webhookCallback and secret_token to setWebhook.

Those three show the shape and one of them shows the secret. The agent rewrites main.ts around Node's http module, since the setup has no web framework: createServer with webhookCallback(bot, "http", { secretToken }) for POST on one path and a 404 for anything else, listening on PORT, which the Dockerfile already exposes as 80. The path is a fixed /webhook, not the token as in the Deno setup, because the secret travels in the X-Telegram-Bot-Api-Secret-Token header, which webhookCallback compares, and a token in a URL ends up in access logs. Both WEBHOOK_URL and WEBHOOK_SECRET are read from the environment and the process exits with a message when either is missing.

On start the bot calls bot.api.setWebhook(WEBHOOK_URL, { secret_token: WEBHOOK_SECRET }) before listening, the way scripts/build.ts does for Vercel, so a deploy with a new URL registers itself. A new poll.ts beside it does what the Deno setup's does, deleteWebhook() then bot.start(), for a laptop with no public address, and docker-compose.yml's command: npm run dev points at it, with a poll script added to the setup's package.json. README.md for the setup gains the two variables and the one line that explains that polling and a webhook cannot be active at once.

Without a token the agent cannot register a webhook, so it proves what it can. It type-checks with the setup's npm run typecheck, starts the server with a stubbed Bot whose setWebhook records its arguments, sends a POST to /webhook with the right header and reads a 200, sends one with a wrong header and reads a 401, and sends a GET and reads the 404. Those three responses and the recorded setWebhook call go in the description.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Migrate the long-polling bot in setups/docker-node to webhooks. Read setups/docker-node/main.ts, its Dockerfile, docker-compose.yml, package.json and README.md, plus setups/vercel-serverless-node, setups/deno-deploy and fastify.ts at the root for how this repository already handles webhooks. Rewrite main.ts to serve POST /webhook with webhookCallback(bot, \"http\") and a secret token read from WEBHOOK_SECRET, listen on PORT, and call setWebhook with WEBHOOK_URL and the secret before listening; exit with a message when either variable is missing. Add a poll.ts that deletes the webhook and calls bot.start() for local runs, point the compose command at it, and document both variables in the setup's README. Do not touch the other setups. Type-check, then prove the server with a stubbed Bot: a POST with the right header, one with a wrong header, and a GET, quoting each status. Open a pull request.",
  "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 inside setups/docker-node: main.ts rewritten around an HTTP server, poll.ts new, package.json with a poll script, docker-compose.yml pointing command at it, and README.md with the two variables. The Dockerfile is unchanged, since EXPOSE 80 and tsx ./main.ts already fit, and the other setups and the root examples are untouched.

The description quotes the type-check, then the three stubbed requests with their statuses, 200 for the right header, 401 for a wrong one and 404 for a GET, and the setWebhook arguments the stub recorded. The run's record holds the stub script, so a reviewer can see the real bot was never started.

Before merging, a reviewer sets WEBHOOK_URL to the address Telegram will reach and picks a WEBHOOK_SECRET; the first real deploy registers the webhook, and getWebhookInfo through the Bot API confirms it.

Run it on every pull request

Each new bot a team adds in a setup like this one starts with polling, because bot.start() is one line. An automation with a github trigger on pull_request.opened and pull_request.synchronize starts a run that reads the diff for a new bot.start() outside a poll.ts, and comments with the webhook server from this pull request as the pattern and the two variables it needs; when every new bot already serves a webhook, it says nothing.

The trigger adds the pull request to the prompt after it. The result is the comment; the prompt says to push nothing to the author's branch.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Moving a bot to webhooks is a small amount of code and a long list of details: the secret header, the fixed path, registering before listening, keeping a way to run locally. The agent reads how the same repository already does each of them in three other runtimes and writes the Node version to match, in one pass.

Without a token, the proof is a type-check and a stubbed server, and both stay in the run's record with the statuses they returned. The same request runs across a team's bots at once, one sandbox each, with each pull request showing which setup it changed and which it left.

Frequently asked questions

Why a fixed /webhook path and not the token?

The Deno setup uses the token as the path, which works but puts the token in every access log along the way. Telegram sends the secret in the X-Telegram-Bot-Api-Secret-Token header, webhookCallback checks it, and the path can be plain.

What happens if polling and the webhook are both on?

Telegram refuses getUpdates while a webhook is set, which is why poll.ts calls deleteWebhook() first and main.ts calls setWebhook on start. Only one of them runs at a time, and each one puts the bot in the mode it needs.

Does the Dockerfile need a change?

No. It already runs tsx ./main.ts and declares EXPOSE 80; the server listens on PORT, so the port the container publishes is the one the webhook reaches. The agent leaves the file alone and says so.

Can the bot run locally without a public address?

Yes, with poll.ts, which the compose file now runs. It deletes the webhook and long-polls, so a laptop needs no tunnel; the webhook server is for the deployed container.

More grammY jobs

More jobs like this: Hand off a long task

Keep reading