mtcute

https://mtcute.dev/guide
Admin
mtcute is a TypeScript/JavaScript Telegram client library that uses MTProto protocol for direct...
Tokens:75,049
Snippets:744
Trust Score:5.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install @mtcute/postgres and pg

Source: https://mtcute.dev/guide/topics/storage

Install the PostgreSQL storage package and the pg client library.

```bash
pnpm add @mtcute/postgres pg
```

--------------------------------

### Install using-mtcute skill via skills.sh

Source: https://mtcute.dev/guide/intro/llm-assistance

Installs the experimental using-mtcute skill from the mtcute repository using the skills.sh CLI. The skill explains basics and includes scripts for searching the API surface.

```bash
pnpx skills add https://github.com/mtcute/mtcute --skill using-mtcute
```

--------------------------------

### Install @mtcute/web with pnpm

Source: https://mtcute.dev/guide

Installs the @mtcute/web package for browser usage. Recommended with Vite.

```bash
pnpm add @mtcute/web
```

--------------------------------

### Create and start a client with @mtcute/node

Source: https://mtcute.dev/guide

Creates a TelegramClient with your API ID and hash, starts it, and sends a formatted message. Replace API_ID and API_HASH with your credentials from my.telegram.org/apps.

```ts
import { TelegramClient, html } from '@mtcute/node'

const tg = new TelegramClient({
  apiId: API_ID,
  apiHash: 'API_HASH'
})

const self = await tg.start({ ... })
console.log(`Logged in as ${self.displayName}`)

await tg.sendText('self', html`Hello from <b>mtcute</b>!`)
```

--------------------------------

### Throttle a start command handler with state.throttle

Source: https://mtcute.dev/guide/dispatcher/rate-limit

Use `state.throttle` to throttle a user instead of rate-limiting. When the limit is reached, it waits until the limit is replenished and then returns. The example limits to 2 requests per second per user.

```ts
dp.onNewMessage(
  filters.start,
  async (msg, state) => {
    // no more than 2 rps per user
    await state.throttle('start', 2, 1)

    await msg.replyText('Hi!')
  }
)
```

--------------------------------

### Install build tools for each OS

Source: https://mtcute.dev/guide/intro/faq

Install the required build tools (Python, Make, and GCC) on various operating systems. Each commented line targets a specific platform: Windows uses winget, macOS uses Homebrew, and Linux distributions use their native package managers.

```bash
# Windows
winget install Microsoft.VisualStudio.2022.BuildTools Python.Python.3.11
# macOS
xcode-select --install # install xcode command-line tools
brew install python make

# nix
nix-shell -p python3 gnumake gcc

# Ubuntu/Debian
sudo apt install python3 make gcc
# Arch Linux
sudo pacman -S python make gcc
# Fedora
sudo dnf install python3 make gcc
# CentOS/RHEL
sudo yum install python3 make gcc
# openSUSE
sudo zypper install python3 make gcc
# Alpine Linux
sudo apk add python3 make gcc
```

--------------------------------

### WizardScene registration example

Source: https://mtcute.dev/guide/dispatcher/scenes

A complete WizardScene example with three steps: asking for name, handling skip via callback, validating name, and collecting email. Uses WizardSceneAction to control flow and onCurrentStep filter for skip callback.

```typescript
interface RegForm {
  name?: string
}

const wizard = new WizardScene<RegForm>('REGISTRATION')

wizard.addStep(async (msg) => {
  await msg.answerText('What is your name?',  {
    replyMarkup: BotKeyboard.inline([[BotKeyboard.callback('Skip', 'SKIP')]]),
  })

  return WizardSceneAction.Next
})

wizard.onCallbackQuery(filters.and(wizard.onCurrentStep(), filters.equals('SKIP')), async (upd, state) => {
  await state.merge({ name: 'Anonymous' })
  await wizard.skip(state)

  await upd.client.sendText(upd.chatId, 'Alright, "Anonymous" then\n\nNow enter your email')
})

wizard.addStep(async (msg, state) => {
  // simple validation
  if (msg.text.length < 3) {
    await msg.replyText('Invalid name!')
    return WizardSceneAction.Stay
  }

  await state.set({ name: msg.text.trim() })
  await msg.answerText('Enter your email')

  return WizardSceneAction.Next
})

wizard.addStep(async (msg, state) => {
  const { name } = (await state.get())!

  console.log({ name, email: msg.text })

  await msg.answerText('Thanks!')
  return WizardSceneAction.Exit
})
```

--------------------------------

### Start updates loop after sign in

Source: https://mtcute.dev/guide/intro/sign-in

Manually starts the updates loop after signing in. The tg.start method does this automatically, but when using manual sign-in you must call startUpdatesLoop yourself.

```TypeScript
if (await checkSignedIn()) {
  tg.startUpdatesLoop()
} else {
  // some sign in logic

  tg.startUpdatesLoop()
}
```

```JavaScript
if (await checkSignedIn()) {
  tg.startUpdatesLoop()
} else {
  // some sign in logic

  tg.startUpdatesLoop()
}
```

--------------------------------

### start

Source: https://mtcute.dev/guide/topics/conversation

Starts the conversation. Must be paired with stop() to avoid memory leaks.

```APIDOC
## [METHOD] start

### Description
Starts the conversation. Must be paired with stop() to avoid memory leaks.

### Method
`start(): Promise<void>`

### Example
```ts
await conv.start()
```
```

--------------------------------

### Setup Context7 MCP for mtcute docs

Source: https://mtcute.dev/guide/intro/llm-assistance

Sets up the Context7 MCP server to provide complete mtcute documentation to your agent. Run this command in your terminal.

```bash
pnpx ctx7 setup
```

--------------------------------

### Store API credentials in .env

Source: https://mtcute.dev/guide/intro/sign-in

Example .env file containing API_ID and API_HASH environment variables. Use dotenv-cli to load them.

```bash
# .env
API_ID=123456
API_HASH=0123456789abcdef0123456789abcdef
```

--------------------------------

### with

Source: https://mtcute.dev/guide/topics/conversation

Starts the conversation, executes the provided callback, and stops the conversation in a finally block.

```APIDOC
## [METHOD] with

### Description
Starts the conversation, executes the provided callback, and stops the conversation in a finally block.

### Method
`with(callback: () => Promise<void>): Promise<void>`

### Parameters
- **callback** (function) - Required - Async function containing conversation logic.

### Example
```ts
await conv.with(async () => {
    await conv.sendText('Hello!')
    await conv.waitForResponse()
})
```
```

--------------------------------

### Install @mtcute/node with pnpm

Source: https://mtcute.dev/guide

Installs the @mtcute/node package for existing Node.js projects. Requires TypeScript 5.0 or newer.

```bash
pnpm add @mtcute/node
```

--------------------------------

### Sign in as a user with phone, code, and password

Source: https://mtcute.dev/guide/intro/sign-in

Creates a TelegramClient with your API credentials and starts the login flow, prompting for phone, code, and password via tg.input. Replace API_ID and API_HASH with your own values. Note that tg.input is a wrapper over node:readline and is not available in @mtcute/core.

```typescript
// Replace with your own values
const tg = new TelegramClient({
  apiId: API_ID,
  apiHash: 'API_HASH'
})

const self = await tg.start({
  phone: () => tg.input('Phone > '),
  code: () => tg.input('Code > '),
  password: () => tg.input('Password > ')
})
console.log(`Logged in as ${self.displayName}`)
```

--------------------------------

### Sign in as a bot with botToken

Source: https://mtcute.dev/guide/intro/sign-in

Creates a TelegramClient and starts the login flow using a bot token obtained from @BotFather. Replace API_ID and API_HASH with your own values, and replace the botToken string with your actual token.

```typescript
// Replace with your own values
const tg = new TelegramClient({
  apiId: API_ID,
  apiHash: 'API_HASH'
})

const self = await tg.start({
  botToken: '12345678:0123456789abcdef0123456789abcdef'
})
console.log(`Logged in as ${self.displayName}`)
```

--------------------------------

### QR code sign-in with TelegramClient

Source: https://mtcute.dev/guide/intro/sign-in

Shows how to start a TelegramClient with QR code sign-in. The qrCodeHandler receives a URL to display as a QR code, and a password prompt is still required if 2FA is enabled.

```typescript
import { encodeQR } from 'qr'

// Replace with your own values
const tg = new TelegramClient({
  apiId: API_ID,
  apiHash: 'API_HASH'
})

const self = await tg.start({
  qrCodeHandler: (url, expires) => {
    // display the `url` as the qr code to the user, for example print it to console:
    console.log(encodeQR(url, 'ascii'))
  },
  // logging in via qr still requires entering a 2fa password if you have one set up
  password: () => tg.input('Password > ')
})
console.log(`Logged in as ${self.displayName}`)
```

--------------------------------

### Create a client with @mtcute/web

Source: https://mtcute.dev/guide

Creates a TelegramClient for browsers using @mtcute/web. Uses IndexedDB-based storage. Calls the help.getConfig method as an example.

```ts
import { TelegramClient } from '@mtcute/web'

const tg = new TelegramClient({
  apiId: 123456,
  apiHash: '0123456789abcdef0123456789abcdef',
  storage: 'my-account' // will use IndexedDB-based storage
})

tg.call({ _: 'help.getConfig' }).then((res) => console.log(res))
```

--------------------------------

### Import session string

Source: https://mtcute.dev/guide/topics/storage

Import a session string using importSession or by passing it to start. You can import into any storage, including in-memory storage.

```typescript
const tg = new TelegramClient({...})

await tg.importSession(SESSION_STRING)
// or
await tg.start({ session: SESSION_STRING })
```

--------------------------------

### Use networkMiddlewares.onRpcError helper

Source: https://mtcute.dev/guide/advanced/net-middlewares

Creates a middleware that only handles RPC errors, using the onRpcError helper. The example logs when the error is PEER_ID_INVALID, and then includes the basic middlewares.

```typescript
const client = new TelegramClient({
    ...,
    network: {
        middlewares: [
            networkMiddlewares.onRpcError(async (ctx, error) => {
                if (error.errorMessage === 'PEER_ID_INVALID') {
                    logPeerIdInvalid(ctx.request)
                }
            }),
            ...networkMiddlewares.basic()
        ]
    }
})
```

--------------------------------

### Handle custom updates with onRawUpdate

Source: https://mtcute.dev/guide/advanced/custom-schema

Handle custom updates by passing `nextSchema.readerMap` to the client and listening to raw updates with `onRawUpdate`. This example checks for the custom `updateWoof` update and logs the peer.

```ts
const tg = new TelegramClient({
  ...,
  readerMap: nextSchema.readerMap
})

tg.onRawUpdate.add(({ update, peers }) => {
  if (update._ === 'updateWoof') {
    console.log('got woof from %o', peers.get(update.at))
  }
})
```

--------------------------------

### Scaffold a Node.js bot with pnpm create @mtcute/bot

Source: https://mtcute.dev/guide

Scaffolds a new mtcute bot project in Node.js. Follow the interactive instructions to get a working bot.

```bash
pnpm create @mtcute/bot my-awesome-bot
```

--------------------------------

### Callback data output for post:1:view

Source: https://mtcute.dev/guide/topics/keyboards

The callback data string produced by the PostButton.build call in the previous example. It shows the prefix 'post' followed by the field values '1' and 'view' separated by colons.

```text
post:1:view
```

--------------------------------

### Filter inline queries with filters.regex

Source: https://mtcute.dev/guide/dispatcher/inline-mode

Use filters.regex to filter inline queries based on the query text. The example matches queries starting with 'cats '.

```TypeScript
dp.onInlineQuery(
  filters.regex(/^cats /),
  async (query) => {
    // ...
  }
)
```

--------------------------------

### Filter chosen inline results with filters.regex

Source: https://mtcute.dev/guide/dispatcher/inline-mode

Filters chosen inline results by result ID using filters.regex. The example matches IDs starting with 'CATS_'.

```ts
dp.onChosenInlineResult(
  filters.regex(/^CATS_/),
  async (result) => {
    // ...
  }
)
```

```ts
dp.onChosenInlineResult(
  filters.regex(/^CATS_/),
  async (result) => {
    // ...
  }
)
```

--------------------------------

### Get remaining requests and reset time from state.throttle

Source: https://mtcute.dev/guide/dispatcher/rate-limit

`throttle` returns a tuple containing the number of requests left until the user hits the limit and the time when the limit will be reset. This example shows how to use those values to inform the user.

```ts
const [left, reset] = await state.throttle('some_expensive_command', 1, 15)
await msg.replyText(`${left} requests left. Reset at ${new Date(reset).toString()}`)
```

--------------------------------

### BotKeyboard.builder()

Source: https://mtcute.dev/guide/topics/keyboards

Creates a builder for inline keyboards.

```APIDOC
## BotKeyboard.builder()

### Description
Creates a builder for inline keyboards. Use `push` to add buttons and `asInline` to get the markup.

### Method
`BotKeyboard.builder()`

### Parameters
None.

### Returns
A keyboard builder instance for inline keyboards.
```

--------------------------------

### Allow better-sqlite3 postinstall in pnpm-workspace.yaml

Source: https://mtcute.dev/guide/intro/faq

Add this to pnpm-workspace.yaml to allow pnpm 10+ to run the postinstall script for better-sqlite3. Without it, pnpm blocks the script by default and the native bindings won't be built.

```yaml
onlyBuiltDependencies:
  - better-sqlite3
```

--------------------------------

### Get complete user with tg.getUsers

Source: https://mtcute.dev/guide/topics/peers

Use tg.getUsers to fetch a complete User object from an incomplete peer. The incomplete user object is passed directly to the method, which returns an array; destructure the first element to get the complete user.

```typescript
const user = ... // incomplete user from somewhere
const [completeUser] = await tg.getUsers(user)
```

--------------------------------

### Scaffold a Deno bot with npm:@mtcute/create-bot

Source: https://mtcute.dev/guide

Scaffolds a new bot with Deno using the npm version of @mtcute/create-bot.

```bash
deno run -A npm:@mtcute/create-bot my-awesome-bot
```

--------------------------------

### Set up a Dispatcher with Dispatcher.for

Source: https://mtcute.dev/guide/dispatcher/intro

Creates a bound dispatcher for a TelegramClient instance using the Dispatcher.for method. Requires the @mtcute/dispatcher package and an existing TelegramClient instance.

```ts
import { Dispatcher } from '@mtcute/dispatcher'

const tg = new TelegramClient({...})
const dp = Dispatcher.for(tg)
```

--------------------------------

### Use filters.stateEmpty

Source: https://mtcute.dev/guide/dispatcher/state

Use `filters.stateEmpty` to match when there is no stored state. The example is shown in both TypeScript and JavaScript.

```typescript
dp.onNewMessage(
  filters.stateEmpty,
  async (msg, state) => {
    // ...
  }
)
```

```javascript
dp.onNewMessage(
  filters.stateEmpty,
  async (msg, state) => {
    // ...
  }
)
```

--------------------------------

### Get current state with state.get()

Source: https://mtcute.dev/guide/dispatcher/state

Retrieves the current state using state.get(). Returns null if no state is stored.

```typescript
dp.onNewMessage(async (msg, state) => {
  const current = await state.get()
})
```

--------------------------------

### Export session string

Source: https://mtcute.dev/guide/topics/storage

Call exportSession after starting the client to generate a session string. The output is about 400 characters long.

```typescript
await tg.start()
console.log(await tg.exportSession())
```

--------------------------------

### BotKeyboard.url()

Source: https://mtcute.dev/guide/topics/keyboards

Creates an inline keyboard button that opens the given URL when clicked.

```APIDOC
## BotKeyboard.url(text, url)

### Description
Creates an inline keyboard button that opens the given URL when clicked.

### Method
`BotKeyboard.url(text, url)`

### Parameters
- **text** (string) - Required - The text to display on the button.
- **url** (string) - Required - The URL to open.

### Returns
An inline keyboard button object.
```

--------------------------------

### Getting state outside handlers with getState

Source: https://mtcute.dev/guide/dispatcher/state

Use dp.getState to retrieve state for a message reply or a User/Chat instance, then optionally delete it.

```TypeScript
const state = await dp.getState(await msg.getReply())
// you can also pass User/Chat instances:
const state = await dp.getState(msg.sender)
// and then, for example
await state.delete()
```

--------------------------------

### BotKeyboard.replyBuilder()

Source: https://mtcute.dev/guide/topics/keyboards

Creates a builder for reply keyboards.

```APIDOC
## BotKeyboard.replyBuilder()

### Description
Creates a builder for reply keyboards. Use `push` to add buttons and `asReply` to get the markup.

### Method
`BotKeyboard.replyBuilder()`

### Parameters
None.

### Returns
A keyboard builder instance for reply keyboards.
```

--------------------------------

### Manual start/stop with try/finally

Source: https://mtcute.dev/guide/topics/conversation

Shows the equivalent of .with() using manual .start() and .stop() calls. Calling .stop() is vital to avoid memory leaks.

```typescript
await conv.start()
try {
    // ... code ...
} finally {
    conv.stop()
}
```

--------------------------------

### Send media with InputMedia builders

Source: https://mtcute.dev/guide/topics/files

Shows how to send media using `sendMedia` with `InputMediaLike` builders: `InputMedia.photo` for a file path, `InputMedia.auto` for a File ID with a caption, and a plain string File ID when no additional parameters are needed.

```typescript
await tg.sendMedia('me', InputMedia.photo('file:assets/welcome.jpg'))

await tg.sendMedia('me', InputMedia.auto('BQACAgEAAx...Z2mGB8E', {
    caption: 'Backup of the project'
}))

// when using InputMedia.auto with file IDs and not using
// additonal parameters like `caption`, you can simply pass it as a string
await tg.sendMedia('me', 'CAADAgADLgZZCKNgg2JpAg')
```

--------------------------------

### Get state with default fallback

Source: https://mtcute.dev/guide/dispatcher/state

Provides a default fallback state when no state is stored. The fallback can be an object or a function returning the default state.

```typescript
dp.onNewMessage(async (msg, state) => {
  const current = await state.get({ ... })
  // or a function
  const current = await state.get(() => ({ ... }))
})
```

--------------------------------

### BotKeyboard.replyBuilder with push and asReply

Source: https://mtcute.dev/guide/topics/keyboards

Builds a reply keyboard with two text buttons using the builder. The asReply method returns the markup, and the result is a two-row keyboard with one button per row.

```TypeScript
const markup = BotKeyboard.replyBuilder()
    .push(BotKeyboard.text('Button 1'))
    .push(BotKeyboard.text('Button 2'))
    .asReply()

// Result:
// [ Button 1 ]
// [ Button 2 ]
```

--------------------------------

### Delete state with state.delete

Source: https://mtcute.dev/guide/dispatcher/state

Use `state.delete()` inside a message handler to remove the currently stored state. The example is shown in both TypeScript and JavaScript.

```typescript
dp.onNewMessage(async (msg, state) => {
  await state.delete()
})
```

```javascript
dp.onNewMessage(async (msg, state) => {
  await state.delete()
})
```

--------------------------------

### Async handler with error handling

Source: https://mtcute.dev/guide/intro/updates

Example of an async handler with error handling. Handlers should be synchronous, so wrap async operations in try/catch to handle errors.

```ts
tg.onNewMessage.add(async (msg) => {
  try {
    await msg.answerText('test')
  } catch (e) {
    console.error(e)
  }
})
```

```ts
tg.onNewMessage.add(async (msg) => {
  try {
    await msg.answerText('test')
  } catch (e) {
    console.error(e)
  }
})
```

--------------------------------

### BotKeyboard.webView

Source: https://mtcute.dev/guide/topics/keyboards

Creates a reply keyboard button that opens a WebView when clicked.

```APIDOC
## BotKeyboard.webView

### Description
Creates a reply keyboard button that opens a WebView when clicked.

### Method
`BotKeyboard.webView`

### Parameters
- **text** (string) - Required - The text to display on the button.
- **url** (string) - Required - The URL to open in the WebView.

### Request Example
```ts
BotKeyboard.webView('Open WebView', 'https://example.com')
```

### Response
Returns a reply button object.
```

--------------------------------

### Upload a theme with _normalizeInputFile

Source: https://mtcute.dev/guide/topics/raw-api

Converts an InputFileLike to an InputFile using _normalizeInputFile and uploads a theme via account.uploadTheme.

```typescript
const file = 'file:theme.txt'

const res = await tg.call({
    _: 'account.uploadTheme',
    file: await tg._normalizeInputFile(file),
    ...
})
```

--------------------------------

### Create a client with @mtcute/deno

Source: https://mtcute.dev/guide

Creates a TelegramClient for Deno using the jsr:@mtcute/deno package. Uses sqlite-based storage by default.

```ts
import { TelegramClient } from 'jsr:@mtcute/deno'

const tg = new TelegramClient({
  apiId: 123456,
  apiHash: '0123456789abcdef0123456789abcdef',
  storage: 'my-account' // will use sqlite-based storage
})

await tg.start()
```

--------------------------------

### Close a chat with closeChat

Source: https://mtcute.dev/guide/intro/updates

Closes a chat that was previously opened with openChat. The example shows the same call in both TypeScript and JavaScript (the second block is likely the JavaScript version).

```typescript
await tg.closeChat('durov')
```

```typescript
await tg.closeChat('durov')
```

--------------------------------

### Enter a scene with state.enter

Source: https://mtcute.dev/guide/dispatcher/scenes

Enters a scene using state.enter with the scene instance.

```typescript
dp.onNewMessage(async (msg, state) => {
  await state.enter(SomeScene)
})
```

--------------------------------

### Custom filter using state.get()

Source: https://mtcute.dev/guide/dispatcher/state

A custom filter that checks if the state's `action` equals `'ENTER_PASSWORD'` by calling `state.get()`. The example is shown in both TypeScript and JavaScript.

```typescript
dp.onNewMessage(
  (msg, state) => state.get().then((res) => res?.action === 'ENTER_PASSWORD'),
  async (msg, state) => {
    // ...
  }
)
```

```javascript
dp.onNewMessage(
  (msg, state) => state.get().then((res) => res?.action === 'ENTER_PASSWORD'),
  async (msg, state) => {
    // ...
  }
)
```

--------------------------------

### KeyboardBuilder.asReply()

Source: https://mtcute.dev/guide/topics/keyboards

Returns the built reply keyboard markup.

```APIDOC
## KeyboardBuilder.asReply()

### Description
Returns the built reply keyboard markup.

### Method
`asReply()`

### Parameters
None.

### Returns
The reply keyboard markup object.
```

--------------------------------

### BotKeyboard.callback

Source: https://mtcute.dev/guide/topics/keyboards

Creates an inline keyboard button that sends a callback query with the specified data when tapped.

```APIDOC
## BotKeyboard.callback

### Description
Creates an inline keyboard button that sends a callback query with the specified data when tapped.

### Method
`BotKeyboard.callback`

### Parameters
- **text** (string) - Required - The text to display on the button.
- **data** (string) - Required - The callback data to send when the button is tapped.

### Request Example
```ts
BotKeyboard.callback('First button', 'btn:1')
```

### Response
Returns an inline button object.
```

--------------------------------

### Send a GIF inline result with BotInline.gif

Source: https://mtcute.dev/guide/dispatcher/inline-mode

Create a GIF result using a direct URL to an MP4 or GIF. The example uses a Tenor video URL.

```TypeScript
dp.onInlineQuery(async (query) => {
  query.answer([
    BotInline.gif(
      'RESULT_ID',
      'https://media.tenor.com/videos/98bf1db10cb172aae086b09ae88ebf22/mp4'
    )
  ])
})
```

--------------------------------

### Scaffold or add @mtcute/bun with Bun

Source: https://mtcute.dev/guide

Scaffolds a new bot with Bun or adds @mtcute/bun to an existing project. Bun is supported in @mtcute/create-bot.

```bash
bun create @mtcute/bot my-awesome-bot
# or add to an existing project
bun add @mtcute/bun
```

--------------------------------

### Check for RPC errors with isTlRpcError

Source: https://mtcute.dev/guide/advanced/net-middlewares

Shows how to check if a call result is an RPC error using isTlRpcError and access the errorMessage. In this example, it logs when the error is PEER_ID_INVALID.

```typescript
const myMiddleware: RpcCallMiddleware = async (ctx, next) => {
    const res = await next(ctx)

    if (isTlRpcError(res) && res.errorMessage === 'PEER_ID_INVALID') {
        logPeerIdInvalid(ctx.request)
    }

    return res
}
```

--------------------------------

### Reusing existing SQLite storage for FSM

Source: https://mtcute.dev/guide/dispatcher/state

Import SqliteStorage and SqliteStateStorage, then create a TelegramClient with the storage and pass SqliteStateStorage.from(storage) to Dispatcher.for.

```TypeScript
import { SqliteStorage } from '@mtcute/node' // or '@mtcute/bun' / '@mtcute/deno'
import { SqliteStateStorage } from '@mtcute/dispatcher'

const storage = new SqliteStorage('my-account')
const tg = new TelegramClient({ ..., storage })

const dp = Dispatcher.for<BotState>(tg, {
  storage: SqliteStateStorage.from(storage)
})
```

--------------------------------

### Set state with TTL

Source: https://mtcute.dev/guide/dispatcher/state

Sets a TTL (in seconds) after which the newly set state is considered stale and removed. The example sets a TTL of 3600 seconds (1 hour).

```typescript
dp.onNewMessage(async (msg, state) => {
  // ttl = 1 hour
  await state.set({ ... }, 3600)
})
```

--------------------------------

### BotInline.video

Source: https://mtcute.dev/guide/dispatcher/inline-mode

Documentation for creating a video inline query result using BotInline.video.

```APIDOC
## BotInline.video

### Description
Creates a video inline query result. When sending by direct URL, there is a file size limit of 20 MB and a thumbnail is required. Alternatively, you can send a video by its URL (e.g. from YouTube) using `isEmbed: true`.

### Method
BotInline.video

### Parameters
- **resultId** (string) - Required - Unique identifier for this result.
- **url** (string) - Required - Direct URL to the video file or page.
- **options** (object) - Optional - Additional options:
  - **thumb** (string) - Required when sending by direct URL - URL of the thumbnail.
  - **title** (string) - Optional - Title of the result.
  - **description** (string) - Optional - Description of the result.
  - **isEmbed** (boolean) - Optional - Set to `true` to send a video by its URL (e.g. from YouTube).

### Request Example
```ts
dp.onInlineQuery(async (query) => {
  query.answer([
    BotInline.video(
      'RESULT_ID',
      'https://amvnews.ru/index.php?go=Files&file=down&id=1858&alt=4',
      {
        thumb:
          'https://amvnews.ru/images/news098/1257019986-Bad-Apple21_5.jpg',
        title: 'Video title',
        description: 'Video description',
      }
    )
  ])
})
```

### Response
No explicit response is documented. The result is used to answer the inline query.
```

--------------------------------

### Pre-update middleware with PropagationAction.Stop

Source: https://mtcute.dev/guide/dispatcher/middlewares

Registers a pre-update middleware that runs before an update is dispatched. Returning PropagationAction.Stop skips the update entirely. The example randomly skips 10% of updates.

```typescript
dp.onPreUpdate((upd) => {
  // randomly skip 10% of updates
  if (Math.random() < 0.1)
    return PropagationAction.Stop
})
```

--------------------------------

### BotKeyboard.text()

Source: https://mtcute.dev/guide/topics/keyboards

Creates a reply keyboard button with the given text.

```APIDOC
## BotKeyboard.text(text)

### Description
Creates a reply keyboard button with the given text.

### Method
`BotKeyboard.text(text)`

### Parameters
- **text** (string) - Required - The text to display on the button.

### Returns
A reply keyboard button object.
```

--------------------------------

### Get Unique File ID from message media

Source: https://mtcute.dev/guide/topics/files

Access the Unique File ID of a photo from a new message. The ID is stable across users and bots but cannot be used to download the file.

```typescript
tg.onNewMessage.add(async (msg) => {
    if (msg.media?.type === 'photo') {
        console.log(msg.media.uniqueFileId)
    }
})
```

--------------------------------

### BotKeyboard.copy()

Source: https://mtcute.dev/guide/topics/keyboards

Creates an inline keyboard button that copies the given text to the clipboard when clicked.

```APIDOC
## BotKeyboard.copy(options)

### Description
Creates an inline keyboard button that copies the given text to the clipboard when clicked.

### Method
`BotKeyboard.copy(options)`

### Parameters
- **options** (object) - Required - An object with the following properties:
  - **text** (string) - Required - The text to display on the button.
  - **copyText** (string) - Required - The text to copy to the clipboard.

### Returns
An inline keyboard button object.
```

--------------------------------

### BotInline.audio

Source: https://mtcute.dev/guide/dispatcher/inline-mode

Documentation for creating an audio inline query result using BotInline.audio.

```APIDOC
## BotInline.audio

### Description
Creates an audio inline query result. When sending by direct URL, there is a file size limit of 20 MB. Performer, title and other meta can't be changed once the file is cached by Telegram.

### Method
BotInline.audio

### Parameters
- **resultId** (string) - Required - Unique identifier for this result.
- **url** (string) - Required - Direct URL to the audio file.
- **options** (object) - Optional - Additional options:
  - **performer** (string) - Optional - Performer name.
  - **title** (string) - Optional - Title of the audio.

### Request Example
```ts
dp.onInlineQuery(async (query) => {
  query.answer([
    BotInline.audio(
      'RESULT_ID',
      'https://vk.com/mp3/cc_ice_melts.mp3',
      {
        performer: 'Griby',
        title: 'Tayet Lyod',
      }
    )
  ])
})
```

### Response
No explicit response is documented. The result is used to answer the inline query.
```

--------------------------------

### Create multiple TelegramWorkerPort instances for same worker

Source: https://mtcute.dev/guide/advanced/workers

Use this snippet to create multiple TelegramWorkerPort instances for the same underlying worker. Each port gets its own logical connection, with isolated requests, aborts, and keepalives.

```typescript
const worker = new Worker(
    new URL('./worker.js', import.meta.url),
)

const port1 = new TelegramWorkerPort({ worker })
const port2 = new TelegramWorkerPort({ worker })
```

--------------------------------

### KeyboardBuilder.asInline()

Source: https://mtcute.dev/guide/topics/keyboards

Returns the built inline keyboard markup.

```APIDOC
## KeyboardBuilder.asInline()

### Description
Returns the built inline keyboard markup.

### Method
`asInline()`

### Parameters
None.

### Returns
The inline keyboard markup object.
```

--------------------------------

### Stop propagation with PropagationAction.Stop

Source: https://mtcute.dev/guide/dispatcher/groups-propagation

Prevents the update from being handled by any other handlers within the same dispatcher. In the example, the second handler will not be executed even though it is in a separate group. Does not prevent handlers from child dispatchers.

```typescript
dp.onNewMessage(
  filters.or(filters.text, filters.sticker),
  async (msg) => {
    console.log('Text or sticker')

    return PropagationAction.Stop
  }
)

dp.onNewMessage(
  filters.text,
  async (msg) => {
    console.log('Text only')
  },
  1
)
```

--------------------------------

### Fetch DC options with help.getConfig

Source: https://mtcute.dev/guide/intro/faq

Fetches the list of Telegram data center options without requiring authorization. Useful for discovering DC IPs.

```typescript
tg.call({ _: 'help.getConfig' })
  .then((res) => console.log(res.dcOptions))
```

--------------------------------

### account.uploadTheme

Source: https://mtcute.dev/guide/topics/raw-api

Uploads a theme file. Requires normalizing the input file with _normalizeInputFile.

```APIDOC
## account.uploadTheme

### Description
Uploads a theme file. Requires normalizing the input file with _normalizeInputFile.

### Method
call

### Endpoint
account.uploadTheme

### Parameters
#### Request Body
- **file** (InputFile) - Required - The normalized input file.
- **...** - Other parameters as required by the API.

### Request Example
```ts
const file = 'file:theme.txt'

const res = await tg.call({
    _: 'account.uploadTheme',
    file: await tg._normalizeInputFile(file),
    ...
})
```
```

--------------------------------

### Get complete sender and chat in Dispatcher

Source: https://mtcute.dev/guide/topics/peers

In a Dispatcher message handler, use msg.getCompleteSender() and msg.getCompleteChat() to obtain complete sender and chat objects. These methods are available on the message object when using the Dispatcher.

```typescript
dp.onNewMessage(async (msg) => {
    const sender = await msg.getCompleteSender()
    const chat = await msg.getCompleteChat()
})
```

--------------------------------

### Serialize and deserialize custom TL objects

Source: https://mtcute.dev/guide/advanced/custom-schema

Use the generated `nextSchema` with `TlBinaryWriter` and `TlBinaryReader` to serialize and deserialize custom TL objects. This example calls the custom method `woof.bark` and reads the result.

```ts
import { TlBinaryReader, TlBinaryWriter } from '@mtcute/core/utils.js'

const r = await tg.call({
    _: 'mtcute.customMethod',
    bytes: TlBinaryWriter.serializeObject(nextSchema.writerMap, {
        _: 'woof.bark',
        at: await tg.resolvePeer('teidesu')
    } as any)
})

console.log(TlBinaryReader.deserializeObject(nextSchema.readerMap, r))
```

--------------------------------

### Handle updates with onNewMessage, onUpdate, onRawUpdate

Source: https://mtcute.dev/guide/intro/updates

Shows how to handle updates: onNewMessage for new messages, onUpdate for any supported update, and onRawUpdate for raw MTProto updates. Handlers should be synchronous.

```ts
tg.onNewMessage.add((msg) => {
  console.log(msg.text)
})

// You can also handle any supported update at once:
tg.onUpdate.add((upd) => {
  if (upd.name === 'new_message') {
    console.log(upd.data.text)
  }
})

// As well as raw MTProto updates:
tg.onRawUpdate.add(({ update, peers }) => {
  console.log(update._)
})
```

```ts
tg.onNewMessage.add((msg) => {
  console.log(msg.text)
})

// You can also handle any supported update at once:
tg.onUpdate.add((upd) => {
  if (upd.name === 'new_message') {
    console.log(upd.data.text)
  }
})

// As well as raw MTProto updates:
tg.onRawUpdate.add(({ update, peers }) => {
  console.log(update._)
})
```

--------------------------------

### Stop children propagation with PropagationAction.StopChildren

Source: https://mtcute.dev/guide/dispatcher/groups-propagation

Prevents handlers from child dispatchers from being executed, in addition to stopping propagation within the same dispatcher. In the example, the second executor will not be called even though it is in a child dispatcher.

```typescript
dp.onNewMessage(
  filters.or(filters.text, filters.sticker),
  async (msg) => {
    console.log('Text or sticker')

    return PropagationAction.StopChildren
  }
)

const dp1 = Dispatcher.child()
dp.addChild(dp1)

dp1.onNewMessage(
  filters.text,
  async (msg) => {
    console.log('Text only')
  }
)
```

--------------------------------

### Use BaseTelegramClient with sendText

Source: https://mtcute.dev/guide/advanced/treeshaking

Shows the tree-shakeable pattern: import BaseTelegramClient and import the needed method from '@mtcute/web/methods.js', then call the method with the client instance.

```ts
import { BaseTelegramClient } from '@mtcute/web'
import { sendText } from '@mtcute/web/methods.js'

const tg = new BaseTelegramClient({ ... })

await sendText(tg, ...)
```

--------------------------------

### Handle pre_checkout_query with dp.onPreCheckoutQuery

Source: https://mtcute.dev/guide/dispatcher/handlers

Handles pre_checkout_query updates when a user clicks the 'Pay' button. Approves the pre-checkout query.

```typescript
dp.onPreCheckoutQuery(async (upd) => {
  await upd.approve()
})
```

```javascript
dp.onPreCheckoutQuery(async (upd) => {
  await upd.approve()
})
```

--------------------------------

### BotKeyboard.requestPeer

Source: https://mtcute.dev/guide/topics/keyboards

Creates a reply keyboard button that, when clicked, asks the user to choose a peer and sends a message with `ActionPeerChosen`.

```APIDOC
## BotKeyboard.requestPeer

### Description
Creates a reply keyboard button that, when clicked, asks the user to choose a peer and sends a message with `ActionPeerChosen`.

### Method
`BotKeyboard.requestPeer`

### Parameters
- **text** (string) - Required - The text to display on the button.

### Request Example
```ts
BotKeyboard.requestPeer('Choose peer')
```

### Response
Returns a reply button object.
```

--------------------------------

### Unparse HTML message with html.unparse

Source: https://mtcute.dev/guide/topics/parse-modes

Shows how to use the `unparse` method to convert a message back to its original text with entities. The example uses the HTML parser and prints both the plain text and the unparsed HTML.

```ts
import { html } from '@mtcute/html-parser'

const msg = await tg.sendText('me', html`Hi, <b>User</b>!`)

console.log(msg.text)
// Hi, User!
console.log(html.unparse(msg))
// Hi, <b>User</b>!
```

```ts
import { html } from '@mtcute/html-parser'

const msg = await tg.sendText('me', html`Hi, <b>User</b>!`)

console.log(msg.text)
// Hi, User!
console.log(html.unparse(msg))
// Hi, <b>User</b>!
```

--------------------------------

### Upload files with setProfilePhoto using InputFileLike

Source: https://mtcute.dev/guide/topics/files

Shows the various `InputFileLike` types accepted by client methods like `setProfilePhoto`: Buffer, readable stream, fetch Response, UploadedFile, file path with `file:` prefix, and File ID. Note that URLs are not supported by `setProfilePhoto` and some other methods (TG limitation).

```typescript
await tg.setProfilePhoto('photo', Buffer.from(...))
await tg.setProfilePhoto('photo', fs.createReadableStream('assets/renge.jpg'))
await tg.setProfilePhoto('photo', await fetch('https://nyanpa.su/renge.jpg'))
await tg.setProfilePhoto('photo', await tg.uploadFile(...))
await tg.setProfilePhoto('photo', 'file:assets/renge.jpg')
await tg.setProfilePhoto('photo', 'BQACAgEAAx...Z2mGB8E')

// setProfilePhoto and some other methods don't support URLs (TG limitation)
// await tg.setProfilePhoto('photo', 'https://nyanpa.su/renge.jpg')
```
Tokens:
Raw