Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src
README.md
package.json

README.md

messaging-api-telegram

Messaging API client for Telegram

Telegram

Table of Contents

Installation

npm i --save messaging-api-telegram

or

yarn add messaging-api-telegram

Usage

Initialize

const { TelegramClient } = require('messaging-api-telegram');

// get accessToken from telegram [@BotFather](https://telegram.me/BotFather)
const client = TelegramClient.connect('12345678:AaBbCcDdwhatever');

Error Handling

messaging-api-telegram 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.getWebhookInfo().catch(error => {
  console.log(error); // formatted error message
  console.log(error.stack); // error stack trace
  console.log(error.config); // axios request config
  console.log(error.request); // HTTP request
  console.log(error.response); // HTTP response
});

API Reference

All methods return a Promise.


Webhook API

getWebhookInfo - Official Docs

Gets current webhook status.

Example:

client.getWebhookInfo().then(info => {
  console.log(info);
  // {
  //   url: 'https://4a16faff.ngrok.io/',
  //   has_custom_certificate: false,
  //   pending_update_count: 0,
  //   max_connections: 40,
  // }
});

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
  .getUpdates({
    limit: 10,
  })
  .then(updates => {
    console.log(updates);
    /*
      [
        {
          update_id: 513400512,
          message: {
            message_id: 3,
            from: {
              id: 313534466,
              first_name: 'first',
              last_name: 'last',
              username: 'username',
            },
            chat: {
              id: 313534466,
              first_name: 'first',
              last_name: 'last',
              username: 'username',
              type: 'private',
            },
            date: 1499402829,
            text: 'hi',
          },
        },
        ...
      ]
    */
  });

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.setWebhook('https://4a16faff.ngrok.io/');

deleteWebhook - Official Docs

Removes webhook integration.

Example:

client.deleteWebhook();

Send API - Official Docs

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.

Exmaple:

client.sendMessage(CHAT_ID, 'hi', {
  disable_web_page_preview: true,
  disable_notification: true,
});

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.sendPhoto(CHAT_ID, 'https://example.com/image.png', {
  caption: 'gooooooodPhoto',
  disable_notification: true,
});

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.sendAudio(CHAT_ID, 'https://example.com/audio.mp3', {
  caption: 'gooooooodAudio',
  disable_notification: true,
});

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.sendDocument(CHAT_ID, 'https://example.com/doc.gif', {
  caption: 'gooooooodDocument',
  disable_notification: true,
});

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.sendSticker(CHAT_ID, 'CAADAgADQAADyIsGAAE7MpzFPFQX5QI', {
  disable_notification: true,
});

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.sendVideo(CHAT_ID, 'https://example.com/video.mp4', {
  caption: 'gooooooodVideo',
  disable_notification: true,
});

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.sendVoice(CHAT_ID, 'https://example.com/voice.ogg', {
  caption: 'gooooooodVoice',
  disable_notification: true,
});

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.sendVideoNote(CHAT_ID, 'https://example.com/video_note.mp4', {
  duration: 40,
  disable_notification: true,
});

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.sendMediaGroup(CHAT_ID, [
  { type: 'photo', media: 'BQADBAADApYAAgcZZAfj2-xeidueWwI' },
]);

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.sendLocation(
  CHAT_ID,
  {
    latitude: 30,
    longitude: 45,
  },
  {
    disable_notification: true,
  }
);

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.sendVenue(
  CHAT_ID,
  {
    latitude: 30,
    longitude: 45,
    title: 'a_title',
    address: 'an_address',
  },
  {
    disable_notification: true,
  }
);

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.sendContact(
  CHAT_ID,
  {
    phone_number: '886123456789',
    first_name: 'first',
  },
  { last_name: 'last' }
);

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.sendChatAction(CHAT_ID, 'typing');

Get API

getMe - Official Docs

Gets bot's information.

Example:

client.getMe().then(result => {
  console.log(result);
  // {
  //   id: 313534466,
  //   first_name: 'first',
  //   username: 'a_bot'
  // }
});

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.getUserProfilePhotos(USER_ID, { limit: 1 }).then(result => {
  console.log(result);
  // {
  //   total_count: 3,
  //   photos: [
  //     [
  //       {
  //         file_id:
  //           'AgADBAADGTo4Gz8cZAeR-ouu4XBx78EeqRkABHahi76pN-aO0UoDA050',
  //         file_size: 14650,
  //         width: 160,
  //         height: 160,
  //       },
  //       {
  //         file_id:
  //           'AgADBAADGTo4Gz8cZAeR-ouu4XBx78EeqRkABKCfooqTgFUX0EoD5B1C',
  //         file_size: 39019,
  //         width: 320,
  //         height: 320,
  //       },
  //       {
  //         file_id:
  //           'AgADBAADGTo4Gz8cZAeR-ouu4XBx78EeqRkABPL_pC9K3UpI0koD1B1C',
  //         file_size: 132470,
  //         width: 640,
  //         height: 640,
  //       },
  //     ],
  //   ],
  // }
});

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
  .getFile('UtAqweADGTo4Gz8cZAeR-ouu4XBx78EeqRkABPL_pM4A1UpI0koD65K2')
  .then(file => {
    console.log(file);
    // {
    //   file_id: 'UtAqweADGTo4Gz8cZAeR-ouu4XBx78EeqRkABPL_pM4A1UpI0koD65K2',
    //   file_size: 106356,
    //   file_path: 'photos/1068230105874016297.jpg',
    // }
  });

getFileLink(fileId)

Gets link of the file.

Param Type Description
fileId String File identifier to get info about.

Example:

client
  .getFileLink('UtAqweADGTo4Gz8cZAeR-ouu4XBx78EeqRkABPL_pM4A1UpI0koD65K2')
  .then(link => {
    console.log(link);
    // 'https://api.telegram.org/file/bot<ACCESS_TOKEN>/photos/1068230105874016297.jpg'
  });

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.getChat(CHAT_ID).then(chat => {
  console.log(chat);
  // {
  //   id: 313534466,
  //   first_name: 'first',
  //   last_name: 'last',
  //   username: 'username',
  //   type: 'private',
  // }
});

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.getChatAdministrators(CHAT_ID).then(admins => {
  console.log(admins);
  // [
  //   {
  //     user: {
  //       id: 313534466,
  //       first_name: 'first',
  //       last_name: 'last',
  //       username: 'username',
  //       languange_code: 'zh-TW',
  //     },
  //     status: 'creator',
  //   },
  // ]
});

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.getChatMembersCount(CHAT_ID).then(count => {
  console.log(count); // '6'
});

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.getChatMember(CHAT_ID, USER_ID).then(member => {
  console.log(member);
  // {
  //   user: {
  //     id: 313534466,
  //     first_name: 'first',
  //     last_name: 'last',
  //     username: 'username',
  //     languange_code: 'zh-TW',
  //   },
  //   status: 'creator',
  // }
});

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.editMessageText('new_text', { message_id: MESSAGE_ID });

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.editMessageCaption('new_caption', { message_id: MESSAGE_ID });

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.editMessageReplyMarkup(
  {
    keyboard: [[{ text: 'new_button_1' }, { text: 'new_button_2' }]],
    resize_keyboard: true,
    one_time_keyboard: true,
  },
  { message_id: MESSAGE_ID }
);

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.deleteMessage(CHAT_ID, MESSAGE_ID);

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.editMessageLiveLocation(
  {
    latitude: 30,
    longitude: 45,
  },
  {
    message_id: MESSAGE_ID,
  }
);

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.stopMessageLiveLocation({ message_id: MESSAGE_ID });

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.kickChatMember(CHAT_ID, USER_ID, { until_date: UNIX_TIME });

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.unbanChatMember(CHAT_ID, USER_ID);

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.restrictChatMember(CHAT_ID, USER_ID, { can_send_messages: true });

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.promoteChatMember(CHAT_ID, USER_ID, {
  can_change_info: true,
  can_invite_users: true,
});

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.exportChatInviteLink(CHAT_ID);

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.setChatPhoto(CHAT_ID, 'https://example.com/image.png');

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.deleteChatPhoto(CHAT_ID);

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.setChatTitle(CHAT_ID, 'New Title');

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.setChatDescription(CHAT_ID, 'New Description');

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.setChatStickerSet(CHAT_ID, 'Sticker Set Name');

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.deleteChatStickerSet(CHAT_ID);

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.pinChatMessage(CHAT_ID, MESSAGE_ID, { disable_notification: true });

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.unpinChatMessage(CHAT_ID);

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.leaveChat(CHAT_ID);

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.sendInvoice(CHAT_ID, {
  title: 'product name',
  description: 'product description',
  payload: 'bot-defined invoice payload',
  provider_token: 'PROVIDER_TOKEN',
  start_parameter: 'pay',
  currency: 'USD',
  prices: [
    { label: 'product', amount: 11000 },
    { label: 'tax', amount: 11000 },
  ],
});

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.answerShippingQuery('UNIQUE_ID', true);

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.answerPreCheckoutQuery('UNIQUE_ID', true);

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.answerInlineQuery(
  'INLINE_QUERY_ID',
  [
    {
      type: 'photo',
      id: 'UNIQUE_ID',
      photo_file_id: 'FILE_ID',
      title: 'PHOTO_TITLE',
    },
    {
      type: 'audio',
      id: 'UNIQUE_ID',
      audio_file_id: 'FILE_ID',
      caption: 'AUDIO_TITLE',
    },
  ],
  {
    cache_time: 1000,
  }
);

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.sendGame(CHAT_ID, 'Mario Bros.', {
  disable_notification: true,
});

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.setGameScore(USER_ID, 999);

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.getGameHighScores(USER_ID).then(scores => {
  console.log(scores);
  // [
  //   {
  //     position: 1,
  //     user: {
  //       id: 427770117,
  //       is_bot: false,
  //       first_name: 'first',
  //     },
  //     score: 999,
  //   },
  // ]
});

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.forwardMessage(CHAT_ID, USER_ID, MESSAGE_ID, {
  disable_notification: true,
});

Debug Tips

Log requests details

To enable default request debugger, use following DEBUG env variable:

DEBUG=messaging-api-telegram

If you want to use custom request logging function, just define your own onRequest:

const client = TelegramClient.connect({
  accessToken: ACCESS_TOKEN,
  onRequest: ({ method, url, headers, body }) => {
    /* */
  },
});

Test

Point requests to your dummy server

To avoid sending requests to real Telegram server, specify origin option when constructing your client:

const { TelegramClient } = require('messaging-api-telegram');

const client = TelegramClient.connect({
  accessToken: ACCESS_TOKEN,
  origin: 'https://mydummytestserver.com',
});

Warning: Don't do this on production server.

Manual Mock with Jest

create __mocks__/messaging-api-telegram.js in your project root:

// __mocks__/messaging-api-telegram.js
const jestMock = require('jest-mock');
const { TelegramClient } = require.requireActual('messaging-api-telegram');

module.exports = {
  TelegramClient: {
    connect: jest.fn(() => {
      const Mock = jestMock.generateFromMetadata(
        jestMock.getMetadata(TelegramClient)
      );
      return new Mock();
    }),
  },
};

Then, mock messaging-api-telegram package in your tests:

// __tests__/mytest.spec.js
jest.mock('messaging-api-telegram');