Bot based on grammY bot framework.
Project based on telegram-bot-template.
- Scalable structure
- Config loading and validation
- Internationalization, language changing
- Graceful shutdown
- Logger (powered by pino)
- Ultrafast and multi-runtime server (powered by hono)
Follow these steps to set up and run your bot:
-
Environment Variables Setup
Create an environment variables file by copying the provided example file:
cp .env.example .env
Open the newly created
.env
file and set theBOT_TOKEN
environment variable. -
Launching the Bot
You can run your bot in both development and production modes.
Development Mode:
Install the required dependencies:
npm install
Start the bot in watch mode (auto-reload when code changes):
npm run dev
Production Mode:
Install only production dependencies (no development dependencies):
npm install --only=prod
Set
NODE_ENV
environment variable toproduction
in your.env
file.
UpdateBOT_WEBHOOK
with the actual URL where your bot will receive updates.
UpdateBOT_WEBHOOK_SECRET
with a random secret token.NODE_ENV=production BOT_WEBHOOK=<server_url>/webhook BOT_WEBHOOK_SECRET=<random_secret_value>
Start the bot in production mode:
npm start # with type checking (requires development dependencies) # or npm run start:force # skip type checking and start
npm run lint
β Lint source code.npm run format
β Format source code.npm run typecheck
β Run type checking.npm run dev
β Start the bot in development mode.npm run start
β Start the bot.npm run start:force
β Starts the bot without type checking.
project-root/
βββ locales # Localization files
βββ src
βββ bot # Contains the code related to the bot
β βββ callback-data # Callback data builders
β βββ features # Implementations of bot features
β βββ filters # Update filters
β βββ handlers # Update handlers
β βββ helpers # Utility functions
β βββ keyboards # Keyboard builders
β βββ middlewares # Middleware functions
β βββ i18n.ts # Internationalization setup
β βββ context.ts # Context object definition
β βββ index.ts # Bot entry point
βββ server # Contains the code related to the web server
β βββ index.ts # Web server entry point
βββ config.ts # Application config
βββ logger.ts # Logging setup
βββ main.ts # Application entry point
Variable | Type | Description |
---|---|---|
NODE_ENV | String | Specifies the application environment. (development or production ) |
BOT_TOKEN | String | Telegram Bot API token obtained from @BotFather. |
LOG_LEVEL | String |
Optional.
Specifies the application log level. For example, use info for general logging. View the Pino documentation for more log level options. Defaults to info .
|
BOT_MODE | String |
Optional.
Specifies method to receive incoming updates (polling or webhook ).Default depends on NODE_ENV (polling for development , webhook for production ).
|
BOT_WEBHOOK | String |
Optional in polling mode.
Webhook endpoint URL, used to configure webhook.
|
BOT_WEBHOOK_SECRET | String |
Optional in polling mode.
A secret token that is used to ensure that a request is sent from Telegram, used to configure webhook.
|
BOT_SERVER_HOST | String |
Optional. Specifies the server hostname. Defaults to 0.0.0.0 .
|
BOT_SERVER_PORT | Number |
Optional. Specifies the server port. Defaults to 80 .
|
BOT_ALLOWED_UPDATES | Array of String |
Optional. A JSON-serialized list of the update types you want your bot to receive. See Update for a complete list of available update types. Defaults to an empty array (all update types except chat_member , message_reaction and message_reaction_count ).
|
BOT_ADMINS | Array of Number |
Optional.
Administrator user IDs.
Use this to specify user IDs that have special privileges, such as executing /setcommands . Defaults to an empty array. |