Introducing Livops 2.0! Promo codeCEOgives you 8,000 so‘m on your balance.What’s new

Telegraf bot hosting: deploying a Telegraf 4 bot on Node.js

A Telegraf bot is one Node.js process: bot.launch() for polling, or bot.webhookCallback() behind an HTTP server for a webhook, with bot.stop() on SIGTERM. On Livops a repository with telegraf in package.json is run as a bot from every push, for 19 credits a month (19,000 so'm).

By Livops team, the people who build and run LivopsUpdated

Telegraf is the long-standing Node.js framework for Telegram bots; version 4.16.3 is the current one in its docs[1]. A Telegraf bot is a single Node process, and hosting it means keeping that process up, giving it the token through the environment, stopping it cleanly, and keeping sessions somewhere that survives a restart. This page covers each, the one webhook detail that catches people out, and the exact files Livops reads.

What does a Telegraf bot need in production?

A process that keeps polling, or an HTTP server

Telegram delivers updates either to getUpdates or to a webhook, never both[5]. bot.launch() with no options polls — and calls deleteWebhook first, so a leftover webhook from another host does not block it[2]. With a webhook, Telegram POSTs to your HTTPS address and your process only has to answer.

A graceful stop

Telegraf’s docs end every example the same way, and a bot on a server needs it most[1]:

process.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

bot.stop() closes the webhook server or stops polling; called when neither is running, it throws Bot is not running![2].

Sessions outside memory

session() with no store uses an in-memory store[4], so every restart and every deploy empties it. Telegraf’s own comment points to @telegraf/session, or a store you pass yourself, for data that must survive restarts or be shared between instances[4].

A production Telegraf bot, polling

package.json:

{
  "name": "my-bot",
  "private": true,
  "scripts": { "start": "node bot.js" },
  "dependencies": { "telegraf": "^4.16.3" }
}

bot.js:

const { Telegraf } = require("telegraf");
const { message } = require("telegraf/filters");

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

bot.start((ctx) => ctx.reply("Hello!"));
bot.on(message("text"), (ctx) => ctx.reply(ctx.message.text));

bot.launch();

process.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

The same bot on a webhook

Telegraf offers three ways in, and they differ in one thing: who calls setWebhook.

  • bot.launch({ webhook: { domain, port } }) starts a server and calls setWebhook[2]. Its secretToken option is optional[1] — set it anyway.
  • bot.createWebhook({ domain }) also calls setWebhook, then returns a request handler[2].
  • bot.webhookCallback(path, { secretToken }) only handles requests: it accepts POSTs on path with the right X-Telegram-Bot-Api-Secret-Token header[2], answers anything else with 403[3], and leaves setWebhook to you.

Where the platform sets the webhook, use the third, so your code never moves it somewhere else:

const http = require("node:http");

const server = http.createServer(
  bot.webhookCallback(process.env.WEBHOOK_PATH, {
    secretToken: process.env.WEBHOOK_SECRET,
  }),
);
server.listen(Number(process.env.PORT));

// bot.launch() was never called, so bot.stop() would throw: close the server.
process.once("SIGTERM", () => server.close());

Deploy a Telegraf bot on Livops

  1. Push the repository, or upload the folder as a .zip, and create a project from it in the cabinet.
  2. Under Settings → Variables, add BOT_TOKEN and mark it as a secret: its value is never shown again.
  3. Deploy. The log shows npm install and the start.

telegraf in package.json makes the project a Telegram bot. Livops runs npm install, then your build script if there is one, and starts npm run start. With no start script it runs a file it finds: index.js, bot.js, app.js, main.js or server.js, in the root or in src/. A .nvmrc or .node-version file picks the Node version. To set the type and the command yourself, add livops.json:

{
  "kind": "bot",
  "start": "node bot.js"
}

Polling is the default, and the polling bot above runs unchanged: no port, no domain. Livops does not read a Node bot’s source to guess its mode, so for a webhook open Settings → Connection to Telegram, choose Webhook and press Save and redeploy. The platform generates WEBHOOK_SECRET, sets PORT and WEBHOOK_PATH (/webhook unless you change it), tells Telegram the address with the secret once the bot answers, and refuses requests to the path that lack it. The webhookCallback example above is exactly what it expects. In webhook mode the token must be in BOT_TOKEN.

What happens after that:

  • On a push, a polling bot is stopped first — SIGTERM, then ten seconds — and the new version starts after it, so two copies never poll with one token. A webhook bot’s new copy must answer on PORT within a minute and takes the updates before the old one is stopped.
  • If the bot exits in its first 30 seconds, the deploy is marked failed with its last lines in the log. A bot that prints nothing and exits with code 0 usually never reached bot.launch().
  • If it crashes later, it is started again; ten crashes inside 15 minutes and it is stopped, and you are notified with its last lines — in Telegram, if your account is linked.
  • Files go in /app/data (process.env.DATA_DIR), which survives restarts and deploys; the code folder is read-only and /tmp is wiped. For sessions, add Redis or PostgreSQL under Databases: REDIS_URL or DATABASE_URL appears in the bot’s variables by itself.
  • The clock is UTC. For node-cron schedules in Tashkent time, pass timezone: "Asia/Tashkent" or add TZ=Asia/Tashkent under Variables.

A bot costs 19 credits a month (19,000 so’m), polling or webhook. One credit is 1,000 so’m; see Pricing.

Livops or a VPS?

A VPS gives you root and room for many bots, with pm2 or systemd to keep them running — and with it the deploys, the Node upgrades and the system updates. On Livops a git push is the deploy and restarts are the platform’s; you give up root, so a bot that needs system software of its own is better on a VPS or in its own Dockerfile.

Questions

How does Livops know my Node project is a bot?

From package.json: telegraf, grammy, node-telegram-bot-api and a few other Telegram libraries make it a Telegram bot project. It runs npm install, your build script if there is one, and then the start script.

My package.json has no start script. Will it run?

Yes, if a file such as index.js, bot.js, app.js or main.js is in the root or in src/. Livops runs it with node. A start script is still the clearest way to say what runs.

Can I use bot.launch with a webhook on Livops?

Not as it is: launch with webhook options, and createWebhook, both call setWebhook with an address of their own. Use bot.webhookCallback behind node:http, listening on PORT at WEBHOOK_PATH with WEBHOOK_SECRET, and let the platform set the webhook.

Does a TypeScript Telegraf bot work?

Yes. If package.json has a build script it runs during the build; point the start script at the compiled file, for example node dist/bot.js.

Where do sessions go?

Telegraf's session() keeps them in memory by default, so a restart or a deploy loses them. Use a persistent store, for example with @telegraf/session on the Redis or PostgreSQL database you add to the project.

How much does it cost?

19 credits a month, 19,000 so'm, the same for polling and webhook. There is no free tier for bots; the first bot on an account that has not paid runs for 15 minutes on a zero balance.

Sources

  1. Telegraf — documentation (v4.16.3) (telegraf.js.org). Checked .
  2. Telegraf source — src/telegraf.ts (raw.githubusercontent.com). Checked .
  3. Telegraf source — src/core/network/webhook.ts (raw.githubusercontent.com). Checked .
  4. Telegraf source — src/session.ts (raw.githubusercontent.com). Checked .
  5. Telegram Bot API — Getting updates (core.telegram.org). Checked .

Put your project online today

Connect GitHub or drop a folder. No card is asked for.

Deploy your Telegraf bot

Got a question? — @livops_uz