API Reference

May 7, 2026 · View on GitHub

All methods return Promise. Legacy methods resolve with a JSON string; newer methods resolve with a typed {raw: string} wrapper (TdRawResult) and in some cases extra structured fields.

The authoritative contract is index.d.ts. This page is a readable overview grouped by purpose.

Authorization

Method	Signature	Returns
`startTdLib`	`(params: TdLibParameters)`	`Promise<string>` — idempotent; safe to call repeatedly.
`login`	`(details: UserDetails)`	`Promise<string>` — submits phone number.
`verifyPhoneNumber`	`(code: string)`	`Promise<string>`
`verifyPassword`	`(password: string)`	`Promise<string>`
`getAuthorizationState`	`()`	`Promise<string>` — JSON `{@type: "authorizationState..."}`.
`getProfile`	`()`	`Promise<string>` — JSON of current `user`.
`logout`	`()`	`Promise<string>` — auto-resets native client so next `startTdLib` starts fresh.
`destroy`	`()`	`Promise<string>` — deletes all local TDLib data.

interface TdLibParameters {
  api_id: number;
  api_hash: string;
  system_language_code?: string;
  device_model?: string;
  system_version?: string;
  application_version?: string;
}

interface UserDetails {
  countrycode: string;
  phoneNumber: string;
}

Chats

Method	Signature	Returns
`loadChats`	`(limit: number)`	`Promise<string>` — resolves `"No more chats to load"` when you've reached the end.
`getChats`	`(limit: number)`	`Promise<string>` — JSON array of full chat objects.
`getChat`	`(chatId: number)`	`Promise<TdRawResult>`
`openChat`	`(chatId: number)`	`Promise<TdRawResult>` — tells TDLib the user is viewing this chat.
`closeChat`	`(chatId: number)`	`Promise<{success: boolean}>`
`searchChats`	`(query: string, limit: number)`	`Promise<string>` — JSON array of full chat objects matching query.
`searchPublicChat`	`(username: string)`	`Promise<string>` — lookup `@username`.
`joinChat`	`(chatId: number)`	`Promise<TdRawResult>`
`leaveChat`	`(chatId: number)`	`Promise<TdRawResult>`
`createPrivateChat`	`(userId: number)`	`Promise<string>`
`getChatMember`	`(chatId: number, userId: number)`	`Promise<TdRawResult>`
`getSupergroup`	`(supergroupId: number)`	`Promise<TdRawResult>`

Messages

Method	Signature	Returns
`sendMessage`	`(chatId, text, replyToMessageId?)`	`Promise<TdRawResult>` — `replyToMessageId` is optional; pass `0`/omit for a plain message.
`getMessage`	`(chatId, messageId)`	`Promise<TdRawResult>`
`getChatHistory`	`(chatId, fromMessageId, limit, offset)`	`Promise<Array<{raw_json: string}>>`
`getMessagesCompat`	`(chatId, messageIds)`	`Promise<string>` — bulk fetch.
`viewMessages`	`(chatId, messageIds, forceRead)`	`Promise<string>` — marks messages as read using `messageSourceChatHistory`.
`getChatMessagePosition`	`(chatId, messageId, threadId)`	`Promise<{raw: string, count?: number}>`
`getMessageThread`	`(chatId, messageId)`	`Promise<TdRawResult>`
`getMessageThreadHistory`	`(chatId, threadId, fromMessageId, offset, limit)`	`Promise<TdRawResult>`
`deleteMessages`	`(chatId, messageIds, revoke?)`	`Promise<boolean>` — deletes one or more messages; `revoke` defaults to `true` (delete for everyone when TDLib allows it).

Comments (channel / forum threads)

Method	Signature	Returns
`addComment`	`(chatId, threadId, replyToMessageId, text)`	`Promise<string>`
`deleteComment`	`(chatId, messageId)`	`Promise<boolean>`

Reactions

Method	Signature	Returns
`addMessageReaction`	`(chatId, messageId, emoji)`	`Promise<string>`
`removeMessageReaction`	`(chatId, messageId, emoji)`	`Promise<string>`
`getAddedReactions`	`(chatId, messageId)`	`Promise<TdRawResult>`

Users

Method	Signature	Returns
`getUserProfile`	`(userId)`	`Promise<string>`
`getUserFull`	`(userId)`	`Promise<string>`
`getUserProfilePhotos`	`(userId, offset, limit)`	`Promise<string>`
`getUsersCompat`	`(userIds: number[])`	`Promise<string>` — bulk.

Files

Method	Signature	Returns
`downloadFile`	`(fileId)`	`Promise<TdRawResult>` — synchronous; waits for the whole file. For UI avatars/previews prefer fire-and-forget via `td_json_client_send` — see the Cookbook.
`downloadFileByRemoteId`	`(remoteId)`	`Promise<TdRawResult>`
`cancelDownloadFile`	`(fileId, onlyIfPending)`	`Promise<TdRawResult>`
`cancelDownloadByRemoteId`	`(remoteId, onlyIfPending)`	`Promise<TdCancelDownloadByRemoteIdResult>`
`getFile`	`(fileId)`	`Promise<TdRawResult>`

Options

Method	Signature	Returns
`getOption`	`(name: string)`	`Promise<string \| null>` — value is coerced to string (`null` for empty).
`setOption`	`(name: string, value: SetOptionValue)`	`Promise<string>`

interface SetOptionValue {
  type: 'string' | 'integer' | 'boolean' | 'empty';
  value?: string | number | boolean;
}

Events & utilities

Method	Signature	Notes
`addListener`	`(eventName: string)`	`RCTEventEmitter` glue — required by RN.
`removeListeners`	`(count: number)`	same.
`echoToJs`	`(payload)`	Round-trips a value through native and back. Useful for bridge sanity checks.

Low-level JSON client

Escape hatch for TDLib functions not yet wrapped with a dedicated method (registerDevice, sendChatAction, custom queries):

Method	Signature	Notes
`td_json_client_create`	`()`	Creates a client. `startTdLib` does this for you.
`td_json_client_execute`	`(request)`	Synchronous, doesn't require auth (e.g. `getTextEntities`).
`td_json_client_send`	`(request)`	Fire-and-forget. Response, if any, arrives via `tdlib-update`.
`td_json_client_receive`	`()`	Blocking receive — only usable when the high-level API is not running.

Text helpers

Method	Signature	Returns
`getTextEntities`	`(text: string)`	`Promise<string>` — parses Telegram entities like mentions, hashtags, bot commands, and URLs from plain text.

Result types

interface TdRawResult {
  raw: string; // raw TDLib JSON string
}

interface TdChatHistoryItem {
  raw_json: string; // raw TDLib JSON of a single message
}

interface TdChatMessagePositionResult extends TdRawResult {
  count?: number;
}

interface TdCancelDownloadByRemoteIdResult extends TdRawResult {
  tdFileId?: number;
  remoteFileId?: string;
  error?: string;
  message?: string;
}

interface TdLibUpdateEvent {
  type: string; // e.g. "updateNewMessage"
  raw:  string; // raw TDLib JSON
}