Modern Telegram client framework for TypeScript/JavaScript.
Important: this documentation is for version 1.*
. If you need MTProto implementation (version 0.1.*
), please follow the link.
- Based on TDLib;
- Strictly typed;
- Documentation out of the box;
- Supports models;
- Built on middleware;
- Authorization helper;
All TDLib classes and methods are described and have suitable wrappers in Airgram. There are only two differences:
- All parameter names are represent in "camelCase".
- Parameter
@type
renamed to_
.
- TDLib v1.3.0
- NodeJS
- Installation
- Getting started
- Configuration
- Api reference
- Authorization
- Middleware
- Getting updates
- Models
- Build TDLib library according the instruction.
- Install Airgram:
# npm
npm install airgram
# yarn
yarn add airgram
Please check out an example.
Basic usage:
import { Airgram, Auth, prompt } from 'airgram'
const airgram = new Airgram({
apiId: Number(process.env.APP_ID!),
apiHash: process.env.APP_HASH!
})
const auth = new Auth(airgram)
auth.use({
code: () => prompt(`Please enter the secret code:\n`),
phoneNumber: () => prompt(`Please enter your phone number:\n`)
})
// Call Telegram method
airgram.api.getMe().then((response) => {
console.info(response)
})
// Getting all updates
airgram.updates.use(({ update }, next) => {
if(update) {
console.log(`"${update._}" ${JSON.stringify(update)}`)
}
return next()
})
// Get only new message updates
airgram.updates.on('updateNewMessage', ({ update }, next) => {
console.info(update)
return next
})
This section describes the options you can pass to Airgram
constructor:
import { Airgram } from 'airgram'
const airgram = new Airgram({
// options
})
Key | Type | Note |
---|---|---|
command |
string |
Path to the tdjson (windows) / libtdjson (unix) command. |
useTestDc |
boolean |
If set to true, the Telegram test environment will be used instead of the production environment |
databaseDirectory |
string |
The path to the directory for the persistent database |
filesDirectory |
string |
The path to the directory for storing files |
useFileDatabase |
boolean |
If set to true, information about downloaded and uploaded files will be saved between application restarts |
useChatInfoDatabase |
boolean |
If set to true, the library will maintain a cache of users, basic groups, supergroups, channels and secret chats. Implies useFileDatabase |
useMessageDatabase |
boolean |
If set to true, the library will maintain a cache of chats and messages. Implies useChatInfoDatabase |
useSecretChats |
boolean |
If set to true, support for secret chats will be enabled |
apiId |
number |
Application identifier for Telegram API access, which can be obtained at https://my.telegram.org |
apiHash |
string |
Application identifier hash for Telegram API access, which can be obtained at https://my.telegram.org |
systemLanguageCode |
string |
IETF language tag of the user's operating system language |
deviceModel |
string |
Model of the device the application is being run on |
systemVersion |
string |
Version of the operating system the application is being run on |
applicationVersion |
string |
Application version |
enableStorageOptimizer |
boolean |
If set to true, old files will automatically be deleted |
ignoreFileNames |
boolean |
If set to true, original file names will be ignored. Otherwise, downloaded files will be saved under names as close as possible to the original name |
logFilePath |
string |
Path to a file where the internal TDLib log will be written. Use an empty path to switch back to the default logging behaviour. |
logMaxFileSize |
number |
Maximum size of the file to where the internal TDLib log is written before the file will be auto-rotated. Should be positive. |
logVerbosityLevel |
number |
New value of the verbosity level for logging. Value 0 corresponds to fatal errors, value 1 corresponds to errors, value 2 corresponds to warnings and debug warnings, value 3 corresponds to informational, value 4 corresponds to debug, value 5 corresponds to verbose debug, value greater than 5 and up to 1024 can be used to enable even more logging. |
databaseEncryptionKey |
string |
Encryption key |
client |
any |
Instance of the TDLib JSON client that you can share between threads. |
Key | Type | Note |
---|---|---|
models |
Object | Contains models, which replace plain JSON objects. Details. |
contextFactory |
Function | Function that returns custom middleware context. Details. |
This section describes public API of an Airgram
instance:
Key | Type | Note |
---|---|---|
api |
Object | Contains wrappers for all TDLib methods. |
config |
Object | Airgram configuration. Readonly. |
client |
any |
Instance of TDLib JSON client that you can share between threads. Readonly. |
handleError |
Function | Error handler. Can be overriden by airgram.catch() . |
catch |
(handler) => void |
Overrides default error handler. Argument handler takes a function: (error: Error, ctx?: Record<string, any>) => void |
pause |
() => void |
Stop getting responses and updates from TDLib |
resume |
() => void |
Continue getting responses and updates from TDLib |
destroy |
() => void |
Destroy Airgram and TDLib instances |
Just specify a secret token by Auth
constructor:
import { Airgram, Auth } from 'airgram'
const airgram = new Airgram(/* options */)
new Auth(airgram, {
token: 'xxx'
})
Airgram provides component Auth
, which implements basic logic for authorization or registration new Telegram accounts. User just needs to specify the phone number, secret code and some other data, if necessary.
import { Airgram, Auth } from 'airgram'
const airgram = new Airgram()
const auth = new Auth(airgram)
auth.use({
phoneNumber: '+1234567890',
firstName: 'John',
lastName: 'Smith'
})
Method auth.use()
takes config:
type AuthAnswer = string | (() => string) | (() => Promise<string>)
interface AuthDialog {
code?: AuthAnswer
firstName?: AuthAnswer
lastName?: AuthAnswer,
phoneNumber?: AuthAnswer
password?: AuthAnswer
}
You can use helper prompt
to communicate with user by the command line:
import { prompt } from 'airgram'
auth.use({
code: () => prompt(`Please enter the secret code:\n`),
phoneNumber: () => prompt(`Please enter your phone number:\n`)
})
If you want to ensure the code will execute only after successful authorization, you can use auth.ready()
method:
auth.ready().then(() => {
console.log('Success!')
})
// or pass callback
auth.ready(() => {
console.log('Success!')
})
Middleware is a chain of callback functions, which are called before a request is send to TDLib. Middleware allows you modify requests and responses to add some additional logic. Middlewares also are using to handle updates.
This is a scaffolding for middleware function:
import { UPDATE } from 'airgram-api'
airgram.use((ctx, next) => {
// Add some code here
return next()
})
// You can pass an array of predicates: `['updateNewChat', 'updateSupergroup']`
airgram.on(UPDATE.updateNewChat, (ctx, next) => {
// Add some code here
return next()
})
Tip: in the example above we took predicate's value from the UPDATE
directory instead of using string value updateNewChat
, because this way protects us from typos and we can use IDE autocomplete.
Function takes 2 arguments: ctx
and next
.
Argument ctx
contains an object with the following structure:
Key | Type | Note |
---|---|---|
_ |
string |
Request (or update) type. |
airgram |
Airgram |
Instance of Airgram . |
getState |
() => Object |
Returns current state. |
setState |
Function | A function that takes either a new state object, or a function which receives the previous state and returns a new one. It behaves similarly to setState from React. |
request |
{ method: string, params: Object } |
Object which contains method and parameters of the request. Value will be undefined for updates. |
response |
Object | Object which contains response data from TDLib. Field will be undefined if the request has not handled. |
update |
Object | This field is available only for updates. |
You can extend default context by define contextFactory
:
import { ag, api, Airgram, createContext, User } from 'airgram'
import { UPDATE } from 'airgram-api'
interface Context extends ag.Context {
getUser (id: number): User | void
setUser (id: number, user: User): void
}
const userMap: Map<number, User> = new Map()
const contextFactory: ag.ContextFactory = () => {
return (options: ag.ContextOptions): Context => ({
...createContext(options),
getUser (id: number): User | void {
return userMap.get(id)
},
setUser (id: number, user: User): void {
userMap.set(id, user)
}
})
}
const airgram = new Airgram<Context>({
contextFactory
})
airgram.updates.on(UPDATE.updateUser, ({ setUser, update }, next) => {
setUser(update.user.id, update.user)
return next()
})
airgram.updates.on(UPDATE.updateNewMessage, async ({ getUser, update }) => {
const user = getUser(update.message.senderUserId)
if (!user) {
throw new Error('Unknown user')
}
console.log(`${user.username}: ${JSON.stringify(update.message)}`)
})
Since middlewares are meant to be composed, they need an easy way to send metadata about the request down the chain of middleware. To accomplish this, each middleware context has a state object. The state is read by using ctx.getState()
and written using ctx.setState(newState)
or ctx.setState((prevState) => newState)
. The API of setState
is meant to be similar to React's one. For example:
airgram.use(({ setState }, next) => {
setState({ foo: 'bar' })
return next()
})
airgram.use(async ({ getState }) => {
console.log(`foo = ${getState().foo}`);
// output: foo = bar
})
Each state can be set by the last argument of the request:
// We can set starting state by the last argument
airgram.api.getChats({limit: 10}, {log: true})
airgram.on('getChats', async ({ _, getState }, next) => {
if(!getState().log) {
return next()
}
const start = new Date()
await next()
const time = new Date() - start;
console.log(`Request "${_}" took ${time} to complete.`);
})
The second argument next
is a function which runs the next handler.
Function next()
returns a promise Promise<any>
, so we can use the next handlers result inside of our middleware:
airgram.use(async (ctx, next) => {
const start = new Date()
const { request } = ctx
const result = await next()
console.log(`Method: ${request.method}, params: ${JSON.stringify(request.params)}, result: ${JSON.stringify(result)}, ${new Date() - start}ms`)
})
Sometimes middleware may be pretty complicated or you want to reuse the code. In this case the most suitable way is to create new class (or use existing) and pass it to use()
or on()
methods.
Your class must have a middleware()
factory method:
class MiddlewareClass {
handle(ctx) {
// do some work
}
middleware() {
return (ctx, next) => {
this.handle(ctx)
return next()
}
}
}
airgram.use(new MiddlewareClass())
All methods describes here.
Use methods airgram.updates.use()
and airgram.updates.on()
to add some handlers for updates. It works almost the same as airgram.use()
and airgram.on()
, but there are two differences:
- By using
airgram.updates.use()
andairgram.updates.on()
methods, callbacks won't be called for requests; - Improved typings for updates.
Airgram provide an excellent feature to create your own models for plain JSON objects which returned by TDLib.
For example, lets add some features to the Chat:
import { Airgram } from 'airgram'
import { ApiMethods, CHAT_TYPE, UPDATE } from 'airgram-api'
import { ChatBaseModel } from 'airgram-api/models/Chat'
class ChatModel extends ChatBaseModel {
get isBasicGroup (): boolean {
return this.type._ === CHAT_TYPE.chatTypeBasicGroup
}
get isSupergroup (): boolean {
return this.type._ === CHAT_TYPE.chatTypeSupergroup
}
get isPrivateChat (): boolean {
return this.type._ === CHAT_TYPE.chatTypePrivate
}
get isSecretChat (): boolean {
return this.type._ === CHAT_TYPE.chatTypeSecret
}
public async isMeChat (api: ApiMethods): Promise<boolean> {
if ('userId' in this.type) {
return (await api.getMe()).id === this.type.userId
}
return false
}
}
// This is important for correct typings
declare module 'airgram-api/outputs/Chat' {
export interface Chat extends ChatModel {}
}
const airgram = new Airgram({
models: {
chat: ChatModel
}
})
airgram.updates.on(UPDATE.updateNewChat, async ({ update }) => {
const { chat } = update
console.info('isBasicGroup: ', chat.isBasicGroup)
console.info('isSupergroup: ', chat.isSupergroup)
console.info('isPrivateChat: ', chat.isPrivateChat)
console.info('isSecretChat: ', chat.isSecretChat)
console.info('isMeChat: ', await chat.isMeChat(airgram.api))
})
The source code is licensed under GPL v3. License is available here.