Introduction
grammY makes it easy to create Telegram bots. Whether you’re a beginner or building at scale, grammY provides a simple yet powerful API that’s always up to date with the latest Telegram Bot API features.
In this guide, you’ll create your first working bot in just a few minutes.
Prerequisites
Before you begin, make sure you have:
- Node.js (version 12.20.0 or higher) or Deno installed
- A bot token from @BotFather
Getting Your Bot Token
Create a new bot
Send the /newbot command and follow the instructions.
Save your token
BotFather will give you a bot token. Keep it secret! You’ll need it in the next steps.
Creating Your First Bot
Create a new directory
mkdir my-telegram-bot
cd my-telegram-bot
Create bot.js
Create a file called bot.js with the following code:const { Bot } = require("grammy");
// Create a bot object
const bot = new Bot(""); // <-- place your bot token in this string
// Register listeners to handle messages
bot.on("message:text", (ctx) => ctx.reply("Echo: " + ctx.message.text));
// Start the bot (using long polling)
bot.start();
Replace the empty string with your actual bot token from BotFather.
Run your bot
Your bot is now running! Send it a message on Telegram and it will echo it back. Create a new directory
mkdir my-telegram-bot
cd my-telegram-bot
Initialize your project
npm init -y
npm install grammy
npm install -D typescript @types/node
npx tsc --init
Create bot.ts
Create a file called bot.ts with the following code:import { Bot } from "grammy";
// Create a bot object
const bot = new Bot(""); // <-- place your bot token in this string
// Register listeners to handle messages
bot.on("message:text", (ctx) => ctx.reply("Echo: " + ctx.message.text));
// Start the bot (using long polling)
bot.start();
Replace the empty string with your actual bot token from BotFather.
Run your bot
npx tsx bot.ts
# or compile and run
npx tsc
node bot.js
Create bot.ts
Create a file called bot.ts with the following code:import { Bot } from "https://deno.land/x/grammy/mod.ts";
// Create a bot object
const bot = new Bot(""); // <-- place your bot token in this string
// Register listeners to handle messages
bot.on("message:text", (ctx) => ctx.reply("Echo: " + ctx.message.text));
// Start the bot (using long polling)
bot.start();
Replace the empty string with your actual bot token from BotFather.
Run your bot
deno run --allow-net bot.ts
Understanding the Code
Let’s break down what each part of the code does:
Creating a Bot Instance
const bot = new Bot("YOUR_BOT_TOKEN");
Bot class is the core of grammY and represents your bot. You must provide your bot token obtained from BotFather.
Listening for Messages
bot.on("message:text", (ctx) => ctx.reply("Echo: " + ctx.message.text));
ctx (context) object contains:
ctx.message - the incoming messagectx.reply() - a method to send a replyctx.api - full access to the Telegram Bot API
Starting the Bot
This starts the bot using long polling, which continuously checks for new updates from Telegram.
Adding More Features
Now that you have a basic bot running, let’s add some common features:
Responding to Commands
import { Bot } from "grammy";
const bot = new Bot("YOUR_BOT_TOKEN");
// Handle the /start command
bot.command("start", (ctx) => {
ctx.reply("Welcome! I'm your new bot. Send me any message!");
});
// Handle the /help command
bot.command("help", (ctx) => {
ctx.reply("Send me a message and I'll echo it back!");
});
// Echo text messages
bot.on("message:text", (ctx) => {
ctx.reply("Echo: " + ctx.message.text);
});
bot.start();
Handling Different Message Types
import { Bot } from "grammy";
const bot = new Bot("YOUR_BOT_TOKEN");
// Handle text messages
bot.on("message:text", (ctx) => {
ctx.reply("You sent text: " + ctx.message.text);
});
// Handle photos
bot.on("message:photo", (ctx) => {
ctx.reply("Nice photo!");
});
// Handle stickers
bot.on("message:sticker", (ctx) => {
ctx.reply("Cool sticker!");
});
// Handle any other message type
bot.on("message", (ctx) => {
ctx.reply("Got your message!");
});
bot.start();
Using the Bot API
import { Bot } from "grammy";
const bot = new Bot("YOUR_BOT_TOKEN");
bot.command("info", async (ctx) => {
const chatId = ctx.chat.id;
// Send a message
await ctx.api.sendMessage(chatId, "Hello from the Bot API!");
// Get chat information
const chat = await ctx.api.getChat(chatId);
ctx.reply(`This chat is called: ${chat.first_name || chat.title}`);
});
bot.start();
Error Handling
It’s important to handle errors gracefully:
import { Bot } from "grammy";
const bot = new Bot("YOUR_BOT_TOKEN");
bot.command("start", (ctx) => {
ctx.reply("Hello!");
});
// Error handler
bot.catch((err) => {
const ctx = err.ctx;
console.error(`Error while handling update ${ctx.update.update_id}:`);
const e = err.error;
console.error("Error:", e);
});
bot.start();
Customizing Startup
You can customize how your bot starts:
import { Bot } from "grammy";
const bot = new Bot("YOUR_BOT_TOKEN");
bot.command("start", (ctx) => ctx.reply("Hello!"));
// Start with options
bot.start({
onStart: (botInfo) => {
console.log(`Bot @${botInfo.username} is running!`);
},
drop_pending_updates: true, // Ignore old updates
allowed_updates: ["message", "callback_query"], // Only receive these update types
});
Best Practices
Keep your token secret! Never commit your bot token to version control. Use environment variables instead:import { Bot } from "grammy";
const bot = new Bot(process.env.BOT_TOKEN!);
BOT_TOKEN="your_token_here" node bot.js
Use TypeScript for better development experience. grammY has excellent TypeScript support with full type inference. Your code editor will provide helpful autocomplete and type checking.
Next Steps
Congratulations! You’ve created your first Telegram bot with grammY.
Here’s what to explore next:
- Learn about Context and all the methods available
- Explore Middleware for handling complex logic
- Check out Plugins to extend your bot’s capabilities
- Learn about Deployment options for production
Resources