/tglib

TDLib (Telegram Database library) bindings for Node.js

Primary LanguageJavaScript

tglib

TDLib (Telegram Database library) bindings for Node.js

npm

Getting started

  1. Build the binary (https://github.com/tdlib/td#building)
  2. npm i -S tglib

APIs

tglib provide some useful methods that makes your Telegram app development easier.

Authorizing an user

const client = new Client({
  apiId: 'YOUR_API_ID',
  apiHash: 'YOUR_API_HASH',
  auth: {
    type: 'user',
    value: 'YOUR_PHONE_NUMBER',
  },
})

Authorizing a bot

const client = new Client({
  apiId: 'YOUR_API_ID',
  apiHash: 'YOUR_API_HASH',
  auth: {
    type: 'bot',
    value: 'YOUR_BOT_TOKEN',
  },
})

Low Level APIs

client.ready

This promise is used for initializing tglib client and connect with Telegram.

await client.ready
client.registerCallback(key, callback) -> Void
Expand

This API is provided by tglib, you can use this API to register your function in order to receive callbacks.

The authorization process can be overridden here by registering td:getInput callback.

client.registerCallback('td:update', (update) => console.log(update))
client.registerCallback('td:error', (error) => console.error(error))
client.registerCallback('td:getInput', async (args) => {
  const result = await getInputFromUser(args)
  return result
})

client._send(query) -> Promise -> Object
Expand

This API is provided by TDLib, you can use this API to send asynchronous message to Telegram.

await client._send({
  '@type': 'sendMessage',
  'chat_id': -123456789,
  'input_message_content': {
    '@type': 'inputMessageText',
    'text': {
      '@type': 'formattedText',
      'text': '👻',
    },
  },
})

client._execute(query) -> Promise -> Object
Expand

This API is provided by TDLib, you can use this API to execute synchronous action to Telegram.

await client._execute({
  '@type': 'getTextEntities',
  'text': '@telegram /test_command https://telegram.org telegram.me',
})

client._destroy() -> Promise -> Void
Expand

This API is provided by TDLib, you can use this API to destroy the client.

await client._destroy()

client.fetch(query) -> Promise -> Object
Expand

This API is provided by tglib, you can use this API to send asynchronous message to Telegram and receive response.

const chats = await client.fetch({
  '@type': 'getChats',
  'offset_order': '9223372036854775807',
  'offset_chat_id': 0,
  'limit': 100,
})

High Level APIs

tglib provides a collection of APIs that designed for ease of use and handiness. These APIs are located under client.tg property.

client.tg.sendTextMessage(args = {}) -> Promise -> Void
Expand

This API is provided by tglib, you can use this API to send message to a chat. The function will combine custom options specified in args with its default.

The TextStruct struct uses "parseTextEntities" method which requires TDLib 1.1.0 or above, see TDLib changelog for details.

const { TextStruct } = require('tglib/structs')

await client.tg.sendTextMessage({
  '$text': new TextStruct('`Hello` world!', 'textParseModeMarkdown'),
  'chat_id': 123456789,
  'disable_notification': true,
  'clear_draft': false,
})

client.tg.sendPhotoMessage(args = {}) -> Promise -> Void
Expand

This API is provided by tglib, you can use this API to send photo to a chat. The function will combine custom options specified in args with its default.

The TextStruct struct uses "parseTextEntities" method which requires TDLib 1.1.0 or above, see TDLib changelog for details.

const { TextStruct } = require('tglib/structs')

await client.tg.sendPhotoMessage({
  '$caption': new TextStruct('Such doge much wow'),
  'chat_id': 123456789,
  'path': '/tmp/doge.jpg',
  'ttl': 5,
})

client.tg.updateUsername(username, supergroupId = null) -> Promise -> Void
Expand

This API is provided by tglib, you can use this API to update the username for session user or a supergroup chat.

This API uses "checkChatUsername" method which requires TDLib 1.2.0 or above, see TDLib changelog for details.

await client.tg.updateUsername('a_new_username')

client.tg.getAllChats() -> Promise -> Array
Expand

This API is provided by tglib, you can use this API to get all available chats of session user.

const chats = await client.tg.getAllChats()

client.tg.openSecretChat(userId) -> Promise -> Object
Expand

This API is provided by tglib, you can use this API to open a secret chat with given user ID.

Note: Secret chats are associated with the corresponding TDLib folder. (i.e. only available on the same device).

const chat = await client.tg.openSecretChat(123456789)

client.tg.deleteChat(chatId) -> Promise -> Void
Expand

This API is provided by tglib, you can use this API to delete a chat and remove it from the chat list. You can use this API to delete "private", "secret", "basicGroup", and "supergroup" chats.

await client.tg.deleteChat(-12345678901234)

client.tg.getChat(args = {}) -> Promise -> Object
Expand

This API is provided by tglib, you can use this API to get a chat by username or chat id. This method requires either username option, or chat_id option.

const chat1 = await client.tg.getChat({ username: 'chat_username' })
const chat2 = await client.tg.getChat({ chat_id: '-12345678901234' })

Requirements

  • Node.js 10 preferred (minimum >= 9.0.0)

Note: If you are using Node.js 9.x, you may encounter a warning message Warning: N-API is an experimental feature and could change at any time., this can be suppressed by upgrading to version 10.

  • TDLib binary (see build instructions below)

Windows

macOS

Linux - CentOS 7.5

Note: building TDLib binary requires at least 8GB of memory, otherwise building process will fail.

License

tglib uses the same license as TDLib. See tdlib/td for more information.