🤖 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)
• Fast and low overhead server (powered by fastify)
• Ready-to-use deployment setups:
  • Docker
  • Vercel
• Examples:
  • Prisma ORM
  • grammY plugins:
    • Conversations
    • Runner
  • Web Apps:
    • Vanilla (No frameworks)
    • Vue

Usage

1. Create a new repository using this template.

2. Create an environment variables file:

cp .env.example .env

3. Set BOT_TOKEN environment variable in .env file.

4. Launch bot

   Development mode:

   # 1. Install dependencies
   npm i
   
   # 2. Run bot (in watch mode)
   npm run dev

   Production mode:

   1. Deploy to Vercel.
   2. 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
   

List of available commands

• npm run lint — Lint source code.
• npm run format — Format source code.
• npm run typecheck — Runs type checking.
• npm run dev — Starts the bot in development mode.
• npm run start — Starts the bot.
• npm run start:force — Starts the bot without type checking.

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 git@github.com: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

Vercel (vercel.com)

Branch: deploy/vercel (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template git@github.com: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

Examples

Prisma ORM (prisma.io)

Branch: example/orm-prisma (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update

2. Merge example

git merge template/example/orm-prisma -X theirs --squash --no-commit --allow-unrelated-histories

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 git@github.com: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

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 git@github.com: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

Web App (Vite, TypeScript)

Branch: example/webapp (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update

2. Merge example

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

Web App with Vue (Vue, Vite, TypeScript)

Branch: example/webapp-vue (open diff)

Use in your project:

1. Add the template repository as a remote

git remote add template git@github.com:bot-base/telegram-bot-template.git
git remote update

2. Merge example

git merge template/example/webapp-vue -X theirs --squash --no-commit --allow-unrelated-histories

Environment Variables

Variable	Type	Description
NODE_ENV	String	Application environment (development or production)
BOT_TOKEN	String	Token, get it from @BotFather.
BOT_WEBHOOK	String	Webhook endpoint, used to configure webhook in production environment.
LOG_LEVEL	String	Optional. Application log level. See Pino docs for a complete list of available log levels. Defaults to info.
BOT_SERVER_HOST	String	Optional. Server address. Defaults to 0.0.0.0.
BOT_SERVER_PORT	Number	Optional. 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).
BOT_ADMIN_USER_ID	Number or Array of Number	Optional. Administrator user ID. Commands such as /setcommands will only be available to a user with this ID. Defaults to an empty array.