FazzGram 🚀

Full-featured Telegram Bot API library for Node.js — Simple, powerful, and developer-friendly.

Supports Bot API 10.0 — the latest Telegram Bot API with all methods, types, and update types.

Install

npm install fazzgram
# or clone this repo and run:
npm install

Quick Start

const { FazzGram, Markup } = require('fazzgram');

const bot = new FazzGram('YOUR_BOT_TOKEN');

bot.command('start', (ctx) => ctx.reply('Hello! 👋'));

bot.launch();

Core Concepts

FazzGram(token, options?)

The main bot class. Creates an instance with full API access.

| Option | Type | Default | Description | |---|---|---|---| | baseUrl | string | Telegram API | Custom Bot API server | | timeout | number | 30000 | Request timeout (ms) | | retries | number | 3 | Auto-retry on failure |

Handlers

Commands

bot.command('start', (ctx) => ctx.reply('Started!'));
bot.command(['help', 'h'], (ctx) => ctx.reply('Help!'));

Text / Pattern matching

bot.hears('hello', (ctx) => ctx.reply('Hi!'));
bot.hears(/buy/i, (ctx) => ctx.reply('Here is our shop!'));

Callback queries (inline buttons)

bot.action('confirm', (ctx) => {
  ctx.answerCallbackQuery('Confirmed!');
  ctx.editMessageText('✅ Done');
});

// Pattern match
bot.action(/^item_(\d+)$/, (ctx) => {
  const id = ctx.match[1]; // captured group
  ctx.reply(`You clicked item ${id}`);
});

Update types

bot.on('message', ctx => { ... });
bot.on('callback_query', ctx => { ... });
bot.on('inline_query', ctx => { ... });
bot.on('poll_answer', ctx => { ... });
bot.on('chat_member', ctx => { ... });
bot.on('my_chat_member', ctx => { ... });
bot.on('chat_join_request', ctx => { ... });
bot.on('business_message', ctx => { ... });
bot.on('business_connection', ctx => { ... });
bot.on('guest_message', ctx => { ... });
bot.on('managed_bot', ctx => { ... });
// ...and more

Middleware

bot.use(async (ctx, next) => {
  console.log(`Update from @${ctx.from?.username}`);
  await next(); // call next middleware or handler
});

Context (ctx)

Every handler receives a context object with:

Properties

| Property | Description | |---|---| | ctx.update | Raw Telegram Update object | | ctx.message | Current message | | ctx.callbackQuery | Current callback query | | ctx.inlineQuery | Current inline query | | ctx.chat | Chat object | | ctx.from | Sender user object | | ctx.chatId | Chat ID shortcut | | ctx.userId | User ID shortcut | | ctx.text | Message text shortcut | | ctx.match | Regex match result (from hears/action) | | ctx.bot | Bot instance | | ctx.api | Full API methods |

Reply shortcuts

ctx.reply('Hello')                          // text reply
ctx.replyHTML('<b>Bold</b>')                // HTML
ctx.replyMarkdown('*Bold*')                 // MarkdownV2
ctx.replyWithPhoto('https://...')           // photo
ctx.replyWithAudio(audioFile)              // audio
ctx.replyWithVideo(videoFile)              // video
ctx.replyWithDocument(docFile)             // document
ctx.replyWithAnimation(gifFile)            // GIF/animation
ctx.replyWithSticker(stickerId)            // sticker
ctx.replyWithVoice(voiceFile)              // voice
ctx.replyWithVideoNote(videoNote)          // video note
ctx.replyWithLocation(lat, lng)            // location
ctx.replyWithVenue(lat, lng, title, addr)  // venue
ctx.replyWithContact(phone, name)          // contact
ctx.replyWithPoll(question, options)       // poll
ctx.replyWithDice()                        // dice
ctx.replyWithMediaGroup(media)             // album
ctx.sendChatAction('typing')               // chat action
ctx.typing()                               // typing shortcut

Edit / delete shortcuts

ctx.editMessageText('New text')
ctx.editMessageCaption('New caption')
ctx.editMessageReplyMarkup(newKeyboard)
ctx.deleteMessage()
ctx.pinMessage()

Callback query shortcuts

ctx.answerCallbackQuery('Toast notification')
ctx.notify('Short toast')
ctx.alert('Modal alert popup')

Inline query shortcut

ctx.answerInlineQuery(results)

Join request shortcuts

ctx.approveChatJoinRequest()
ctx.declineChatJoinRequest()

Markup Builder

Inline Keyboard

const { Markup } = require('fazzgram');

// Simple
Markup.inlineKeyboard([
  [Markup.button.callback('Click me', 'action_1')],
  [Markup.button.url('Open URL', 'https://t.me')],
]);

// All button types
Markup.button.callback(text, data)
Markup.button.url(text, url)
Markup.button.webApp(text, url)
Markup.button.login(text, url)
Markup.button.switchInline(text, query)
Markup.button.switchToCurrentChat(text, query)
Markup.button.copyText(text, copyText)
Markup.button.pay(text)
Markup.button.game(text)

Reply Keyboard

Markup.keyboard([
  ['Button 1', 'Button 2'],
  ['Button 3'],
], { resize: true, oneTime: true });

Remove Keyboard

Markup.removeKeyboard()

Force Reply

Markup.forceReply({ placeholder: 'Type here...' })

Launch Modes

Long Polling (default)

bot.launch();

// With options:
bot.launch({
  polling: {
    timeout: 30,
    allowedUpdates: ['message', 'callback_query'],
  }
});

Standalone Webhook Server

bot.launch({
  webhook: {
    url: 'https://yourdomain.com',
    port: 3000,
    secretToken: 'my-secret',
  }
});

Express Integration

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', bot.webhookMiddleware({ secretToken: 'my-secret' }));

app.listen(3000);

Direct API Access

Every Telegram Bot API method is available via bot.api.* or ctx.api.*:

// Sending
await bot.api.sendMessage({ chat_id: 123, text: 'Hi' });
await bot.api.sendPhoto({ chat_id: 123, photo: 'file_id_or_url' });
await bot.api.sendDocument({ chat_id: 123, document: fs.createReadStream('file.pdf') });

// Chat management
await bot.api.banChatMember({ chat_id, user_id });
await bot.api.promoteChatMember({ chat_id, user_id, can_delete_messages: true });
await bot.api.setChatTitle({ chat_id, title: 'New Title' });

// Stickers
await bot.api.getStickerSet({ name: 'Animals' });
await bot.api.createNewStickerSet({ ... });

// Payments
await bot.api.sendInvoice({ ... });
await bot.api.refundStarPayment({ ... });

// Business
await bot.api.setBusinessAccountName({ ... });
await bot.api.getBusinessAccountStarBalance({ ... });

// Stories
await bot.api.postStory({ ... });
await bot.api.editStory({ ... });

// Managed bots
await bot.api.getManagedBotToken({ ... });

// Gifts
await bot.api.getAvailableGifts();
await bot.api.sendGift({ ... });

// File URL helper (not a Telegram method — FazzGram built-in)
const url = await bot.api.getFileUrl('file_id');

File Uploads

const fs = require('fs');

// From URL
ctx.replyWithPhoto('https://example.com/photo.jpg');

// From file_id (Telegram already has it)
ctx.replyWithPhoto('AgACAgIAAxkBAAI...');

// From local path (FazzGram detects this automatically)
ctx.replyWithDocument('/path/to/file.pdf');

// From Buffer
ctx.replyWithPhoto(Buffer.from(imageData));

// From ReadStream
ctx.replyWithAudio(fs.createReadStream('song.mp3'), { title: 'My Song' });

Error Handling

// Global catch
bot.catch((err, ctx) => {
  console.error('Error:', err.message, 'code:', err.code);
  ctx?.reply('Something went wrong!').catch(() => {});
});

// Per-handler try/catch
bot.command('safe', async (ctx) => {
  try {
    await ctx.reply('Hello!');
  } catch (err) {
    console.error(err);
  }
});

All Supported Methods (Bot API 10.0)

Updates

getUpdates · setWebhook · deleteWebhook · getWebhookInfo

Messages

sendMessage · forwardMessage · forwardMessages · copyMessage · copyMessages · sendPhoto · sendLivePhoto · sendAudio · sendDocument · sendVideo · sendAnimation · sendVoice · sendVideoNote · sendPaidMedia · sendMediaGroup · sendLocation · sendVenue · sendContact · sendPoll · sendChecklist · sendDice · sendMessageDraft · sendChatAction

Editing

editMessageText · editMessageCaption · editMessageMedia · editMessageLiveLocation · stopMessageLiveLocation · editMessageChecklist · editMessageReplyMarkup · stopPoll · deleteMessage · deleteMessages · deleteMessageReaction · deleteAllMessageReactions · approveSuggestedPost · declineSuggestedPost

Users & Chats

getMe · getChat · getChatAdministrators · getChatMemberCount · getChatMember · getUserProfilePhotos · getUserProfileAudios · getFile · getFileUrl · getUserChatBoosts · getBusinessConnection

Chat Management

banChatMember · unbanChatMember · restrictChatMember · promoteChatMember · setChatAdministratorCustomTitle · setChatMemberTag · banChatSenderChat · unbanChatSenderChat · setChatPermissions · exportChatInviteLink · createChatInviteLink · editChatInviteLink · createChatSubscriptionInviteLink · editChatSubscriptionInviteLink · revokeChatInviteLink · approveChatJoinRequest · declineChatJoinRequest · setChatPhoto · deleteChatPhoto · setChatTitle · setChatDescription · pinChatMessage · unpinChatMessage · unpinAllChatMessages · leaveChat · setChatStickerSet · deleteChatStickerSet

Forum Topics

getForumTopicIconStickers · createForumTopic · editForumTopic · closeForumTopic · reopenForumTopic · deleteForumTopic · unpinAllForumTopicMessages · editGeneralForumTopic · closeGeneralForumTopic · reopenGeneralForumTopic · hideGeneralForumTopic · unhideGeneralForumTopic · unpinAllGeneralForumTopicMessages

Reactions

setMessageReaction · deleteMessageReaction · deleteAllMessageReactions

Stickers

sendSticker · getStickerSet · getCustomEmojiStickers · uploadStickerFile · createNewStickerSet · addStickerToSet · setStickerPositionInSet · deleteStickerFromSet · replaceStickerInSet · setStickerEmojiList · setStickerKeywords · setStickerMaskPosition · setStickerSetTitle · setStickerSetThumbnail · setCustomEmojiStickerSetThumbnail · deleteStickerSet

Inline Mode

answerInlineQuery · answerWebAppQuery · savePreparedInlineMessage · savePreparedKeyboardButton · answerGuestQuery

Payments

sendInvoice · createInvoiceLink · answerShippingQuery · answerPreCheckoutQuery · getMyStarBalance · getStarTransactions · refundStarPayment · editUserStarSubscription

Bot Settings

setMyCommands · deleteMyCommands · getMyCommands · setMyName · getMyName · setMyDescription · getMyDescription · setMyShortDescription · getMyShortDescription · setMyProfilePhoto · removeMyProfilePhoto · setChatMenuButton · getChatMenuButton · setMyDefaultAdministratorRights · getMyDefaultAdministratorRights

Games

sendGame · setGameScore · getGameHighScores

Gifts & Stars

getAvailableGifts · sendGift · giftPremiumSubscription · convertGiftToStars · upgradeGift · transferGift · getUserGifts · getChatGifts

Stories

postStory · repostStory · editStory · deleteStory

Business

readBusinessMessage · deleteBusinessMessages · setBusinessAccountName · setBusinessAccountUsername · setBusinessAccountBio · setBusinessAccountProfilePhoto · removeBusinessAccountProfilePhoto · setBusinessAccountGiftSettings · getBusinessAccountStarBalance · transferBusinessAccountStars · getBusinessAccountGifts

Managed Bots

getManagedBotToken · replaceManagedBotToken · getManagedBotAccessSettings · setManagedBotAccessSettings

Verification

verifyUser · verifyChat · removeUserVerification · removeChatVerification

Other

answerCallbackQuery · setPassportDataErrors · getUserPersonalChatMessages · logOut · close · setUserEmojiStatus

License

MIT