diff --git a/README.hbs b/README.hbs new file mode 100644 index 0000000..eaae887 --- /dev/null +++ b/README.hbs @@ -0,0 +1,37 @@ +[![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) + +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](telegram.me/BotFather) and create a new bot. + +```sh +npm install node-telegram-bot-api +``` + +```js +var TelegramBot = require('node-telegram-bot-api'); + +var token = 'YOUR_TELEGRAM_BOT_TOKEN'; +// Setup polling way +var bot = new TelegramBot(token, {polling: true}); +bot.on('text', function (msg) { + var chatId = msg.chat.id; + // photo can be: a file path, a stream or a Telegram file_id + var photo = 'cats.png'; + bot.sendPhoto(chatId, photo, {caption: 'Lovely kittens'}); +}); +``` + +There are some other examples on [examples](https://github.com/yagop/node-telegram-bot-api/tree/master/examples). + +### Events +Every time TelegramBot receives a message, it emits a `message`. Depending on which [message](https://core.telegram.org/bots/api#message) was received, emits an event from this ones: `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`. Its much better to listen a specific event rather than a `message` in order to stay safe from the content. +* * * + + +## API Reference +{{#class name="TelegramBot"~}} +{{>header~}} +{{>body~}} +{{>member-index~}} +{{>members~}} +{{/class}} +* * * diff --git a/README.md b/README.md index defea77..6b176e5 100644 --- a/README.md +++ b/README.md @@ -27,286 +27,271 @@ Every time TelegramBot receives a message, it emits a `message`. Depending on w * * * - - +## API Reference + ## TelegramBot +TelegramBot +**Kind**: global class +**See**: https://core.telegram.org/bots/api + +* [TelegramBot](#TelegramBot) + * [new TelegramBot(token, [options])](#new_TelegramBot_new) + * [.getMe()](#TelegramBot+getMe) ⇒ Promise + * [.setWebHook(url)](#TelegramBot+setWebHook) + * [.getUpdates([timeout], [limit], [offset])](#TelegramBot+getUpdates) ⇒ Promise + * [.sendMessage(chatId, text, [options])](#TelegramBot+sendMessage) ⇒ Promise + * [.forwardMessage(chatId, fromChatId, messageId)](#TelegramBot+forwardMessage) ⇒ Promise + * [.sendPhoto(chatId, photo, [options])](#TelegramBot+sendPhoto) ⇒ Promise + * [.sendAudio(chatId, audio, [options])](#TelegramBot+sendAudio) ⇒ Promise + * [.sendDocument(chatId, A, [options])](#TelegramBot+sendDocument) ⇒ Promise + * [.sendSticker(chatId, A, [options])](#TelegramBot+sendSticker) ⇒ Promise + * [.sendVideo(chatId, A, [options])](#TelegramBot+sendVideo) ⇒ Promise + * [.sendVoice(chatId, voice, [options])](#TelegramBot+sendVoice) ⇒ Promise + * [.sendChatAction(chatId, action)](#TelegramBot+sendChatAction) ⇒ Promise + * [.getUserProfilePhotos(userId, [offset], [limit])](#TelegramBot+getUserProfilePhotos) ⇒ Promise + * [.sendLocation(chatId, latitude, longitude, [options])](#TelegramBot+sendLocation) ⇒ Promise + * [.getFile(fileId)](#TelegramBot+getFile) ⇒ Promise + * [.getFileLink(fileId)](#TelegramBot+getFileLink) ⇒ Promise + * [.downloadFile(fileId, downloadDir)](#TelegramBot+downloadFile) ⇒ Promise + + +### new TelegramBot(token, [options]) Both request method to obtain messages are implemented. To use standard polling, set `polling: true` -on `options`. Notice that [webHook](https://core.telegram.org/bots/api#setwebhook) will need a valid SSL certificate (self-signed certificates are allowed since August 29, 2015). +on `options`. Notice that [webHook](https://core.telegram.org/bots/api#setwebhook) will need a valid (not self signed) SSL certificate. Emits `message` when a message arrives. -See: https://core.telegram.org/bots/api -### Params: - -* **String** *token* Bot Token -* **Object** *[options]* -* **Boolean|Object** *[options.polling=false]* Set true to enable polling or set options -* **String|Number** *[options.polling.timeout=4]* Polling time -* **String|Number** *[options.polling.interval=2000]* Interval between requests in miliseconds -* **Boolean|Object** *[options.webHook=false]* Set true to enable WebHook or set options -* **String** *[options.webHook.key]* PEM private key to webHook server -* **String** *[options.webHook.cert]* PEM certificate key to webHook server - -## getMe() +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| token | String | | Bot Token | +| [options] | Object | | | +| [options.polling] | Boolean | Object | false | Set true to enable polling or set options | +| [options.polling.timeout] | String | Number | 4 | Polling time | +| [options.polling.interval] | String | Number | 2000 | Interval between requests in miliseconds | +| [options.webHook] | Boolean | Object | false | Set true to enable WebHook or set options | +| [options.webHook.key] | String | | PEM private key to webHook server | +| [options.webHook.cert] | String | | PEM certificate key to webHook server | + +### telegramBot.getMe() ⇒ Promise Returns basic information about the bot in form of a `User` object. -See: https://core.telegram.org/bots/api#getme - -### Return: - -* **Promise** - -## setWebHook(url) - +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getme + +### telegramBot.setWebHook(url) Specify an url to receive incoming updates via an outgoing webHook. -See: https://core.telegram.org/bots/api#setwebhook +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#setwebhook -### Params: - -* **String** *url* URL where Telegram will make HTTP Post. Leave empty to delete webHook. - -## getUpdates([timeout], [limit], [offset]) +| Param | Type | Description | +| --- | --- | --- | +| url | String | URL where Telegram will make HTTP Post. Leave empty to delete webHook. | + +### telegramBot.getUpdates([timeout], [limit], [offset]) ⇒ Promise Use this method to receive incoming updates using long polling -See: https://core.telegram.org/bots/api#getupdates +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - Updates +**See**: https://core.telegram.org/bots/api#getupdates -### Params: - -* **Number|String** *[timeout]* Timeout in seconds for long polling. -* **Number|String** *[limit]* Limits the number of updates to be retrieved. -* **Number|String** *[offset]* Identifier of the first update to be returned. - -### Return: - -* **Promise** Updates - -## sendMessage(chatId, text, [options]) +| Param | Type | Description | +| --- | --- | --- | +| [timeout] | Number | String | Timeout in seconds for long polling. | +| [limit] | Number | String | Limits the number of updates to be retrieved. | +| [offset] | Number | String | Identifier of the first update to be returned. | + +### telegramBot.sendMessage(chatId, text, [options]) ⇒ Promise Send text message. -See: https://core.telegram.org/bots/api#sendmessage +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendmessage -### Params: - -* **Number|String** *chatId* Unique identifier for the message recipient -* **String** *text* Text of the message to be sent -* **Object** *[options]* Additional Telegram query options - -### Return: - -* **Promise** - -## forwardMessage(chatId, fromChatId, messageId) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| text | String | Text of the message to be sent | +| [options] | Object | Additional Telegram query options | + +### telegramBot.forwardMessage(chatId, fromChatId, messageId) ⇒ Promise Forward messages of any kind. -### Params: +**Kind**: instance method of [TelegramBot](#TelegramBot) -* **Number|String** *chatId* Unique identifier for the message recipient -* **Number|String** *fromChatId* Unique identifier for the chat where the original message was sent -* **Number|String** *messageId* Unique message identifier - -### Return: - -* **Promise** - -## sendPhoto(chatId, photo, [options]) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| fromChatId | Number | String | Unique identifier for the chat where the original message was sent | +| messageId | Number | String | Unique message identifier | + +### telegramBot.sendPhoto(chatId, photo, [options]) ⇒ Promise Send photo -See: https://core.telegram.org/bots/api#sendphoto +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendphoto -### Params: - -* **Number|String** *chatId* Unique identifier for the message recipient -* **String|stream.Stream** *photo* A file path or a Stream. Can also be a `file_id` previously uploaded -* **Object** *[options]* Additional Telegram query options - -### Return: - -* **Promise** - -## sendAudio(chatId, audio, [options]) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| photo | String | stream.Stream | A file path or a Stream. Can also be a `file_id` previously uploaded | +| [options] | Object | Additional Telegram query options | + +### telegramBot.sendAudio(chatId, audio, [options]) ⇒ Promise Send audio -See: https://core.telegram.org/bots/api#sendaudio +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendaudio -### Params: - -* **Number|String** *chatId* Unique identifier for the message recipient -* **String|stream.Stream** *audio* A file path or a Stream. Can also be a `file_id` previously uploaded. -* **Object** *[options]* Additional Telegram query options - -### Return: - -* **Promise** - -## sendDocument(chatId, A, [options]) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| audio | String | stream.Stream | A file path or a Stream. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | + +### telegramBot.sendDocument(chatId, A, [options]) ⇒ Promise Send Document -See: https://core.telegram.org/bots/api#sendDocument +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendDocument -### Params: - -* **Number|String** *chatId* Unique identifier for the message recipient -* **String|stream.Stream** *A* file path or a Stream. Can also be a `file_id` previously uploaded. -* **Object** *[options]* Additional Telegram query options - -### Return: - -* **Promise** - -## sendSticker(chatId, A, [options]) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| A | String | stream.Stream | file path or a Stream. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | + +### telegramBot.sendSticker(chatId, A, [options]) ⇒ Promise Send .webp stickers. -See: https://core.telegram.org/bots/api#sendsticker +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendsticker -### Params: - -* **Number|String** *chatId* Unique identifier for the message recipient -* **String|stream.Stream** *A* file path or a Stream. Can also be a `file_id` previously uploaded. -* **Object** *[options]* Additional Telegram query options - -### Return: - -* **Promise** - -## sendVideo(chatId, A, [options]) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| A | String | stream.Stream | file path or a Stream. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | + +### telegramBot.sendVideo(chatId, A, [options]) ⇒ Promise Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as Document). -See: https://core.telegram.org/bots/api#sendvideo +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendvideo -### Params: +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| A | String | stream.Stream | file path or a Stream. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | -* **Number|String** *chatId* Unique identifier for the message recipient -* **String|stream.Stream** *A* file path or a Stream. Can also be a `file_id` previously uploaded. -* **Object** *[options]* Additional Telegram query options + +### telegramBot.sendVoice(chatId, voice, [options]) ⇒ Promise +Send voice -### Return: +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendvoice -* **Promise** - -## sendVoice(chatId, A, [options]) - -Use this method to send audio files, if you want Telegram clients to display the file as a playable voice message. For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent as Audio or Document). - -See: https://core.telegram.org/bots/api#sendvoice - -### Params: - -* **Number|String** *chatId* Unique identifier for the message recipient -* **String|stream.Stream** *A* file path or a Stream. Can also be a `file_id` previously uploaded. -* **Object** *[options]* Additional Telegram query options - -### Return: - -* **Promise** - -## sendChatAction(chatId, action) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| voice | String | stream.Stream | A file path or a Stream. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | + +### telegramBot.sendChatAction(chatId, action) ⇒ Promise Send chat action. `typing` for text messages, `upload_photo` for photos, `record_video` or `upload_video` for videos, `record_audio` or `upload_audio` for audio files, `upload_document` for general files, `find_location` for location data. -See: https://core.telegram.org/bots/api#sendchataction +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendchataction -### Params: - -* **Number|String** *chatId* Unique identifier for the message recipient -* **String** *action* Type of action to broadcast. - -### Return: - -* **Promise** - -## getUserProfilePhotos(userId, [offset], [limit]) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| action | String | Type of action to broadcast. | + +### telegramBot.getUserProfilePhotos(userId, [offset], [limit]) ⇒ Promise Use this method to get a list of profile pictures for a user. Returns a [UserProfilePhotos](https://core.telegram.org/bots/api#userprofilephotos) object. -See: https://core.telegram.org/bots/api#getuserprofilephotos +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getuserprofilephotos -### Params: - -* **Number|String** *userId* Unique identifier of the target user -* **Number** *[offset]* Sequential number of the first photo to be returned. By default, all photos are returned. -* **Number** *[limit]* Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100. - -### Return: - -* **Promise** - -## sendLocation(chatId, latitude, longitude, [options]) +| Param | Type | Description | +| --- | --- | --- | +| userId | Number | String | Unique identifier of the target user | +| [offset] | Number | Sequential number of the first photo to be returned. By default, all photos are returned. | +| [limit] | Number | Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100. | + +### telegramBot.sendLocation(chatId, latitude, longitude, [options]) ⇒ Promise Send location. Use this method to send point on the map. -See: https://core.telegram.org/bots/api#sendlocation +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendlocation -### Params: - -* **Number|String** *chatId* Unique identifier for the message recipient -* **Float** *latitude* Latitude of location -* **Float** *longitude* Longitude of location -* **Object** *[options]* Additional Telegram query options - -### Return: - -* **Promise** - -## getFile(fileId) +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| latitude | Float | Latitude of location | +| longitude | Float | Longitude of location | +| [options] | Object | Additional Telegram query options | + +### telegramBot.getFile(fileId) ⇒ Promise Get file. Use this method to get basic info about a file and prepare it for downloading. Attention: link will be valid for 1 hour. -See: https://core.telegram.org/bots/api#getfile +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getfile -### Params: -* **String** *fileId* File identifier to get info about - -### Return: - -* **Promise** - -## getFileLink(fileId) +| Param | Type | Description | +| --- | --- | --- | +| fileId | String | File identifier to get info about | + +### telegramBot.getFileLink(fileId) ⇒ Promise Get link for file. Use this method to get link for file for subsequent use. Attention: link will be valid for 1 hour. This method is a sugar extension of the (getFile)[#getfilefileid] method, which returns just path to file on remote server (you will have to manually build full uri after that). -See: https://core.telegram.org/bots/api#getfile +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - promise Promise which will have *fileURI* in resolve callback +**See**: https://core.telegram.org/bots/api#getfile -### Params: -* **String** *fileId* File identifier to get info about - -### Return: - -* **Promise** *promise* Promise which will have *fileURI* in resolve callback - -## downloadFile(fileId, downloadDir) +| Param | Type | Description | +| --- | --- | --- | +| fileId | String | File identifier to get info about | + +### telegramBot.downloadFile(fileId, downloadDir) ⇒ Promise Downloads file in the specified folder. This is just a sugar for (getFile)[#getfilefiled] method -### Params: -* **String** *fileId* File identifier to get info about -* **String** *downloadDir* Absolute path to the folder in which file will be saved +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - promise Promise, which will have *filePath* of downloaded file in resolve callback -### Return: +| Param | Type | Description | +| --- | --- | --- | +| fileId | String | File identifier to get info about | +| downloadDir | String | Absolute path to the folder in which file will be saved | -* **Promise** *promise* Promise, which will have *filePath* of downloaded file in resolve callback - - +* * * diff --git a/package.json b/package.json index 4b19852..f21a573 100644 --- a/package.json +++ b/package.json @@ -15,13 +15,15 @@ ], "scripts": { "test": "./node_modules/.bin/mocha test/index.js", - "test-cov": "./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage" + "test-cov": "./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage", + "gen-doc": "./node_modules/.bin/jsdoc2md --src src/telegram.js -t README.hbs > README.md" }, "author": "Yago Pérez ", "license": "MIT", "dependencies": { "bluebird": "^2.9.30", "debug": "^2.2.0", + "jsdoc-to-markdown": "^1.2.0", "mime": "^1.3.4", "request": "^2.58.0" },