2
0
mirror of https://github.com/yagop/node-telegram-bot-api synced 2025-08-22 09:57:10 +00:00

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
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

View File

@ -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

View File

@ -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

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)
[![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

View File

@ -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~}}

View File

@ -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).
<a name="TelegramBot"></a>
## TelegramBot

View File

@ -3,40 +3,23 @@
* [Common Pitfalls](#pitfalls)
* [FAQs](#faqs)
* * *
<a name="pitfalls"></a>
## Common Pitfalls
1. [Failing to receive reply with `ReplyToMessage`](#reply-to-message)
---
<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
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)
<a name="faqs"></a>
## 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)
---
<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()*.
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)
<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:
* 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)
<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:
* 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>
**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)
<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:
* 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>
**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)
<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:
* 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)
<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:
* 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>
**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

View File

@ -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)
<a name="events"></a>
## 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
* * *
<a name="webhooks"></a>
## 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
* * *
<a name="sending-files"></a>
## 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);
```
<a name="sending-files-performance"></a>
### 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, {
});
```
<a name="error-handling"></a>
## 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' }
});
```
<a name="polling-errors"></a>
#### 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) => {
```
<a name="webhook-errors"></a>
#### 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