Botxona

How to deploy a Telegraf bot (Node.js) — Telegraf hosting on Botxona

Telegraf is one of the most popular and longest-standing Telegram bot frameworks for Node.js. It needs no special settings to work with Botxona — Telegram requests are automatically routed through the platform proxy, so leave telegram.apiRoot unchanged.

Steps

1. Create Telegraf

const { Telegraf } = require("telegraf")

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

bot.start((ctx) => ctx.reply("Hi! I'm up and running."))
bot.launch()

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

2. Store data in DATA_DIR

To store sessions or user data (e.g. with telegraf-session-local):

const path = require("path")
const DATA_DIR = process.env.DATA_DIR || "./data"

const { LocalSession } = require("telegraf-session-local")
const session = new LocalSession({ database: path.join(DATA_DIR, "sessions.json") })
bot.use(session.middleware())

3. package.json

{
  "scripts": { "start": "node index.js" },
  "dependencies": { "telegraf": "4.16.3" }
}

4. .env.example and upload

Describe your settings in .env.example, zip the folder (details) and upload it to the dashboard.

5. Check and trial

Read the results here, then test the bot during the 15-minute trial.

Long-polling instead of webhooks

Don't use Telegraf's bot.launch({ webhook: {...} }) mode — Botxona itself works via long-polling; a setWebhook call is ignored and isn't needed. A plain bot.launch() (no arguments) is enough.

Scheduled tasks

If you add a time-based task with node-cron or a similar library, Botxona detects it automatically and switches the bot to always on (details).

Common errors

  • TelegramError: 404 Not Found — usually an outdated token or a wrong apiRoot manually changed in the code.
  • Sessions aren't saved — the session file may be stored in the project root instead of DATA_DIR.
  • bot.launch() exits immediately — check that there's no line at the end of your code that terminates the process (e.g. process.exit()).

Faster with AI

Give an AI the ready-made task from the Prompt library and your existing Telegraf code will be adapted in seconds.

Next steps

The Dashboard tour and Errors and fixes.