Skip to content

Latest commit

 

History

History
408 lines (320 loc) · 11.2 KB

README.md

File metadata and controls

408 lines (320 loc) · 11.2 KB
Raw

Telegram Suggest Bot

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:
  • Examples:

Usage

Follow these steps to set up and run your own bot:

  1. Create a New Repository

    Start by creating a new repository using 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:

    pnpm install

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

    pnpm run dev

    Production Mode:

    Install Vercel CLI:

    pnpm i -g vercel

    Create a project:

    vercel link

    Set NODEJS_HELPERS environment variable to 0:

    vercel env add NODEJS_HELPERS

    Set BOT_TOKEN environment variable:

    vercel env add BOT_TOKEN --sensitive

    Set BOT_WEBHOOK_SECRET environment variable to a random secret token:

    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

List of Available Commands

  • pnpm run lint — Lint source code.
  • pnpm run format — Format source code.
  • pnpm run typecheck — Run type checking.
  • pnpm run dev — Start the bot in development mode.
  • pnpm run start — Start the bot.
  • pnpm run 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
  1. Merge deployment setup
git merge template/deploy/docker-compose -X theirs --squash --no-commit --allow-unrelated-histories
  1. 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
  1. Merge deployment setup
git merge template/deploy/vercel -X theirs --squash --no-commit --allow-unrelated-histories
  1. 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
  1. Merge example
git merge template/example/plugin-conversations -X theirs --squash --no-commit --allow-unrelated-histories
  1. Install dependencies
pnpm i @grammyjs/conversations
  1. 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
  1. Merge example
git merge template/example/plugin-runner -X theirs --squash --no-commit --allow-unrelated-histories
  1. Install dependencies
pnpm i @grammyjs/runner
  1. Follow the usage instructions in the example/plugin-runner branch.

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 [email protected]:bot-base/telegram-bot-template.git
git remote update
  1. Merge example
git merge template/example/orm-prisma -X theirs --squash --no-commit --allow-unrelated-histories
  1. Install dependencies
pnpm i -D prisma
pnpm i @prisma/client
  1. Follow the usage instructions in the example/orm-prisma 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
  1. Merge example
git merge template/example/runtime-bun -X theirs --squash --no-commit --allow-unrelated-histories
  1. Install dependencies
# remove Node-related dependencies
pnpm r @types/node tsx tsc-watch

# install dependencies
bun i

# remove pnpm lockfile
rm package-lock.json

# install bun typings
bun add -d @types/bun
  1. 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.
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_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.