gitea
/
node-telegram-bot-api
1
0
Fork 0
Code Issues Pull Requests Packages Projects 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
experimental
Plusb Preco 9 years ago committed by Gocho Mugo
parent b2afdeb6a8
commit a44eb7f1ee
7 changed files with 110 additions and 200 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 31
      CONTRIBUTING.md
  2. 2
      LICENSE.md
  3. 61
      README.md
  4. 2
      doc/api.hbs
  5. 2
      doc/api.md
  6. 130
      doc/help.md
  7. 58
      doc/usage.md

31
CONTRIBUTING.md
Unescape 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

2
LICENSE.md
Unescape 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

61
README.md
Unescape View File

@ -1,3 +1,5 @@
# 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)
@ -8,31 +10,31 @@
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,18 +42,14 @@ 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]
@ -63,19 +61,7 @@ bot.on('message', function (msg) {
_**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

2
doc/api.hbs
Unescape 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~}}

2
doc/api.md
Unescape 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

130
doc/help.md
Unescape 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

58
doc/usage.md
Unescape 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

Write Preview
Loading…
Cancel
Save