node-telegram-bot-api/doc/usage.md

Usage

1. Events
2. WebHooks
3. Sending files

---

Events

TelegramBot is an event-emitter that emits the following events:

1. message: Received a new incoming Message of any kind
2. Depending on the properties of the Message, one of these events will ALSO be emitted: text, audio, document, photo, sticker, video, voice, contact, location, new_chat_participant, left_chat_participant, new_chat_title, new_chat_photo, delete_chat_photo, group_chat_created
3. callback_query: Received a new incoming Callback Query
4. inline_query: Received a new incoming Inline Query
5. chosen_inline_result: Received result of an inline query i.e. ChosenInlineResult
6. channel_post: Received a new incoming channel post of any kind
7. edited_message: Received a new version of a message that is known to the bot and was edited
8. edited_message_text
9. edited_message_caption
10. edited_channel_post: Received a new version of a channel post that is known to the bot and was edited
11. edited_channel_post_text
12. edited_channel_post_caption

Tip: Its much better to listen a specific event rather than on message in order to stay safe from the content.

Tip: Bot must be enabled on inline mode for receive some messages.

---

WebHooks

Telegram only supports HTTPS connections to WebHooks. Therefore, in order to set a WebHook, you will need a SSL certificate. Since August 29, 2015 Telegram supports self-signed ones, thus, you can generate them:

# Our private cert will be key.pem, keep this file private
$ openssl genrsa -out key.pem 2048

# Our public certificate will be crt.pem
$ openssl req -new -sha256 -key key.pem -out crt.pem

Once they are generated, the crt.pem should be uploaded, when setting up your webhook. For example,

bot.setWebHook("public-url.com", {
  certificate: "path/to/crt.pem", // Path to your crt.pem
});

Note: If you encounter an error, like Error: error:0906D06C:PEM routines:PEM_read_bio:no start line, you may want to proceed to this issue for more information.

---

Sending files

The library makes it easy to get started sending files. By default, you may provide a file-path and the library will handle reading it for you. For example,

bot.sendAudio(chatId, "path/to/audio.mp3");

You may also pass in a Readable Stream from which data will be piped. For example,

const stream = fs.createReadStream("path/to/audio.mp3");
bot.sendAudio(chatId, stream);

You may also pass in a Buffer containing the contents of your file. For example,

const buffer = fs.readFileSync("path/to/audio.mp3"); // sync! that's sad! :-( Just making a point!
bot.sendAudio(chatId, buffer);

If you already have a File ID, you earlier retrieved from Telegram, you may pass it in, for example:

const fileId = getFileIdSomehow();
bot.sendAudio(chatId, fileId);

Some API methods, such as SendPhoto, allow passing a HTTP URL, that the Telegram servers will use to download the file. For example,

const url = "https://telegram.org/img/t_logo.png";
bot.sendPhoto(chatId, url);

Performance Issue:

To support providing file-paths to methods that send files involves performing a file operation, i.e. fs.existsSync(), that checks for the existence of the file at the provided path. While the cost of this operation might be negligible in most use cases, if you want to squeeze the best performance out of this library, you may wish to disable this behavior.

This will mean that you will NOT be able to pass in file-paths. You will have to use Streams or Buffers to provide the file contents.

Disabling this behavior:

const bot = new TelegramBot(token, {
  filepath: false,
});