Getting Started

Create your first bot in minutes. (Scroll down for a Deno guide.)

Getting Started on Node.js

This guide assumes that you have Node.js installed, and npm should come with it. If you don’t know what these things are, check out our Introduction!

Create a new TypeScript project and install the grammy package. Do this by opening a terminal and typing:

# Create a new directory and change into it.
mkdir my-bot
cd my-bot

# Set up TypeScript (skip if you use JavaScript).
npm install -D typescript
npx tsc --init

# Install grammY.
npm install grammy

# Create a new directory and change into it.
mkdir my-bot
cd my-bot

# Set up TypeScript (skip if you use JavaScript).
yarn add typescript -D
npx tsc --init

# Install grammY.
yarn add grammy

# Create a new directory and change into it.
mkdir my-bot
cd my-bot

# Set up TypeScript (skip if you use JavaScript).
pnpm add -D typescript
npx tsc --init

# Install grammY.
pnpm add grammy

Create a new empty text file, e.g. called bot.ts. Your folder structure should now look like this:

.
├── bot.ts
├── node_modules/
├── package.json
├── package-lock.json
└── tsconfig.json

Now, it’s time to open Telegram to create a bot account, and obtain an authentication token for it. Talk to @BotFather to do this. The authentication token looks like 123456:aBcDeF_gHiJkLmNoP-q.

Got the token? You can now code your bot in the bot.ts file. You can copy the following example bot into that file, and pass your token to the Bot constructor:

import { Bot } from "grammy";

// Create an instance of the `Bot` class and pass your authentication token to it.
const bot = new Bot(""); // <-- put your authentication token between the ""

// You can now register listeners on your bot object `bot`.
// grammY will call the listeners when users send messages to your bot.

// Handle the /start command.
bot.command("start", (ctx) => ctx.reply("Welcome! Up and running."));
// Handle other messages.
bot.on("message", (ctx) => ctx.reply("Got another message!"));

// Now that you specified how to handle messages, you can start your bot.
// This will connect to the Telegram servers and wait for messages.

// Start the bot.
bot.start();

const { Bot } = require("grammy");

// Create an instance of the `Bot` class and pass your authentication token to it.
const bot = new Bot(""); // <-- put your authentication token between the ""

// You can now register listeners on your bot object `bot`.
// grammY will call the listeners when users send messages to your bot.

// Handle the /start command.
bot.command("start", (ctx) => ctx.reply("Welcome! Up and running."));
// Handle other messages.
bot.on("message", (ctx) => ctx.reply("Got another message!"));

// Now that you specified how to handle messages, you can start your bot.
// This will connect to the Telegram servers and wait for messages.

// Start the bot.
bot.start();

Compile the code by running

npx tsc

in your terminal. This generates the JavaScript file bot.js.

You can now run the bot by executing

node bot.js

in your terminal. Done! 🎉

Head over to Telegram to watch your bot respond to messages!

Enabling Logging

You can enable basic logging by running

export DEBUG="grammy*"

in your terminal before you execute node bot.js. This makes it easier to debug your bot.

Getting Started on Deno

This guide assumes that you have Deno installed.

Create a new directory somewhere and create a new empty text file in it, e.g. called bot.ts.

Now, it’s time to open Telegram to create a bot account, and obtain an authentication token for it. Talk to @BotFather to do this. The authentication token looks like 123456:aBcDeF_gHiJkLmNoP-q.

Got the token? You can now code your bot in the bot.ts file. You can copy the following example bot into that file, and pass your token to the Bot constructor:

import { Bot } from "https://deno.land/x/grammy@v1.11.2/mod.ts";

// Create an instance of the `Bot` class and pass your authentication token to it.
const bot = new Bot(""); // <-- put your authentication token between the ""

// You can now register listeners on your bot object `bot`.
// grammY will call the listeners when users send messages to your bot.

// Handle the /start command.
bot.command("start", (ctx) => ctx.reply("Welcome! Up and running."));
// Handle other messages.
bot.on("message", (ctx) => ctx.reply("Got another message!"));

// Now that you specified how to handle messages, you can start your bot.
// This will connect to the Telegram servers and wait for messages.

// Start the bot.
bot.start();

You can now run the bot by executing

deno run --allow-net bot.ts

in your terminal. Done! 🎉

Head over to Telegram to watch your bot respond to messages!

Enabling Logging

You can enable basic logging by running

export DEBUG="grammy*"

in your terminal before you run your bot. This makes it easier to debug your bot.

You now need to run the bot using

deno run --allow-net --allow-env bot.ts

so grammY can detect that DEBUG is set.