using-mtcute

Build Telegram bots and MTProto clients in TypeScript using mtcute packages.

553|61|Updated Apr 8, 2021
One-click install
npx skills add https://github.com/mtcute/mtcute --skill using-mtcute
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: using-mtcute
Source: https://github.com/mtcute/mtcute/tree/main/.claude/_skills/using-mtcute
Command: npx skills add https://github.com/mtcute/mtcute --skill using-mtcute

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires fastest-levenshtein, @mtcute/tl-utils.

What problem does it solve?

Working with Telegram's MTProto protocol in TypeScript requires navigating hundreds of TL schema types, raw API methods, and platform-specific setup. This Skill provides the operational knowledge and lookup tools to write correct mtcute code without guessing type names, method signatures, or package structure.

Core Features & Use Cases

  • TL Schema Lookup: Resolve raw TL constructors, unions, and method definitions (e.g., user, messages.sendMessage) into TypeScript types via the bundled get-constructor tool.
  • Client Method Discovery: Find signatures, parameters, and JSDoc for 300+ high-level TelegramClient methods like sendText, sendMedia, and getHistory with fuzzy matching.
  • High-Level Type Inspection: Inspect wrapper classes such as Message, Chat, User, and CallbackQuery with full member definitions.
  • Use Case: You are building a Telegram userbot that replies to private messages and downloads media. Use this Skill to scaffold the client with @mtcute/node, wire up the Dispatcher with filters, and look up the exact InputMedia types for file uploads.

Quick Start

Ask the assistant to write an mtcute bot that logs in with a bot token and replies to new private messages, and it will use the bundled lookup tools to verify every method and type.

Frequently Asked Questions about using-mtcute

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I send a message with mtcute in TypeScript?

Create a TelegramClient from a platform package like @mtcute/node, call start() with a bot token or phone login, then use tg.sendText(chatId, 'text'). Chats can be referenced by numeric ID, username string, or 'me'.

What is the difference between mtcute and grammy or telegraf?

mtcute speaks Telegram's native MTProto binary protocol directly, giving access to the full Telegram API including user accounts. grammy, telegraf, and node-telegram-bot-api are Bot API wrappers limited to the bot subset.

Which mtcute package should I install for Node.js?

Install @mtcute/node for Node.js server-side apps. It pre-configures crypto, transport, and SQLite storage. Use @mtcute/web for browsers, @mtcute/bun for Bun, and @mtcute/deno for Deno; avoid importing @mtcute/core directly.

How do I look up TL types like RawUser or messages.sendMessage?

Run the bundled get-constructor tool with the TL name or TypeScript type name, for example node tools/get-constructor.js RawUser. It prints the TL definition, generated TypeScript type, union membership, and optionally all referenced types.

Does mtcute support proxies and custom transports?

Yes, the Node.js package exports SocksProxyTcpTransport, HttpProxyTcpTransport, and MtProxyTcpTransport. You can also pass a proxy URL string to proxyTransportFromUrl, supporting socks4, socks5, http, https, and mtproto schemes.

How do I handle FLOOD_WAIT errors in mtcute?

Catch errors from API calls and check them with tl.RpcError.is(e, 'FLOOD_WAIT_%d'). The error object exposes the wait duration, such as e.seconds, so you can delay and retry the request.