// Use when updating TL schema layer in mtcute, fetching new Telegram API schemas, or when user asks to update the layer/schema
Use when working with mtcute, @mtcute/* packages, Telegram MTProto in TypeScript, TL types, Telegram API methods, or building Telegram bots/clients in TypeScript. Not for Bot API wrapper libraries (grammy, telegraf, node-telegram-bot-api).
Use when adding or modifying high-level client methods in packages/core/src/highlevel/methods/. Covers function signatures, codegen annotations, peer resolution, update handling, pagination, and all common patterns.
| name | update-layer |
| description | Use when updating TL schema layer in mtcute, fetching new Telegram API schemas, or when user asks to update the layer/schema |
| metadata | {"internal":true} |
Update the Telegram TL schema by fetching from multiple sources, resolving conflicts, and generating code.
Avoid wasting time and effort on reading the scripts to understand how they work, everything you need is listed below.
cd packages/core && pnpm tsx scripts/tl/fetch-api.ts --dry-run
Parse the output. It contains:
Build flags from the dry-run output:
pnpm tsx scripts/tl/fetch-api.ts \
--resolve entryName=N \ # 0=remove, 1+ = pick option from dry-run. repeat per conflict
--docs cached|fresh \ # use cached docs if available, or force re-fetch
You should pass --docs fresh when one of the Core/Corefork/Blogfork schemas was updated, but the cached docs are still on an older layer.
pnpm tsx scripts/tl/process-diff.ts
This prints a structured summary of changes: added/removed/modified classes and methods, and a list of long fields that may need int53 overrides.
Check if they represent user/channel/chat IDs or file sizes — those should be int53
If there are such long fields listed, present them to the user and run the scripts/tl/add-int53-overrides.ts script to add the override to the file like so:
# ! key is the entry name, array items are the fields that need to be overridden
echo '{"class":{"user":["bot_id"],"channel":["linked_id"]},"method":{"messages.getHistory":["offset_id"]}}' | pnpm tsx scripts/tl/add-int53-overrides.ts
Verify that there were no [warn] messages regarding the overrides you just added.
pnpm run gen-tl
If constructors changed ID or were removed, update packages/core/src/utils/binary/compat.ts:
case entries in mapCompatObject and type-specific mappers for old constructor names (e.g. user_layer225)Based on the diff, update these files for new/changed TL types:
New message actions: Add interfaces + switch cases in packages/core/src/highlevel/types/messages/message-action.ts (_messageActionFromTl). Also add new types to the MessageAction union.
New chat event actions: Add interfaces + switch cases in packages/core/src/highlevel/types/peers/chat-event/actions.ts (_actionFromTl). Also add new types to the ChatAction union.
New message fields: Update packages/core/src/highlevel/types/messages/message.ts (the Message class).
New user/chat fields: Update as needed:
packages/core/src/highlevel/types/peers/user.ts (User class, wraps user type)packages/core/src/highlevel/types/peers/full-user.ts (FullUser class, wraps userFull type)packages/core/src/highlevel/types/peers/chat.ts (Chat class, wraps chat, chatForbidden, channel, channelForbidden types)packages/core/src/highlevel/types/peers/full-chat.ts (FullChat class, wraps chatFull and channelFull types)Message-related updates: If Update-related types changed (including messageAction*, messageMedia*, messageReply*Header, messageForwardHeader, messageEntity*), update _fetchMissingPeers in the updates manager to handle new fields.
Peer-related updates: If user or channel changed, update service/peers.ts min-updating logic for new fields.
Note: all these tasks may take a long time, use timeout=5m for each to avoid issues
# typecheck and fix any type errors (note: workspace-wide `tsc` is broken, avoid using it, use `lint:tsc` script instead)
pnpm run -w lint:tsc
# run eslint, fix any remaining linting issues
pnpm run -w lint:ci --fix
# run tests
pnpm run -w test