🤖 Telegram Bot Template

Bot starter template based on grammY bot framework.

Features

• Scalable structure
• Config loading and validation
• Internationalization, language changing
• Graceful shutdown
• Logger (powered by pino)
• Ultrafast and multi-runtime server (powered by hono)
• Ready-to-use deployment setups:
  • Docker
  • Vercel
• Examples:
  • grammY plugins:
    • Conversations
    • Runner
  • Databases:
    • Drizzle ORM
  • Runtimes:
    • Bun

Usage

Follow these steps to set up and run your bot using this template:

1. Create a New Repository

   Start by creating a new repository using this template. You can do this by clicking here.

2. Environment Setup

   Create an environment variables file by copying the provided example file:

   cp .env.example .env

   Open the newly created .env file and set the BOT_TOKEN environment variable.

   Start Postgres

   docker run --name=postgres --rm -itd -p 5432:5432 -e POSTGRES_PASSWORD=Crunchy2 -e POSTGRES_DB=tgbot postgres:latest

3. Launching the Bot

   You can run your bot in both development and production modes.

   Development Mode:

   Install the required dependencies:

   bun install

   Generate migrations:

   bun run generate

   Run migrations:

   bun run migrate

   Start the bot in watch mode (auto-reload when code changes):

   bun dev

   Production Mode:

   Install only production dependencies (no development dependencies):

   bun install --only=prod

   Set NODE_ENV environment variable to production in your .env file.
   Update BOT_WEBHOOK with the actual URL where your bot will receive updates.
   Update BOT_WEBHOOK_SECRET with a random secret token.
   Update DATABASE_URL with a production database.

   NODE_ENV=production
   BOT_WEBHOOK=<server_url>/webhook
   BOT_WEBHOOK_SECRET=<random_secret_value>
   DATABASE_URL=<production_db_url>

   Run migrations:

   bun run migrate

   Start the bot in production mode:

   bun start # with type checking (requires development dependencies)
   # or
   bun start:force # skip type checking and start

List of Available Commands

• bun lint — Lint source code.
• bun format — Format source code.
• bun typecheck — Run type checking.
• bun dev — Start the bot in development mode.
• bun start — Start the bot.
• bun start:force — Starts the bot without type checking.

Directory Structure

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

Deploy

Docker (docker.com)

Branch: deploy/docker-compose (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update

2. Merge deployment setup

git merge template/deploy/docker-compose -X theirs --squash --no-commit --allow-unrelated-histories

3. Follow the usage instructions in the deploy/docker-compose branch.

Vercel (vercel.com)

Branch: deploy/vercel (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update

2. Merge deployment setup

git merge template/deploy/vercel -X theirs --squash --no-commit --allow-unrelated-histories

3. Follow the usage instructions in the deploy/vercel branch.

Examples

grammY conversations (grammy.dev/plugins/conversations)

Branch: example/plugin-conversations (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update

2. Merge example

git merge template/example/plugin-conversations -X theirs --squash --no-commit --allow-unrelated-histories

3. Install dependencies

npm i @grammyjs/conversations

4. Follow the usage instructions in the example/plugin-conversations branch.

grammY runner (grammy.dev/plugins/runner)

Branch: example/plugin-runner (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update

2. Merge example

git merge template/example/plugin-runner -X theirs --squash --no-commit --allow-unrelated-histories

3. Install dependencies

npm i @grammyjs/runner

4. Follow the usage instructions in the example/plugin-runner branch.

Bun (bun.sh)

Branch: example/runtime-bun (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template [email protected]:bot-base/telegram-bot-template.git
git remote update

2. Merge example

git merge template/example/runtime-bun -X theirs --squash --no-commit --allow-unrelated-histories

3. Install dependencies

# remove Node-related dependencies
npm r @types/node tsx tsc-watch

# install dependencies
bun i

# remove npm lockfile
rm package-lock.json

# install bun typings
bun add -d @types/bun

4. Follow the usage instructions in the example/runtime-bun branch.

Environment Variables

Variable	Type	Description
NODE_ENV	String	Specifies the application environment. (development or production)
BOT_TOKEN	String	Telegram Bot API token obtained from @BotFather.
DATABASE_URL	String	Database connection.
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.