Telegram Game & Mini App Client (y0red-Bot)

A modular and extensible Node.js library to create powerful Telegram Bots, Games, and Mini Apps. This package provides a clean Bot class, intuitive keyboard builders, and simple methods for sending rich media.

Features

• Modular Design: High-level bot logic is separate from the low-level API client.
• Extensible: Easily register handlers for commands, callback queries, and messages.
• Bot Commands: Set the list of commands (/start) users see in the Telegram UI.
• Deep Linking: Automatically parses payloads from t.me/YourBot?start=payload links.
• Intuitive Keyboard Builders: Chainable Keyboard and InlineKeyboard classes to build any kind of bot keyboard.
• Rich Media: Simple methods for sending messages with HTML, MarkdownV2, and images.
• Webhook Ready: Includes a simple-to-use Express.js middleware.

Installation

npm install tg-app-client express

How to Use

1. Create Your Bot File (my-bot.js)

import express from 'express';
import { Bot, Keyboard, InlineKeyboard } from 'tg-app-client';

const BOT_TOKEN = 'YOUR_SUPER_SECRET_BOT_TOKEN';
const PORT = 3000;

const bot = new Bot(BOT_TOKEN);

// Set the commands users will see
bot.setCommands([
  { command: 'start', description: 'Start the bot' },
  { command: 'help', description: 'Get help' },
]);

// Handle the /start command (and deep links!)
bot.onCommand('start', (ctx) => {
  const chatId = ctx.update.message.chat.id;
  let text = 'Welcome!';
  if (ctx.payload) {
    text += `\nYou arrived with payload: ${ctx.payload}`;
  }
  
  const keyboard = new InlineKeyboard()
    .text('Say Hi', 'say_hi')
    .url('Google', '[https://google.com](https://google.com)')
    .build();

  ctx.api.sendMessage({
    chat_id: chatId,
    text: text,
    reply_markup: keyboard
  });
});

// Handle a callback query
bot.onCallbackQuery((ctx) => {
    if (ctx.update.callback_query.data === 'say_hi') {
        ctx.api.answerCallbackQuery({
            callback_query_id: ctx.update.callback_query.id,
            text: 'Hello there!',
            show_alert: true
        });
    }
});

// Start the server
const app = express();
app.use(express.json());
app.use(bot.createWebhookMiddleware());
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

2. Set Your Webhook

Use a service like ngrok during development to get a public URL.

ngrok http 3000

Then tell Telegram where to send updates:

curl "[https://api.telegram.org/bot](https://api.telegram.org/bot)<YOUR_BOT_TOKEN>/setWebhook?url=<YOUR_NGROK_URL>/webhook/<YOUR_BOT_TOKEN>"

3. Run Your Bot

node my-bot.js

API Highlights

Keyboard Builders

Create complex keyboards with a simple, chainable API.

Custom Reply Keyboard:

import { Keyboard } from 'tg-app-client';

const keyboard = new Keyboard()
  .text('Yes').text('No')
  .row()
  .requestContact('Share Contact')
  .build();

Inline Keyboard (attached to a message):

import { InlineKeyboard } from 'tg-app-client';

const keyboard = new InlineKeyboard()
  .text('Confirm', 'confirm_action')
  .text('Cancel', 'cancel_action')
  .row()
  .url('Learn More', '[https://example.com](https://example.com)')
  .build();

Sending Rich Messages

// Send a message with HTML formatting
ctx.api.sendMessage({
    chat_id: chatId,
    text: '<b>This is bold text.</b>',
    parse_mode: 'HTML'
});

// Send an image with a caption
ctx.api.sendPhoto({
    chat_id: chatId,
    photo: '[https://placehold.co/600x400](https://placehold.co/600x400)',
    caption: 'An example image.'
});