diff --git a/guide/002-listen-and-respond.md b/guide/002-listen-and-respond.md index 074a743..dcd2115 100644 --- a/guide/002-listen-and-respond.md +++ b/guide/002-listen-and-respond.md @@ -68,3 +68,29 @@ bot.on(message("text"), async ctx => { await ctx.sendMessage("Hello!"); }); ``` + +You can also listen to other updates like this. + +- Command + +```TS (Node) +bot.command('commandName',async ctx=>{ + await ctx.reply("Hello"); +}); +``` + +- Message + +```TS (Node) +bot.hears('Hi',async ctx=>{ + await ctx.reply("Hello"); +}); +``` + +- Callback Query (Inline Keyboard) + +```TS (Node) +bot.action('action',async ctx=>{ + await ctx.answerCbQuery("Hello"); +}); +``` diff --git a/guide/???-formatting.md b/guide/003-sending-message.md similarity index 65% rename from guide/???-formatting.md rename to guide/003-sending-message.md index 70beda8..4e143dc 100644 --- a/guide/???-formatting.md +++ b/guide/003-sending-message.md @@ -1,12 +1,40 @@ +# `[003]` Sending Message + +When you want to send user a message then you need to call function to send the message. + +In this artice, we'll talk about how can we send a message using our bot. + +See also: [official reference to sendMessage](https://core.telegram.org/bots/api#send-message) + +### Sending Message using Context (Update Received) + +```TS (Node) +bot.hears("hello",async ctx=>{ + ctx.reply("Hi"); +}) +``` + +### Sending From Direct API Call + +```TS (Node) +// You can get chatId from update +bot.telegram.sendMessage(chatId,"Hello World!") +``` + +### Advanced + +You can pass options to do more actions like `reply_to_message_id` and many more. +You can see official reference given by Telegram to know about usage of options. + # Formatting messages > The Bot API supports basic formatting for messages. You can use bold, italic, underlined, strikethrough, and spoiler text, as well as inline links and pre-formatted code in your bots' messages. Telegram clients will render them accordingly. [[Read more]](https://core.telegram.org/bots/api#formatting-options) There are 3 ways to format messages sent to Telegram with Telegraf: -* [Markdown](#markdown) -* [HTML](#html) -* [fmt helpers](#fmt) (recommended!) +- [Markdown](#markdown) +- [HTML](#html) +- [fmt helpers](#fmt) (recommended!) ## Markdown @@ -165,3 +193,82 @@ link("Link text", URL); ```TS (Node) mention("User", userId); ``` + +# Reply Markup + +You can pass `reply_markup` in options. + +There are two types of markup available (as of Bot API 6.6) + +1. Inline Keyboard + + Inline Keyboard looks like this : + + + You can use Telegraf's Markup for making Inline Keyboard easily. + + ```TS (Node) + import { Markup } from "telegraf" + + bot.on("message",async ctx=>{ + await ctx.reply("This is a awsome Inline Keyboard",Markup.inlineKeyboard([ + Markup.button.callback('Hey','hey') + ])) + }); + ``` + + **How to use More Options with Markup?** + + ```TS (Node) + bot.on("message", async (ctx) => { + await ctx.reply("This is a awsome Inline Keyboard", { + reply_markup: Markup.inlineKeyboard([Markup.button.callback("Hey", "hey")]), + parse_mode: "HTML", + }); + }); + ``` + +2. Keyboard + + Keyboard Looks Like this: + + + You can just do same as inline but Keyboard doesn't support Markup (by Telegraf) + + ```TS (Node) + bot.on("message", async (ctx) => { + await ctx.reply("This is a awsome Keyboard", { + reply_markup: { + keyboard:[ + ['Row'], // row 1 + ['Row 2'] // row 2 + ] + }, + parse_mode: "HTML", + }); + }); + ``` + + You can even send keyboard with options. + + ```TS (Node) + bot.on("message", async (ctx) => { + await ctx.reply("This is a awsome Keyboard", { + reply_markup: { + keyboard:[ + ['Row'], // row 1 + [{text:'Share Contact',request_contact:true}] // row 2 + ] + }, + parse_mode: "HTML", + }); + }); + ``` + +You can use all these options also in calling `bot.telegram.sendMessage()` + +```TS (Node) +bot.telegram.sendMessage(chatId,"Wow",{ + parse_mode:"HTML" +}); +``` diff --git a/guide/004-calling-api.md b/guide/004-calling-api.md new file mode 100644 index 0000000..63fba58 --- /dev/null +++ b/guide/004-calling-api.md @@ -0,0 +1,15 @@ +# `[004]` **Calling API** + +In Telegraf, it is possible to call all the possible api methods using `bot.telegram.*` + +\* here refers to `methodName` + +### **How APIs are called** + +Telegraf sends request to Bot API and Telegraf supports all the methods available for **Bot API**. + +**Bot API** further calls the **MtProto** Server to send that request to **Telegram**'s **Servers**. + +**MtProto** contains more methods and data than **Bot API**. + +> Note: **Telegraf** only Supports **Bot API** and its methods. diff --git a/guide/005-context-and-middleware.md b/guide/005-context-and-middleware.md new file mode 100644 index 0000000..aa3afe6 --- /dev/null +++ b/guide/005-context-and-middleware.md @@ -0,0 +1,138 @@ +# `[005]` Context and Middleware + +> Context Class is a vey important part of Telegraf ([API REFERENCE](https://telegraf.js.org/classes/Context.html)) +> Whenever you register a listener on your bot object, this listener will receive a context object. + +```javascript +bot.on("message", (ctx) => { + // `ctx` is the `Context` class. +}); +``` + +You can use the context object to + +
    +
  1. access information about the message +
  2. perform actions in response to the message +
+ +> Context is called ctx commonly in short form. + +### Information + +**Access Information About the Message, Chat , etc** + +```javascript +bot.on("message", (ctx) => { + const txt = ctx.message.text; // undefined if text is empty + const sender = ctx.from.id; // the user who sent the message + const fname = ctx.from.first_name; // the first name of the user who sent the message + const message_id = ctx.message.message_id; // the id of the message + + // There are many more that you can get through your IDE or searching telegraf.js.org +}); +``` + +### Action + +**Do actions with the context class** + +```javascript +bot.on("message", (ctx) => { +ctx.replyWithMarkdownV2("*Hello*); +ctx.replyWithHTML("Hello*"); + +ctx.forwardMessage("chat"); +// There are many more functions that you can get through your IDE or searching telegraf.js.org +}); +``` + +# Why use context actions ? + +When you use the telegram's plain API then you do : + +```javascript +bot.on("message", async (ctx) => { + const chatId = ctx.from.id; + const text = "New Message"; + await bot.telegram.sendMessage(chatId, text); +}); +``` + +**With Context Method** + +```javascript +bot.on("message", async (ctx) => { + ctx.replyWithHTML("New Message"); +}); +``` + +With context your code is more consized and neat 👍 + +# How Context Objects Are Created + +Whenever your bot receives a new message from Telegram, it is wrapped in an update object. In fact, update objects can not only contain new messages, but also all other sorts of things, such as edits to messages, poll answers, and much more. + +A fresh context object is created exactly once for every incoming update. Contexts for different updates are completely unrelated objects, they only reference the same bot information via ctx.me. + +The same context object for one update will be shared by all installed [middleware](#Middleware) on the bot. + +# Customizing the Context Class + +You can install your own properties on the context object if you want. + +# Middleware + +Middleware ! What is this ? 🤔 +In short, when you add any listner the middleware will be called then your listner callback will be fired. + +Example : + +```javascript +bot.use(async (ctx, next) => { + if ((ctx.from.id = "bad_user")) { + ctx.replyWithMarkdownV2("You are bad user"); + } else { + await next(); + } +}); + +bot.on("message", (ctx) => { + ctx.reply("Yay ! You passed middleware"); +}); +``` + +> **Warning** +> You must await next(); + +How does the code above worked ? + +``` +bot > middleware > listner +``` + +First the middleware will be called then the listner + +Other type of middlewares : + +```javascript +bot.on("message", (ctx, next) => {}); // This middleware will be called only on messages +``` + +### Modifing the middleware + +You can add custom properties in the context object through middleware like : + +```javascript +bot.use((ctx,next)=>{ +ctx.custom.replyToMessage = (text)=>{ +ctx.replyWithHTML(text,{reply_to_message_id : ctx.message.message_id}); +} + +await next(); +}); + +bot.hears("hii",ctx=>{ +ctx.custom.replyToMessage("Wow"); +}) +``` diff --git a/guide/006-filters.md b/guide/006-filters.md new file mode 100644 index 0000000..ce23997 --- /dev/null +++ b/guide/006-filters.md @@ -0,0 +1,46 @@ +# `[006]` Filters in Telegraf + +You can use `bot.on` listener with `message("text")` or any other filter + +> **Note**
+> bot.on("message"|"other_type") has been deprecated. It may be removed in future versions. So prefer new filters. + +# Available Types + +You can see all available filters [here](https://telegraf.js.org/classes/Telegraf-1.html#on-3) or your code editor will suggest you. + +# Example + +Here is an example how to use filters + +```TS (Node) +import { message } from "telegraf/filters"; + +bot.on(message("text"), async (ctx, next) => { + // next is added because other listners below this wont work if await next(); is not added + await next(); +}); +``` + +### More Details + +You can also add multiple listeners using array like given below: + +```TS (Node) +bot.on([message("text"), message("photo")], async (ctx) => { + ctx.reply("Received Text or Photo"); +}); +``` + +### `ctx.has` checks with filters + +You can check if ctx has a filter like this. + +```TS (Node) +if(ctx.has(message("text")){ +ctx.reply("It is text"); +} +else if(ctx.has(message("photo")){ +ctx.reply("It is photo"); +} +``` diff --git a/guide/???-broadcasting.md b/guide/broadcasting.md similarity index 100% rename from guide/???-broadcasting.md rename to guide/broadcasting.md