Quick start

This is a quick guide on how to get mtcute up and running as fast as possible.

Node.js

For bots in Node.js, there's a special package that scaffolds a project for you:

bash

pnpm create @mtcute/bot my-awesome-bot

pnpm create @mtcute/bot my-awesome-bot

Just follow the instructions and you'll get a working bot in no time!

Manually

For existing projects, you'll probably want to add it manually, though.

Note: mtcute is currently targeting TypeScript 5.0. If you are using an older version of TypeScript, please consider upgrading.

Get your API ID and Hash at https://my.telegram.org/apps.
Install @mtcute/node package:

bash

pnpm add @mtcute/node

pnpm add @mtcute/node

Import the package and create a client:

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>!`)

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>!`)

That's literally it! Happy hacking 🚀

Native crypto addon

mtcute also provides @mtcute/crypto-node package, that implements a native Node.js addon for crypto functions used in MTProto.

Using this addon improves overall library performance (especially when uploading/downloading files), so it is advised that you install it as well:

bash

pnpm add @mtcute/crypto-node

pnpm add @mtcute/crypto-node

When using @mtcute/node, native addon is loaded automatically, no extra steps are required.

Bun

Experimental support for Bun is provided in @mtcute/bun package, and Bun is also supported in @mtcute/create-bot.

bash

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

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

Deno

Experimental support for Deno is provided in @mtcute/deno package, which is published to the jsr.io registry:

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()

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()

bash

deno run -A --unstable-ffi your-script.ts

deno run -A --unstable-ffi your-script.ts

Deno is also supported in @mtcute/create-bot, which is only available in npm:

bash

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

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

Browser

For browsers, it is recommended to use vite. Webpack is probably also fine, but you may need to do some extra configuration.

For usage in browsers, mtcute provides an @mtcute/web package:

bash

pnpm add @mtcute/web

pnpm add @mtcute/web

INFO

For vite, you'll need to deoptimize @mtcute/wasm (see vite#8427):

// in vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: ['@mtcute/wasm']
  }
})

// in vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: ['@mtcute/wasm']
  }
})

Then, you can use it as you wish:

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 { 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))

Other runtimes

mtcute strives to be as runtime-agnostic as possible, so it should work in any environment that supports some basic ES2020 features.

In case your runtime of choice is not listed above, you can try using @mtcute/core directly

You will need to provide your own implementations of storage, networking and crypto - feel free to take a look at web/node implementations for reference (or even extend them to better fit your needs, e.g. if some runtime only partially supports some Node.js APIs).

import { TelegramClient } from '@mtcute/core/client.js'
import { setPlatform } from '@mtcute/core/platform.js'

setPlatform(new MyPlatform())

const tg = new TelegramClient({
  ...,
  storage: new MyStorage(),
  crypto: new MyCrypto()
  transport: () => new MyTransport(),
})

import { TelegramClient } from '@mtcute/core/client.js'
import { setPlatform } from '@mtcute/core/platform.js'

setPlatform(new MyPlatform())

const tg = new TelegramClient({
  ...,
  storage: new MyStorage(),
  crypto: new MyCrypto()
  transport: () => new MyTransport(),
})

INFO

You only need to call setPlatform once, before creating any clients. Platform is set once globally and cannot be changed afterwards. It is safe to call setPlatform multiple times, as long as the constructor is the same - it will be ignored if the platform is already set.

A good starting point might be to use WebPlatform, since it implements everything in portable JavaScript.

Quick start ​

Node.js ​

Manually ​

Native crypto addon ​

Bun ​

Deno ​

Browser ​

Other runtimes ​

Quick start

Node.js

Manually

Native crypto addon

Bun

Deno

Browser

Other runtimes