From a44eb7f1ee9349920760e2e7d22e3d395b716c56 Mon Sep 17 00:00:00 2001 From: Plusb Preco Date: Wed, 15 Feb 2017 13:59:56 +0900 Subject: [PATCH] docs: Docs improvements (#291) Feature: * Add notes about events in `api` document * Update copyright year * Cleanup docs References: * Feature request: https://github.com/yagop/node-telegram-bot-api/issues/289 * PR: https://github.com/yagop/node-telegram-bot-api/pull/291 * Requested-by: @preco21 * PR-by: @preco21 --- CONTRIBUTING.md | 31 +++--------- LICENSE.md | 2 +- README.md | 85 ++++++++++++++----------------- doc/api.hbs | 2 + doc/api.md | 2 + doc/help.md | 130 +++++++++++++++--------------------------------- doc/usage.md | 58 ++++++++------------- 7 files changed, 110 insertions(+), 200 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8774044..1f88460 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,16 +5,12 @@ Before proceeding any further, read the following documents: -1. [code of conduct][coc] -1. [software license][license] +1. [Code of Conduct][coc] +1. [License][license] -[coc]:https://github.com/yagop/node-telegram-bot-api/blob/master/CODE_OF_CONDUCT.md -[license]:https://github.com/yagop/node-telegram-bot-api/blob/master/LICENSE.md +## General Information - -### General Information - -**Updating API Reference i.e. generating `doc/api.md`:** +### Updating API Reference i.e. generating `doc/api.md` Run: @@ -22,19 +18,11 @@ Run: $ npm run gen-doc ``` - ---- - - -**Running tests:** +### Running tests Please read `test/README.md` for more information. - ---- - - -**Transpiling ES6 for older Node.js versions:** +### Transpiling ES2015 for older Node.js versions We use babel to transpile the code: @@ -42,8 +30,5 @@ We use babel to transpile the code: $ npm run build ``` - ---- - - -> E=mc² +[coc]:https://github.com/yagop/node-telegram-bot-api/blob/master/CODE_OF_CONDUCT.md +[license]:https://github.com/yagop/node-telegram-bot-api/blob/master/LICENSE.md diff --git a/LICENSE.md b/LICENSE.md index 6ae969c..6e850e0 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2015 Yago +Copyright (c) 2017 Yago Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index e62e46c..dc66ad0 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,40 @@ - [![Bot API](http://img.shields.io/badge/Bot API-v2.3.1-00aced.svg)](https://core.telegram.org/bots/api) - [![Build Status](https://travis-ci.org/yagop/node-telegram-bot-api.svg?branch=master)](https://travis-ci.org/yagop/node-telegram-bot-api) - [![Build status](https://ci.appveyor.com/api/projects/status/ujko6bsum3g5msjh/branch/master?svg=true)](https://ci.appveyor.com/project/yagop/node-telegram-bot-api/branch/master) - [![Coverage Status](https://coveralls.io/repos/yagop/node-telegram-bot-api/badge.svg?branch=master)](https://coveralls.io/r/yagop/node-telegram-bot-api?branch=master) - [![bitHound Score](https://www.bithound.io/github/yagop/node-telegram-bot-api/badges/score.svg)](https://www.bithound.io/github/yagop/node-telegram-bot-api) - [![https://telegram.me/node_telegram_bot_api](https://img.shields.io/badge/💬 Telegram-node__telegram__bot__api-blue.svg)](https://telegram.me/node_telegram_bot_api) - [![https://telegram.me/Yago_Perez](https://img.shields.io/badge/💬 Telegram-Yago__Perez-blue.svg)](https://telegram.me/Yago_Perez) +# Node.js Telegram Bot API + +[![Bot API](http://img.shields.io/badge/Bot API-v2.3.1-00aced.svg)](https://core.telegram.org/bots/api) +[![Build Status](https://travis-ci.org/yagop/node-telegram-bot-api.svg?branch=master)](https://travis-ci.org/yagop/node-telegram-bot-api) +[![Build status](https://ci.appveyor.com/api/projects/status/ujko6bsum3g5msjh/branch/master?svg=true)](https://ci.appveyor.com/project/yagop/node-telegram-bot-api/branch/master) +[![Coverage Status](https://coveralls.io/repos/yagop/node-telegram-bot-api/badge.svg?branch=master)](https://coveralls.io/r/yagop/node-telegram-bot-api?branch=master) +[![bitHound Score](https://www.bithound.io/github/yagop/node-telegram-bot-api/badges/score.svg)](https://www.bithound.io/github/yagop/node-telegram-bot-api) +[![https://telegram.me/node_telegram_bot_api](https://img.shields.io/badge/💬 Telegram-node__telegram__bot__api-blue.svg)](https://telegram.me/node_telegram_bot_api) +[![https://telegram.me/Yago_Perez](https://img.shields.io/badge/💬 Telegram-Yago__Perez-blue.svg)](https://telegram.me/Yago_Perez) Node.js module to interact with official [Telegram Bot API](https://core.telegram.org/bots/api). A bot token is needed, to obtain one, talk to [@botfather](https://telegram.me/BotFather) and create a new bot. -**Installation:** +## Install -```sh -npm install node-telegram-bot-api +```bash +npm install --save node-telegram-bot-api ``` -**Sample Usage:** +## Usage ```js -var TelegramBot = require('node-telegram-bot-api'); +const TelegramBot = require('node-telegram-bot-api'); // replace the value below with the Telegram token you receive from @BotFather -var token = 'YOUR_TELEGRAM_BOT_TOKEN'; +const token = 'YOUR_TELEGRAM_BOT_TOKEN'; // Create a bot that uses 'polling' to fetch new updates -var bot = new TelegramBot(token, { polling: true }); +const bot = new TelegramBot(token, {polling: true}); // Matches "/echo [whatever]" -bot.onText(/\/echo (.+)/, function (msg, match) { +bot.onText(/\/echo (.+)/, (msg, match) => { // 'msg' is the received Message from Telegram // 'match' is the result of executing the regexp above on the text content // of the message - var chatId = msg.chat.id; - var resp = match[1]; // the captured "whatever" + const chatId = msg.chat.id; + const resp = match[1]; // the captured "whatever" // send back the matched "whatever" to the chat bot.sendMessage(chatId, resp); @@ -40,42 +42,26 @@ bot.onText(/\/echo (.+)/, function (msg, match) { // Listen for any kind of message. There are different kinds of // messages. -bot.on('message', function (msg) { - var chatId = msg.chat.id; +bot.on('message', (msg) => { + const chatId = msg.chat.id; // send a message to the chat acknowledging receipt of their message - bot.sendMessage(chatId, "Received your message"); + bot.sendMessage(chatId, 'Received your message'); }); ``` - -* * * - - ## Documentation - * [Usage][usage] - * [Examples][examples] - * [Help Information][help] - * API Reference ([release][api-release] / [development][api-dev]) - * [Contributing to the Project][contributing] +* [Usage][usage] +* [Examples][examples] +* [Help Information][help] +* API Reference ([release][api-release] / [development][api-dev]) +* [Contributing to the Project][contributing] _**Note**: Development is done against the **master** branch. Code for the latest release resides on the **release** branch._ - -[usage]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md -[examples]:https://github.com/yagop/node-telegram-bot-api/tree/master/examples -[help]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/help.md -[api-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/api.md -[api-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/api.md -[contributing]:https://github.com/yagop/node-telegram-bot-api/tree/master/CONTRIBUTING.md - - -* * * - - -## Our Community +## Community We have a [Telegram channel][tg-channel] where we post updates on the Project. Head over and subscribe! @@ -86,15 +72,16 @@ Some things built using this library, and might interest you: * [node-telegram-bot-api-middleware](https://github.com/idchlife/node-telegram-bot-api-middleware): Middleware for node-telegram-bot-api * [teleirc](https://github.com/FruitieX/teleirc): A simple Telegram ↔ IRC gateway - -* * * - - -## License Information +## License **The MIT License (MIT)** -Copyright (c) 2015 Yago - +Copyright (c) 2017 Yago +[usage]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md +[examples]:https://github.com/yagop/node-telegram-bot-api/tree/master/examples +[help]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/help.md +[api-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/api.md +[api-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/api.md +[contributing]:https://github.com/yagop/node-telegram-bot-api/tree/master/CONTRIBUTING.md [tg-channel]:https://telegram.me/node_telegram_bot_api diff --git a/doc/api.hbs b/doc/api.hbs index 13f2af7..4f56831 100644 --- a/doc/api.hbs +++ b/doc/api.hbs @@ -1,5 +1,7 @@ # API Reference +**Note:** If you are looking for available [events](usage.md#events) or usage of api, please refer [`usage.md`](usage.md). + {{#class name="TelegramBot"~}} {{>header~}} {{>body~}} diff --git a/doc/api.md b/doc/api.md index e29e744..5a19278 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1,5 +1,7 @@ # API Reference +**Note:** If you are looking for available [events](usage.md#events) or usage of api, please refer [`usage.md`](usage.md). + ## TelegramBot diff --git a/doc/help.md b/doc/help.md index a634f01..a9a44ac 100644 --- a/doc/help.md +++ b/doc/help.md @@ -3,40 +3,23 @@ * [Common Pitfalls](#pitfalls) * [FAQs](#faqs) - -* * * - - ## Common Pitfalls -1. [Failing to receive reply with `ReplyToMessage`](#reply-to-message) - - ---- - - -**Failing to receive reply with `ReplyToMessage`** +### Failing to receive reply with `ReplyToMessage` -The user has to **manually reply** to your message, by tapping on the -bot's message and select *Reply*. +The user has to **manually reply** to your message, by tapping on the bot's message and select *Reply*. Sources: - * Issue #113: https://github.com/yagop/node-telegram-bot-api/issues/113 - - -* * * - +* Issue [#113](https://github.com/yagop/node-telegram-bot-api/issues/113) ## Frequently Asked Questions > Check out [all questions ever asked][questions] on our Github Issues. -[questions]:https://github.com/yagop/node-telegram-bot-api/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Aquestion%20 - 1. [How do I send GIFs?](#gifs) 1. [Why and When do I need a certificate when using WebHooks?](#webhook-cert) 1. [How do I know when a user leaves a chat?](#leave-chat) @@ -47,134 +30,99 @@ Sources: 1. [Can you add feature X to the library?](#new-feature) 1. [Is this scalable?](#scalable) - ---- - -**How do I send GIFs?** +### How do I send GIFs? You might be trying to send your animated GIFs using *TelegramBot#sendPhoto()*. The method mostly supports static images. As noted by the community, it seems you need to send them as documents, using *TelegramBot#sendDocument()*. - ```js -bot.sendDocument(chatId, "cat.gif"); +bot.sendDocument(chatId, 'cat.gif'); ``` Sources: - * Issue #11: https://github.com/yagop/node-telegram-bot-api/issues/11 - - ---- - +* Issue [#11](https://github.com/yagop/node-telegram-bot-api/issues/11) -**Why and When do I need a certificate when using WebHooks?** +### Why and When do I need a certificate when using WebHooks? -*Not Done. Send PR please!* +*Not done. PRs welcome!* Sources: - * Issue #63: https://github.com/yagop/node-telegram-bot-api/issues/63 - * Issue #125: https://github.com/yagop/node-telegram-bot-api/issues/125 - - ---- +* Issue [#63](https://github.com/yagop/node-telegram-bot-api/issues/63) +* Issue [#125](https://github.com/yagop/node-telegram-bot-api/issues/125) -**How do I know when a user leaves a chat?** +### How do I know when a user leaves a chat? -*Not Done. Send PR please!* +*Not done. PRs welcome!* Sources: - * Issue #248: https://github.com/yagop/node-telegram-bot-api/issues/248 - - ---- - +* Issue [#248](https://github.com/yagop/node-telegram-bot-api/issues/248) -**What does this error mean?** +### What does this error mean? -*Not Done. Send PR please!* +*Not done. PRs welcome!* Sources: - * Issue #73: https://github.com/yagop/node-telegram-bot-api/issues/73 - * Issue #99: https://github.com/yagop/node-telegram-bot-api/issues/99 - * Issue #101: https://github.com/yagop/node-telegram-bot-api/issues/101 - * Issue #107: https://github.com/yagop/node-telegram-bot-api/issues/107 - * Issue #156: https://github.com/yagop/node-telegram-bot-api/issues/156 - * Issue #170: https://github.com/yagop/node-telegram-bot-api/issues/170 - * Issue #244: https://github.com/yagop/node-telegram-bot-api/issues/244 - - ---- - +* Issue [#73](https://github.com/yagop/node-telegram-bot-api/issues/73) +* Issue [#99](https://github.com/yagop/node-telegram-bot-api/issues/99) +* Issue [#101](https://github.com/yagop/node-telegram-bot-api/issues/101) +* Issue [#107](https://github.com/yagop/node-telegram-bot-api/issues/107) +* Issue [#156](https://github.com/yagop/node-telegram-bot-api/issues/156) +* Issue [#170](https://github.com/yagop/node-telegram-bot-api/issues/170) +* Issue [#244](https://github.com/yagop/node-telegram-bot-api/issues/244) -**How do I know the selected option in reply keyboard?** +### How do I know the selected option in reply keyboard? -*Not Done. Send PR please!* +*Not done. PRs welcome!* Sources: - * Issue #108: https://github.com/yagop/node-telegram-bot-api/issues/108 - - ---- - +* Issue [#108](https://github.com/yagop/node-telegram-bot-api/issues/108) -**How do I send multiple message in correct sequence?** +### How do I send multiple message in correct sequence? -*Not Done. Send PR please!* +*Not done. PRs welcome!* Sources: - * Issue #240: https://github.com/yagop/node-telegram-bot-api/issues/240 - - ---- - +* Issue [#240](https://github.com/yagop/node-telegram-bot-api/issues/240) -**How do I run my bot behind a proxy?** +### How do I run my bot behind a proxy? -*Not Done. Send PR please!* +*Not done. PRs welcome!* Sources: - * Issue #122: https://github.com/yagop/node-telegram-bot-api/issues/122 - * Issue #253: https://github.com/yagop/node-telegram-bot-api/issues/253 - - ---- - +* Issue [#122](https://github.com/yagop/node-telegram-bot-api/issues/122) +* Issue [#253](https://github.com/yagop/node-telegram-bot-api/issues/253) -**Can you add feature X to the library?** +### Can you add feature X to the library? -*Not Done. Send PR please!* +*Not done. PRs welcome!* Sources: - * Issue #238: https://github.com/yagop/node-telegram-bot-api/issues/238 - - ---- +* Issue [#238](https://github.com/yagop/node-telegram-bot-api/issues/238) -**Is this scalable?** +### Is this scalable? -*Not Done. Send PR please!* +*Not done. PRs welcome!* Sources: - * Issue #219: https://github.com/yagop/node-telegram-bot-api/issues/219 +* Issue [#219](https://github.com/yagop/node-telegram-bot-api/issues/219) - ---- +[questions]:https://github.com/yagop/node-telegram-bot-api/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Aquestion%20 diff --git a/doc/usage.md b/doc/usage.md index 78043b0..7f6c924 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -1,13 +1,9 @@ # Usage -1. [Events](#events) -1. [WebHooks](#WebHooks) -1. [Sending files](#sending-files) -1. [Error handling](#error-handling) - - -* * * - +* [Events](#events) +* [WebHooks](#WebHooks) +* [Sending files](#sending-files) +* [Error handling](#error-handling) ## Events @@ -39,17 +35,6 @@ **Tip:** Bot must be enabled on [inline mode][inline-mode] for receive some messages. -[update]:https://core.telegram.org/bots/api#update -[message]:https://core.telegram.org/bots/api#message -[callback-query]:https://core.telegram.org/bots/api#callbackquery -[inline-query]:https://core.telegram.org/bots/api#inlinequery -[chosen-inline-result]:https://core.telegram.org/bots/api#choseninlineresult -[inline-mode]:https://core.telegram.org/bots/api#inline-mode - - -* * * - - ## WebHooks @@ -70,8 +55,8 @@ Once they are generated, the `crt.pem` should be uploaded, when setting up your webhook. For example, ```js -bot.setWebHook("public-url.com", { - certificate: "path/to/crt.pem", // Path to your crt.pem +bot.setWebHook('public-url.com', { + certificate: 'path/to/crt.pem', // Path to your crt.pem }); ``` @@ -79,12 +64,6 @@ bot.setWebHook("public-url.com", { `Error: error:0906D06C:PEM routines:PEM_read_bio:no start line`, you may want to proceed to [this issue][issue-63] for more information. -[issue-63]:https://github.com/yagop/node-telegram-bot-api/issues/63 - - -* * * - - ## Sending files @@ -93,14 +72,14 @@ may provide a **file-path** and the library will handle reading it for you. For example, ```js -bot.sendAudio(chatId, "path/to/audio.mp3"); +bot.sendAudio(chatId, 'path/to/audio.mp3'); ``` You may also pass in a **Readable Stream** from which data will be piped. For example, ```js -const stream = fs.createReadStream("path/to/audio.mp3"); +const stream = fs.createReadStream('path/to/audio.mp3'); bot.sendAudio(chatId, stream); ``` @@ -108,7 +87,7 @@ You may also pass in a **Buffer** containing the contents of your file. For example, ```js -const buffer = fs.readFileSync("path/to/audio.mp3"); // sync! that's sad! :-( Just making a point! +const buffer = fs.readFileSync('path/to/audio.mp3'); // sync! that's sad! :-( Just making a point! bot.sendAudio(chatId, buffer); ``` @@ -124,12 +103,12 @@ Some API methods, such as *SendPhoto*, allow passing a **HTTP URL**, that the Telegram servers will use to download the file. For example, ```js -const url = "https://telegram.org/img/t_logo.png"; +const url = 'https://telegram.org/img/t_logo.png'; bot.sendPhoto(chatId, url); ``` -### Performance Issue: +### Performance Issue To support providing file-paths to methods that send files involves performing a file operation, i.e. *fs.existsSync()*, that checks for @@ -149,7 +128,6 @@ const bot = new TelegramBot(token, { }); ``` - ## Error handling @@ -168,14 +146,14 @@ Every `Error` object we pass back has the properties: For example, sending message to a non-existent user: ```js -bot.sendMessage(nonExistentUserId, 'text').catch(error => { +bot.sendMessage(nonExistentUserId, 'text').catch((error) => { console.log(error.code); // => 'ETELEGRAM' console.log(error.response.body); // => { ok: false, error_code: 400, description: 'Bad Request: chat not found' } }); ``` -#### Polling errors +## Polling errors An error may occur during polling. It is up to you to handle it as you see fit. You may decide to crash your bot after a maximum number @@ -193,7 +171,7 @@ bot.on('polling_error', (error) => { ``` -#### WebHook errors +## WebHook errors Just like with [polling errors](#polling-errors), you decide on how to handle it. By default, the error is logged to stderr. @@ -205,3 +183,11 @@ bot.on('webhook_error', (error) => { console.log(error.code); // => 'EPARSE' }); ``` + +[update]:https://core.telegram.org/bots/api#update +[message]:https://core.telegram.org/bots/api#message +[callback-query]:https://core.telegram.org/bots/api#callbackquery +[inline-query]:https://core.telegram.org/bots/api#inlinequery +[chosen-inline-result]:https://core.telegram.org/bots/api#choseninlineresult +[inline-mode]:https://core.telegram.org/bots/api#inline-mode +[issue-63]:https://github.com/yagop/node-telegram-bot-api/issues/63