mir/node-telegram-bot-api
2
0
Fork 0
mirror of https://github.com/yagop/node-telegram-bot-api synced 2025-08-28 12:57:38 +00:00
Code Issues Releases Wiki Activity

docs: Docs improvements (#291)

Browse Source 
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
This commit is contained in:
Plusb Preco 2017-02-15 13:59:56 +09:00 committed by Gocho Mugo
parent b2afdeb6a8
commit a44eb7f1ee
7 changed files with 110 additions and 200 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
CONTRIBUTING.md
View File

@ -5,16 +5,12 @@
Before proceeding any further, read the following documents: Before proceeding any further, read the following documents:
1. [code of conduct][coc] 1. [Code of Conduct][coc]
1. [software license][license] 1. [License][license]
[coc]:https://github.com/yagop/node-telegram-bot-api/blob/master/CODE_OF_CONDUCT.md ## General Information
[license]:https://github.com/yagop/node-telegram-bot-api/blob/master/LICENSE.md
### Updating API Reference i.e. generating `doc/api.md`
### General Information
**Updating API Reference i.e. generating `doc/api.md`:**
Run: Run:
@ -22,19 +18,11 @@ Run:
$ npm run gen-doc $ npm run gen-doc
``` ```
### Running tests
---
**Running tests:**
Please read `test/README.md` for more information. Please read `test/README.md` for more information.
### Transpiling ES2015 for older Node.js versions
---
**Transpiling ES6 for older Node.js versions:**
We use babel to transpile the code: We use babel to transpile the code:
@ -42,8 +30,5 @@ We use babel to transpile the code:
$ npm run build $ npm run build
``` ```
[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
> E=mc²

2
LICENSE.md
View File

@ -1,6 +1,6 @@
The MIT License (MIT) 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 Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal of this software and associated documentation files (the "Software"), to deal

85
README.md
View File

@ -1,38 +1,40 @@
[![Bot API](http://img.shields.io/badge/Bot API-v2.3.1-00aced.svg)](https://core.telegram.org/bots/api) # Node.js Telegram Bot 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) [![Bot API](http://img.shields.io/badge/Bot API-v2.3.1-00aced.svg)](https://core.telegram.org/bots/api)
[![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) [![Build Status](https://travis-ci.org/yagop/node-telegram-bot-api.svg?branch=master)](https://travis-ci.org/yagop/node-telegram-bot-api)
[![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) [![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)
[![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) [![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)
[![https://telegram.me/Yago_Perez](https://img.shields.io/badge/💬 Telegram-Yago__Perez-blue.svg)](https://telegram.me/Yago_Perez) [![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. 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 ```bash
npm install node-telegram-bot-api npm install --save node-telegram-bot-api
``` ```
**Sample Usage:** ## Usage
```js ```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 // 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 // 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]" // Matches "/echo [whatever]"
bot.onText(/\/echo (.+)/, function (msg, match) { bot.onText(/\/echo (.+)/, (msg, match) => {
// 'msg' is the received Message from Telegram // 'msg' is the received Message from Telegram
// 'match' is the result of executing the regexp above on the text content // 'match' is the result of executing the regexp above on the text content
// of the message // of the message
var chatId = msg.chat.id; const chatId = msg.chat.id;
var resp = match[1]; // the captured "whatever" const resp = match[1]; // the captured "whatever"
// send back the matched "whatever" to the chat // send back the matched "whatever" to the chat
bot.sendMessage(chatId, resp); 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 // Listen for any kind of message. There are different kinds of
// messages. // messages.
bot.on('message', function (msg) { bot.on('message', (msg) => {
var chatId = msg.chat.id; const chatId = msg.chat.id;
// send a message to the chat acknowledging receipt of their message // send a message to the chat acknowledging receipt of their message
bot.sendMessage(chatId, "Received your message"); bot.sendMessage(chatId, 'Received your message');
}); });
``` ```
* * *
## Documentation ## Documentation
* [Usage][usage] * [Usage][usage]
* [Examples][examples] * [Examples][examples]
* [Help Information][help] * [Help Information][help]
* API Reference ([release][api-release] / [development][api-dev]) * API Reference ([release][api-release] / [development][api-dev])
* [Contributing to the Project][contributing] * [Contributing to the Project][contributing]
_**Note**: Development is done against the **master** branch. Code for the latest release _**Note**: Development is done against the **master** branch. Code for the latest release
resides on the **release** branch._ resides on the **release** branch._
## Community
[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
We have a [Telegram channel][tg-channel] where we post updates on We have a [Telegram channel][tg-channel] where we post updates on
the Project. Head over and subscribe! 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 * [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 * [teleirc](https://github.com/FruitieX/teleirc): A simple Telegram ↔ IRC gateway
## License
* * *
## License Information
**The MIT License (MIT)** **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 [tg-channel]:https://telegram.me/node_telegram_bot_api

2
doc/api.hbs
View File

@ -1,5 +1,7 @@
# API Reference # 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"~}} {{#class name="TelegramBot"~}}
{{>header~}} {{>header~}}
{{>body~}} {{>body~}}

2
doc/api.md
View File

@ -1,5 +1,7 @@
# API Reference # API Reference
**Note:** If you are looking for available [events](usage.md#events) or usage of api, please refer [`usage.md`](usage.md).
<a name="TelegramBot"></a> <a name="TelegramBot"></a>
## TelegramBot ## TelegramBot

130
doc/help.md
View File

@ -3,40 +3,23 @@
* [Common Pitfalls](#pitfalls) * [Common Pitfalls](#pitfalls)
* [FAQs](#faqs) * [FAQs](#faqs)
* * *
<a name="pitfalls"></a> <a name="pitfalls"></a>
## Common Pitfalls ## Common Pitfalls
1. [Failing to receive reply with `ReplyToMessage`](#reply-to-message)
---
<a name="reply-to-message"></a> <a name="reply-to-message"></a>
**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 The user has to **manually reply** to your message, by tapping on the bot's message and select *Reply*.
bot's message and select *Reply*.
Sources: 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)
* * *
<a name="faqs"></a> <a name="faqs"></a>
## Frequently Asked Questions ## Frequently Asked Questions
> Check out [all questions ever asked][questions] on our Github Issues. > 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. [How do I send GIFs?](#gifs)
1. [Why and When do I need a certificate when using WebHooks?](#webhook-cert) 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) 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. [Can you add feature X to the library?](#new-feature)
1. [Is this scalable?](#scalable) 1. [Is this scalable?](#scalable)
---
<a name="gifs"></a> <a name="gifs"></a>
**How do I send GIFs?** ### How do I send GIFs?
You might be trying to send your animated GIFs using *TelegramBot#sendPhoto()*. You might be trying to send your animated GIFs using *TelegramBot#sendPhoto()*.
The method mostly supports static images. As noted by the community, The method mostly supports static images. As noted by the community,
it seems you need to send them as documents, using *TelegramBot#sendDocument()*. it seems you need to send them as documents, using *TelegramBot#sendDocument()*.
```js ```js
bot.sendDocument(chatId, "cat.gif"); bot.sendDocument(chatId, 'cat.gif');
``` ```
Sources: 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)
---
<a name="webhook-cert"></a> <a name="webhook-cert"></a>
**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: Sources:
* Issue #63: https://github.com/yagop/node-telegram-bot-api/issues/63 * 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 [#125](https://github.com/yagop/node-telegram-bot-api/issues/125)
---
<a name="leave-chat"></a> <a name="leave-chat"></a>
**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: 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)
---
<a name="error-meanings"></a> <a name="error-meanings"></a>
**What does this error mean?** ### What does this error mean?
*Not Done. Send PR please!* *Not done. PRs welcome!*
Sources: Sources:
* Issue #73: https://github.com/yagop/node-telegram-bot-api/issues/73 * 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 [#99](https://github.com/yagop/node-telegram-bot-api/issues/99)
* Issue #101: https://github.com/yagop/node-telegram-bot-api/issues/101 * 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 [#107](https://github.com/yagop/node-telegram-bot-api/issues/107)
* Issue #156: https://github.com/yagop/node-telegram-bot-api/issues/156 * 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 [#170](https://github.com/yagop/node-telegram-bot-api/issues/170)
* Issue #244: https://github.com/yagop/node-telegram-bot-api/issues/244 * Issue [#244](https://github.com/yagop/node-telegram-bot-api/issues/244)
---
<a name="reply-keyboard"></a> <a name="reply-keyboard"></a>
**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: 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)
---
<a name="ordered-sending"></a> <a name="ordered-sending"></a>
**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: 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)
---
<a name="proxy"></a> <a name="proxy"></a>
**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: Sources:
* Issue #122: https://github.com/yagop/node-telegram-bot-api/issues/122 * 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 [#253](https://github.com/yagop/node-telegram-bot-api/issues/253)
---
<a name="new-feature"></a> <a name="new-feature"></a>
**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: 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)
---
<a name="scalable"></a> <a name="scalable"></a>
**Is this scalable?** ### Is this scalable?
*Not Done. Send PR please!* *Not done. PRs welcome!*
Sources: 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
---

58
doc/usage.md
View File

@ -1,13 +1,9 @@
# Usage # Usage
1. [Events](#events) * [Events](#events)
1. [WebHooks](#WebHooks) * [WebHooks](#WebHooks)
1. [Sending files](#sending-files) * [Sending files](#sending-files)
1. [Error handling](#error-handling) * [Error handling](#error-handling)
* * *
<a name="events"></a> <a name="events"></a>
## Events ## Events
@ -39,17 +35,6 @@
**Tip:** Bot must be enabled on [inline mode][inline-mode] for receive some **Tip:** Bot must be enabled on [inline mode][inline-mode] for receive some
messages. 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
* * *
<a name="webhooks"></a> <a name="webhooks"></a>
## WebHooks ## WebHooks
@ -70,8 +55,8 @@ Once they are generated, the `crt.pem` should be uploaded, when setting up
your webhook. For example, your webhook. For example,
```js ```js
bot.setWebHook("public-url.com", { bot.setWebHook('public-url.com', {
certificate: "path/to/crt.pem", // Path to your crt.pem 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`, `Error: error:0906D06C:PEM routines:PEM_read_bio:no start line`,
you may want to proceed to [this issue][issue-63] for more information. 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
* * *
<a name="sending-files"></a> <a name="sending-files"></a>
## Sending files ## Sending files
@ -93,14 +72,14 @@ may provide a **file-path** and the library will handle reading it for you.
For example, For example,
```js ```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. You may also pass in a **Readable Stream** from which data will be piped.
For example, For example,
```js ```js
const stream = fs.createReadStream("path/to/audio.mp3"); const stream = fs.createReadStream('path/to/audio.mp3');
bot.sendAudio(chatId, stream); bot.sendAudio(chatId, stream);
``` ```
@ -108,7 +87,7 @@ You may also pass in a **Buffer** containing the contents of your file.
For example, For example,
```js ```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); 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, the Telegram servers will use to download the file. For example,
```js ```js
const url = "https://telegram.org/img/t_logo.png"; const url = 'https://telegram.org/img/t_logo.png';
bot.sendPhoto(chatId, url); bot.sendPhoto(chatId, url);
``` ```
<a name="sending-files-performance"></a> <a name="sending-files-performance"></a>
### Performance Issue: ### Performance Issue
To support providing file-paths to methods that send files involves To support providing file-paths to methods that send files involves
performing a file operation, i.e. *fs.existsSync()*, that checks for performing a file operation, i.e. *fs.existsSync()*, that checks for
@ -149,7 +128,6 @@ const bot = new TelegramBot(token, {
}); });
``` ```
<a name="error-handling"></a> <a name="error-handling"></a>
## Error handling ## Error handling
@ -168,14 +146,14 @@ Every `Error` object we pass back has the properties:
For example, sending message to a non-existent user: For example, sending message to a non-existent user:
```js ```js
bot.sendMessage(nonExistentUserId, 'text').catch(error => { bot.sendMessage(nonExistentUserId, 'text').catch((error) => {
console.log(error.code); // => 'ETELEGRAM' console.log(error.code); // => 'ETELEGRAM'
console.log(error.response.body); // => { ok: false, error_code: 400, description: 'Bad Request: chat not found' } console.log(error.response.body); // => { ok: false, error_code: 400, description: 'Bad Request: chat not found' }
}); });
``` ```
<a name="polling-errors"></a> <a name="polling-errors"></a>
#### Polling errors ## Polling errors
An error may occur during polling. It is up to you to handle it 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 as you see fit. You may decide to crash your bot after a maximum number
@ -193,7 +171,7 @@ bot.on('polling_error', (error) => {
``` ```
<a name="webhook-errors"></a> <a name="webhook-errors"></a>
#### WebHook errors ## WebHook errors
Just like with [polling errors](#polling-errors), you decide on how to Just like with [polling errors](#polling-errors), you decide on how to
handle it. By default, the error is logged to stderr. handle it. By default, the error is logged to stderr.
@ -205,3 +183,11 @@ bot.on('webhook_error', (error) => {
console.log(error.code); // => 'EPARSE' 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