🤖 Telegram Bot Template

Typescript-powered starter template based on grammY bot framework. Supports both polling and webhook modes.

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

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 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 the BOT_TOKEN environment variable.

3. Launching the Bot

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

   Development Mode:

   Install the required dependencies:

   npm install

   Run migrations:

   npx prisma migrate dev

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

   npm run dev

   Production Mode:

   Install only production dependencies:

   npm install --only=prod

   Set DEBUG environment variable to false in your .env file.
   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:

   npx prisma migrate deploy

   Start the bot in production mode:

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

List of Available Commands

• 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.

Directory Structure

project-root/
  ├── api # API code (for webhook support on Vercel)
  │   └── index.ts          # Entry point for the API
  ├── locales               # Localization files (Fluent)
  ├── prisma # Persistence (Prisma ORM)
  │   ├── migrations        # Migrations
  │   └── schema.prisma     # DB schema
  └── src
      ├── bot # Telegram bot code
      │   ├── callback-data # Callback data builders
      │   ├── features      # Bot features
      │   ├── filters       # Update filters
      │   ├── handlers      # Update handlers
      │   ├── helpers       # Helper functions
      │   ├── keyboards     # Keyboard builders
      │   ├── middlewares   # Bot middlewares
      │   ├── context.ts    # Context object definition
      │   ├── i18n.ts       # Internationalization setup
      │   └── index.ts      # Main bot entry point
      ├── server # Web server code
      │   ├── middlewares   # Server middlewares
      │   ├── environment   # Server environment setup
      │   └── index.ts      # Server entry point
      ├── config.ts # Application config
      ├── logger.ts # Logging setup (powered by [pino](https://github.com/pinojs/pino))
      └── main.ts   # Application entry point

Deploy Options

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]:ccashwell/tg-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. Environment Variables Setup

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

# development
cp .env.example .env.bot.dev

# production
cp .env.example .env.bot.prod

Open the newly created .env.bot.dev and .env.bot.prod files and set the BOT_TOKEN environment variable.

4. Launch 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):

docker compose up

Production Mode:

Set DEBUG environment variable to false in your .env file.

Start the bot in production mode:

docker compose -f compose.yml -f compose.prod.yml up

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]:ccashwell/tg-bot-template.git
git remote update

2. Merge deployment setup

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

3. 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 the BOT_TOKEN environment variable.

4. 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 Vercel CLI:

   npm i -g vercel

   Create a project:

   vercel link

   Set NODEJS_HELPERS environment variable to 0:

   vercel env add NODEJS_HELPERS

   Set BOT_MODE environment variable to webhook:

   vercel env add BOT_MODE

   Set BOT_TOKEN environment variable:

   vercel env add BOT_TOKEN --sensitive

   Set BOT_WEBHOOK_SECRET environment variable to a random secret token:

   # Generate and set secret token using Node
   node -e "console.log(crypto.randomBytes(256*0.75).toString('base64url'))" | vercel env add BOT_WEBHOOK_SECRET --sensitive production

   # OR using Python
   python3 -c "import secrets; print(secrets.token_urlsafe(256))" | vercel env add BOT_WEBHOOK_SECRET --sensitive production

   # OR set manually:
   vercel env add BOT_WEBHOOK_SECRET --sensitive

   Deploy your bot:

   vercel

   After successful deployment, set up a webhook to connect your Vercel app with Telegram, modify the below URL to your credentials and visit it from your browser:

   https://APP_NAME.vercel.app/BOT_TOKEN
   

Environment Variables

Variable	Type	Description
BOT_TOKEN	String	Telegram Bot API token obtained from @BotFather.
BOT_MODE	String	Specifies method to receive incoming updates (polling or webhook).
DATABASE_URL	String	Database connection.
LOG_LEVEL	String	Optional. Specifies the application log level. Use info for general logging. Check the Pino documentation for more log level options. Defaults to info.
DEBUG	Boolean	Optional. Enables debug mode. You may use config.isDebug flag to enable debugging functions.
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.
SERVER_HOST	String	Optional in polling mode. Specifies the server hostname. Defaults to 0.0.0.0.
SERVER_PORT	Number	Optional in polling mode. 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.