mtcute/docs/guide/index.md

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:

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

If you are using an older version of TypeScript, please consider upgrading.

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

pnpm add @mtcute/node

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

4. 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:

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.

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

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

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

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:

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']
  }
})

:::

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

See also: Tree-shaking

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

::: 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. :::