messaging-api-telegram-proxy
Messaging API client for Telegram use proxy
Table of Contents
Installation
npm i --save messaging-api-telegram-proxy
Usage
Initialize
const TelegramClient = ; let telegram_access_token = '12345678:AaBbCcDdwhatever'// get accessToken from telegram [@BotFather](https://telegram.me/BotFather)let proxy_http = 'http://login:pass@127.0.0.1:1234' // https://www.google.ru/search?q=proxy+http const client = TelegramClient;
Error Handling
messaging-api-telegram-proxy
uses axios as HTTP client. We use axios-error package to wrap API error instances for better formatting error messages. Directly console.log
on the error instance will return formatted message. If you'd like to get the axios request
, response
, or config
, you can still get them via those keys on the error instance.
client;
API Reference
All methods return a Promise.
Webhook API
getWebhookInfo
- Official Docs
Gets current webhook status.
Example:
client;
getUpdates
- Official Docs
Use this method to receive incoming updates using long polling. An Array of Update objects is returned.
Param | Type | Description |
---|---|---|
options | Object |
Optional parameters. |
Example:
client ;
setWebhook(url)
- Official Docs
Specifies a url and receive incoming updates via an outgoing webhook.
Param | Type | Description |
---|---|---|
url | String |
HTTPS url to send updates to. |
Example:
client;
deleteWebhook
- Official Docs
Removes webhook integration.
Example:
client;
Official Docs
Send API -sendMessage(chatId, text [, options])
- Official Docs
Sends text messages.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
text | String |
Text of the message to be sent. |
options | Object |
Other optional parameters. |
Example:
client;
sendPhoto(chatId, photo [, options])
- Official Docs
Sends photos.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
photo | String |
Pass a file id (recommended) or HTTP URL to send photo. |
options | Object |
Other optional parameters. |
Example:
client;
sendAudio(chatId, audio [, options])
- Official Docs
Sends audio files.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
audio | String |
Pass a file id (recommended) or HTTP URL to send audio. |
options | Object |
Other optional parameters. |
Example:
client;
sendDocument(chatId, document [, options])
- Official Docs
Sends general files.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
document | String |
Pass a file id (recommended) or HTTP URL to send document. |
options | Object |
Other optional parameters. |
Example:
client;
sendSticker(chatId, sticker [, options])
- Official Docs
Sends .webp
stickers.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
sticker | String |
Pass a file id (recommended) or HTTP URL to send sticker. |
options | Object |
Other optional parameters. |
Example:
client;
sendVideo(chatId, video [, options])
- Official Docs
Sends video files, Telegram clients support mp4
videos (other formats may be sent as Document).
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
video | String |
Pass a file id (recommended) or HTTP URL to send video. |
options | Object |
Other optional parameters. |
Example:
client;
sendVoice(chatId, voice [, options])
- Official Docs
Sends audio files.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
voice | String |
Pass a file id (recommended) or HTTP URL to send voice. |
options | Object |
Other optional parameters. |
Example:
client;
sendVideoNote(chatId, videoNote [, options])
- Official Docs
Sends video messages. As of v.4.0, Telegram clients support rounded square mp4 videos of up to 1 minute long.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
videoNote | String |
Pass a file id (recommended) or HTTP URL to send video note. |
options | Object |
Other optional parameters. |
Example:
client;
sendMediaGroup(chatId, media [, options])
- Official Docs
send a group of photos or videos as an album.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
media | Array<InputMedia> | A JSON-serialized array describing photos and videos to be sent, must include 2–10 items |
options | Object |
Other optional parameters. |
Example:
client;
sendLocation(chatId, location [, options])
- Official Docs
Sends point on the map.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
location | Object |
Object contains latitude and longitude. |
location.latitude | Number |
Latitude of the location. |
location.longitude | Number |
Longitude of the location. |
options | Object |
Other optional parameters. |
Example:
client;
sendVenue(chatId, venue [, options])
- Official Docs
Sends information about a venue.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
venue | Object |
Object contains information of the venue. |
venue.latitude | Number |
Latitude of the venue. |
venue.longitude | Number |
Longitude of the venue. |
venue.title | String |
Name of the venue. |
venue.address | String |
Address of the venue. |
options | Object |
Other optional parameters. |
Example:
client;
sendContact(chatId, contact [, options])
- Official Docs
Sends phone contacts.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
contact | Object |
Object contains information of the contact. |
contact.phone_number | String |
Phone number of the contact. |
contact.first_name | String |
First name of the contact. |
options | Object |
Other optional parameters. |
Example:
client;
sendChatAction(chatId, action)
- Official Docs
Tells the user that something is happening on the bot's side.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
action | String |
Type of action to broadcast. |
Example:
client;
Get API
getMe
- Official Docs
Gets bot's information.
Example:
client;
getUserProfilePhotos(userId [, options])
- Official Docs
Gets a list of profile pictures for a user.
Param | Type | Description |
---|---|---|
userId | String |
Unique identifier of the target user. |
options | Object |
Other optional parameters |
Example:
client;
getFile(fileId)
- Official Docs
Gets basic info about a file and prepare it for downloading.
Param | Type | Description |
---|---|---|
fileId | String |
File identifier to get info about. |
Example:
client ;
getFileLink(fileId)
Gets link of the file.
Param | Type | Description |
---|---|---|
fileId | String |
File identifier to get info about. |
Example:
client ;
getChat(chatId)
- Official Docs
Gets up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.)
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
Example:
client;
getChatAdministrators(chatId)
- Official Docs
Gets a list of administrators in a chat.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
Example:
client;
getChatMembersCount(chatId)
- Official Docs
Gets the number of members in a chat.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
Example:
client;
getChatMember(chatId, userId)
- Official Docs
Gets information about a member of a chat.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
userId | Number |
Unique identifier of the target user. |
Example:
client;
Updating API
editMessageText(text [, options])
- Official Docs
Edits text and game messages sent by the bot or via the bot (for inline bots).
Param | Type | Description |
---|---|---|
text | String |
New text of the message. |
options | Object |
One of chat_id, message_id or inline_message_id is required. |
options.chat_id | Number | String |
Unique identifier for the target chat or username of the target channel. |
options.message_id | Number |
Identifier of the sent message. |
options.inline_message_id | String |
Identifier of the inline message. |
Example:
client;
editMessageCaption(caption [, options])
- Official Docs
Edits captions of messages sent by the bot or via the bot (for inline bots).
Param | Type | Description |
---|---|---|
caption | String |
New caption of the message. |
options | Object |
One of chat_id, message_id or inline_message_id is required. |
options.chat_id | Number | String |
Unique identifier for the target chat or username of the target channel. |
options.message_id | Number |
Identifier of the sent message. |
options.inline_message_id | String |
Identifier of the inline message. |
Example:
client;
editMessageReplyMarkup(replyMarkup [, options])
- Official Docs
Edits only the reply markup of messages sent by the bot or via the bot (for inline bots).
Param | Type | Description |
---|---|---|
replyMarkup | Object |
New replyMarkup of the message. |
options | Object |
One of chat_id, message_id or inline_message_id is required. |
options.chat_id | Number | String |
Unique identifier for the target chat or username of the target channel. |
options.message_id | Number |
Identifier of the sent message. |
options.inline_message_id | String |
Identifier of the inline message. |
Example:
client;
deleteMessage(chatId, messageId)
- Official Docs
Deletes a message, including service messages.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
messageId | Number |
Identifier of the message to delete. |
Example:
client;
editMessageLiveLocation(location [, options])
- Official Docs
Edit live location messages sent by the bot or via the bot (for inline bots).
Param | Type | Description |
---|---|---|
location | Object |
Object contains new latitude and longitude. |
location.latitude | Number |
Latitude of new location. |
location.longitude | Number |
Longitude of new location. |
options | Object |
One of chat_id, message_id or inline_message_id is required. |
options.chat_id | Number | String |
Unique identifier for the target chat or username of the target channel. |
options.message_id | Number |
Identifier of the sent message. |
options.inline_message_id | String |
Identifier of the inline message. |
Example:
client;
stopMessageLiveLocation(options)
- Official Docs
Stop updating a live location message sent by the bot or via the bot (for inline bots) before live_period expires.
Param | Type | Description |
---|---|---|
identifier | Object |
One of chat_id, message_id or inline_message_id is required. |
identifier.chat_id | Number | String |
Unique identifier for the target chat or username of the target channel. |
identifier.message_id | Number |
Identifier of the sent message. |
identifier.inline_message_id | String |
Identifier of the inline message. |
Example:
client;
Group API
kickChatMember(chatId, userId [, options])
- Official Docs
Kicks a user from a group, a supergroup or a channel.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
userId | Number |
Unique identifier of the target user. |
options | Object |
Other optional parameters. |
Example:
client;
unbanChatMember(chatId, userId)
- Official Docs
Unbans a previously kicked user in a supergroup or channel.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
userId | Number |
Unique identifier of the target user. |
Example:
client;
restrictChatMember(chatId, userId [, options])
- Official Docs
Restricts a user in a supergroup
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
userId | Number |
Unique identifier of the target user. |
options | Object |
Other optional parameters. |
Example:
client;
promoteChatMember(chatId, userId [, options])
- Official Docs
Promotes or demotes a user in a supergroup or a channel.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
userId | Number |
Unique identifier of the target user. |
options | Object |
Other optional parameters. |
Example:
client;
exportChatInviteLink(chatId)
- Official Docs
Exports an invite link to a supergroup or a channel.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
Example:
client;
setChatPhoto(chatId, photo)
- Official Docs
Sets a new profile photo for the chat.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
photo | String |
Pass a file id (recommended) or HTTP URL to send photo. |
Example:
client;
deleteChatPhoto(chatId)
- Official Docs
Deletes a chat photo.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
Example:
client;
setChatTitle(chatId, title)
- Official Docs
Changes the title of a chat.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
title | String |
New chat title, 1-255 characters. |
Example:
client;
setChatDescription(chatId, description)
- Official Docs
Changes the description of a supergroup or a channel.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
description | String |
New chat description, 0-255 characters. |
Example:
client;
setChatStickerSet(chatId, stickerSetName)
- Official Docs
Set a new group sticker set for a supergroup.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
stickerSetName | String |
Name of the sticker set to be set as the group sticker set. |
Example:
client;
deleteChatStickerSet(chatId)
- Official Docs
Delete a group sticker set from a supergroup.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
Example:
client;
pinChatMessage(chatId, messageId [, options])
- Official Docs
Pins a message in a supergroup.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
messageId | Number |
Identifier of a message to pin. |
options | Object |
Other optional parameters. |
Example:
client;
unpinChatMessage(chatId)
- Official Docs
Unpins a message in a supergroup chat.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
Example:
client;
leaveChat(chatId)
- Official Docs
Leaves a group, supergroup or channel.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
Example:
client;
Payments API
sendInvoice(chatId, product [, options])
- Official Docs
Sends invoice.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
product | Object |
Object of the product. |
product.title | String |
Product name. |
product.description | String |
Product description. |
product.payload | String |
Bot defined invoice payload. |
product.provider_token | String |
Payments provider token. |
product.start_parameter | String |
Deep-linking parameter. |
product.currency | String |
Three-letter ISO 4217 currency code. |
product.prices | Array<Object> |
Breakdown of prices. |
options | Object |
Additional Telegram query options. |
Example:
client;
answerShippingQuery(shippingQueryId, ok [, options])
- Official Docs
Reply to shipping queries.
Param | Type | Description |
---|---|---|
shippingQueryId | String |
Unique identifier for the query to be answered. |
ok | Boolean |
Specify if delivery of the product is possible. |
options | Object |
Additional Telegram query options. |
Example:
client;
answerPreCheckoutQuery(preCheckoutQueryId, ok [, options])
- Official Docs
Respond to such pre-checkout queries.
Param | Type | Description |
---|---|---|
preCheckoutQueryId | String |
Unique identifier for the query to be answered. |
ok | Boolean |
Specify if delivery of the product is possible. |
options | Object |
Additional Telegram query options. |
Example:
client;
Inline mode API
answerInlineQuery(inlineQueryId, results [, options])
- Official Docs
Send answers to an inline query.
Param | Type | Description |
---|---|---|
inlineQueryId | String |
Unique identifier of the query. |
results | Array<InlineQueryResult> | Array of object represents one result of an inline query. |
options | Object |
Additional Telegram query options. |
Example:
client;
Game API
sendGame(chatId, gameShortName [, options])
- Official Docs
Sends a game.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target channel. |
gameShortName | String | Short name of the game. |
options | Object |
Additional Telegram query options. |
Example:
client;
setGameScore(userId, score [, options])
- Official Docs
Sets the score of the specified user in a game.
Param | Type | Description |
---|---|---|
userId | Number | String |
User identifier. |
score | Number | New score, must be non-negative. |
options | Object |
Additional Telegram query options. |
Example:
client;
getGameHighScores(userId [, options])
- Official Docs
Gets data for high score tables.
Param | Type | Description |
---|---|---|
userId | Number | String |
User identifier. |
options | Object |
Additional Telegram query options. |
Example:
client;
Others
forwardMessage(chatId, fromChatId, messageId [, options])
- Official Docs
Forwards messages of any kind.
Param | Type | Description |
---|---|---|
chatId | Number | String |
Unique identifier for the target chat or username of the target supergroup or channel. |
fromChatId | Number | String |
Unique identifier for the chat where the original message was sent. |
messageId | Number |
Message identifier in the chat specified in from_chat_id. |
options | Object |
Other optional parameters. |
Example:
client;
Debug Tips
Log requests details
To enable default request debugger, use following DEBUG
env variable:
DEBUG=messaging-api-telegram-proxy
If you want to use custom request logging function, just define your own onRequest
:
const client = TelegramClient;
Test
Point requests to your dummy server
To avoid sending requests to real Telegram server, specify origin
option when constructing your client:
const TelegramClient = ; const client = TelegramClient;
Warning: Don't do this on production server.
Jest
Manual Mock withcreate __mocks__/messaging-api-telegram-proxy.js
in your project root:
// __mocks__/messaging-api-telegram-proxy.jsconst jestMock = ;const TelegramClient = require; moduleexports = TelegramClient: connect: jest ;
Then, mock messaging-api-telegram-proxy
package in your tests:
// __tests__/mytest.spec.jsjest;