tele

a telegram desktop fork. it isn't a real fork of the code: this repo only holds a queue of patches that get applied on top of every stable tdesktop release and built here automatically.

grab the latest build from releases.

• windows x64: tele-<version>-win64.zip. unpack it anywhere and run tele.exe. it keeps its data next to the exe.

• linux x64: tele-<version>-linux64.zip. unpack it somewhere you can write to (like ~/.local/opt/tele) and run ./tele. it keeps its data in ~/.local/share/tele and adds itself to the app menu.

• macos (apple silicon and intel): tele-<version>-macos.dmg. open it, drag tele into applications, then run this once in the terminal, since the build isn't notarized by apple (the .zip next to it is what the self-updater downloads):

  xattr -dr com.apple.quarantine /Applications/tele.app
  

  it keeps its data in ~/Library/Application Support/tele.

none of them touch an installed telegram or its data.

tele updates itself: it checks these releases every 3 hours, downloads new builds in the background and asks you to restart. the update feed is signed, so a build that isn't from here won't be installed. you can turn it off in settings → tele → updates.

every zip and dmg has a build provenance attestation: github signs that the file was built by this repo's workflow from a given commit and hasn't changed since. check a download with the github cli:

gh attestation verify tele-<version>-win64.zip --repo nitreojs/tele

everything tele adds lives in settings → tele, right below the language row, grouped into pages: interface, chats, messages, sending, notifications, menus (beta), privacy, profiles and ids, bots and debug, with server, backup and updates on the page itself. the search at the top of the page, and the main settings search, find every tele setting. backup exports your tele settings to a file you can give to anyone, and imports one with a preview of what changes.

the default is TELE #{build}. empty hides the label.

• {build} (the build number, DEV for local builds), {version}
• {time}, {date}, {weekday}, {day}, {month}, or any qt format like {time:HH:mm:ss} and {date:dd MMM}
• {name}, {username}, {id}, {accounts}
• {unread}, {chat}, {chat_unread}, {status}

any variable takes modifiers after |, applied left to right: {weekday|short|lower} is sun, {date:dddd|upper} is SUNDAY.

• lower, upper: {weekday|lower} is sunday
• title capitalizes every word, cap only the first letter
• short is the compact form, wherever it sits in the chain: Sun and Sep for weekday and month, the first name for {name} and for people in {chat}, 7.2 for {version}, 1.2k for counters, … for {status}. other variables stay as they are
• first, last: the first or last word, {name|first}
• max:N cuts to N characters with …, {chat|max:20}
• pad:N pads to N characters, with zeros for numbers: {day|pad:2} is 07
• k shortens numbers: 1234 is 1.2k, 15000 is 15k, 2500000 is 2.5m
• default:text shows text when the value is empty or 0, {status|default:online}

[ … ] hides its part when a variable inside is empty or 0, so TELE #{build}[ · {unread} unread] doesn't show "· 0 unread". a default counts as filled. doubled brackets are literal. a | that isn't followed by modifiers stays part of a qt format, and '|' in quotes always does. a variable or modifier with a typo is shown as typed. account and activity variables stay empty while the app is locked with a passcode.

the editor highlights variables in the field and points out mistakes under the preview. below are all the variables as chips: click one to insert it, right-click for its other forms with their current values, hover to see the value now. presets has a few ready templates.

the window title (what the taskbar, alt+tab and the system window frame show) takes the same template, set next to the label. {label} puts the rendered label there, so {label} alone keeps both in sync. empty keeps telegram's own title, and a template that renders to nothing leaves the title blank.

on every site: utm*, mtm_*, pk_*, ga_*, _ga, _gl, gclid, gclsrc, gbraid, wbraid, dclid, gad_source, gad_campaignid, fbclid, fb_action_*, fb_source, fb_ref, action_*_map, msclkid, twclid, ttclid, li_fat_id, epik, yclid, ysclid, _openstat, mc_cid, mc_eid, mc_tc, ml_subscriber*, mkt_tok, igshid, igsh, _hsenc, _hsmi, __hsfp, __hssc, __hstc, hsctatracking, srsltid, s_kwcid, s_cid, oly_*_id, rb_clickid, vero_*, wickedid, _kx, wt_mc, wtrid, hmb_*, itm_*, otm_*, cmpid, os_ehash, __twitter_impression, tracking_source, echobox, spm, _branch_match_id, _branch_referrer, si. fragments like #utm_source=… go too.

per site, on top of that: youtube (feature, pp, kw), spotify (context, nd, dl_branch), twitter / x and fx/vx mirrors (s, t, src, ref_src, ref_url, cn), threads (xmt, slof), tiktok (_r, _t, is_from_webapp, sender_device, share_* and more), facebook (mibextid, __tn__, __cft__, ref*, notif_* and more), reddit (share_id, ref*, correlation_id, rdt), amazon (pd_rd_*, qid, ref_, tag, linkCode, /ref=… in the path and more), aliexpress (aff_*, algo_*, pvid, scm* and more), vk (from, ref, ref_domain), yandex (from, clid, redircnt), google search (ved, ei, sa, usg, oq, aqs, gs_* and more), google docs / drive (usp), linkedin (trk*, refId, lipi and more), ebay (_trk*, mk*, campid and more), medium (source), github (email_token, email_source), steam (snr), netflix (trackId, tctx), twitch (tt_medium, tt_content), imdb (ref_, pf_rd_*), bing, msn, apple (itsct, itscg), pinterest, hh.ru, ozon. t.me links are never touched.

start tele with any of these to keep it off the network on its own for that launch. telegram's own connection works as usual, and your settings stay as they are.

• -noteleserver: nothing goes to the tele server: no checkmark or other mark updates (the saved ones still show) and no crash reports.
• -noteleupdate: no update checks, no downloads, no what's new.
• -teleoffline: both of the above, and calcmula is off too.

the flags stay on when tele restarts itself, like after an update. on windows, add them to a shortcut after tele.exe; on linux, ./tele -teleoffline; on macos, open -a tele --args -teleoffline. a shortcut with -noteleserver keeps even the very first launch away from the tele server. to turn the server off for good, empty its field in settings.

tele can pull extra account data, like checkmarks, custom verification, scam / fake marks and support marks, from an optional server (settings → tele → server). it only ever downloads one public list and never tells the server which accounts you look at. the list is hashed, so it can't just be read off as a list of accounts. tele checks it every 10 minutes, and "refresh now" fetches it right away. leave the field empty to turn it off. "clear cached data" drops the list tele saved, so the marks disappear until the next fetch.

the same server takes crash reports. after a crash, tele offers to send the report: a short text with the version, platform and the crash reason, plus a minidump of the crashed process. you can look at it first and untick your username. with the server field empty, nothing is offered.

any server that serves the same format works: point settings → tele → server at it. the list never contains account ids, only keys that can't be turned back into ids without trying them one by one.

tele asks GET <server>/v1/badges and expects json like this:

{
  "salt": "AAECAwQFBgcICQoLDA0ODw==",
  "argon2": { "memory": 8192, "passes": 1, "lanes": 1 },
  "peers": {
    "iguxbtP_SnLvK69aBff2OQ": { "checkmark": true, "icon": "5368324170671202286", "description": "official" },
    "w5Zbi-HfwlqkJ6S4wjwqcw": { "scam": true }
  }
}

• salt is 8 to 64 random bytes in standard base64 with padding.
• argon2 are the argon2id costs: memory in KiB (1024 to 65536), passes (1 to 8), lanes (1 to 8), and memory × passes at most 65536. the official server uses 8192 / 1 / 1.
• each key in peers is base64url without padding of argon2id(password, salt) with those costs, a 16-byte output, version 0x13, no secret and no associated data.
• the password is the utf-8 string <scope>:<id>:
  • scope is prod, or test for accounts on telegram's test servers;
  • id is the bot api style id: users as is (777000), channels and supergroups as -100 followed by the channel id (-1001234567890). basic groups can't have entries.
• every field of an entry is optional: checkmark, scam, fake and support are booleans (false by default), icon is a custom emoji document id as a decimal string, description is plain text shown under the verification in the profile, and supportText (1 to 64 characters, users only) replaces the word "support" under the name of a support account. tele ignores fields it doesn't know, but rejects the whole list when a known field has the wrong type or length.

with the salt above, prod:777000 gives iguxbtP_SnLvK69aBff2OQ and prod:-1001234567890 gives w5Zbi-HfwlqkJ6S4wjwqcw. check your implementation against these two before anything else. in python:

from argon2.low_level import hash_secret_raw, Type
import base64

raw = hash_secret_raw(b"prod:777000", bytes(range(16)), time_cost=1, memory_cost=8192,
                      parallelism=1, hash_len=16, type=Type.ID, version=0x13)
print(base64.urlsafe_b64encode(raw).rstrip(b"=").decode())  # iguxbtP_SnLvK69aBff2OQ

the list can also give accounts extra usernames. they're public anyway, so they come as plain text, in an optional usernames object next to peers:

"usernames": {
  "tele": { "username": "teleAppUpdates", "position": 0 },
  "teleNews": { "username": "teleAppUpdates" }
}

• each key is the extra username, 2 to 32 latin letters, digits and underscores. username is the real public username of the account that gets it, 4 to 32 of them. both start with a letter and are compared ignoring case.
• position is optional: the place of the extra username among the account's usernames, counting from 0, so 0 makes it the main one in the profile. without it, the username goes after the real ones. a position past the end puts it last.
• tele skips a bad entry on its own and keeps the rest: a wrong name, an extra username equal to its account's username, the same key twice in different case, or a position that isn't a whole number from 0 to 1000. only the first 1000 good entries count. usernames never makes tele reject the list, and salt, argon2 and peers are still required (peers can be empty).
• they only apply to accounts on telegram's main servers, not the test ones.

with settings → tele → usernames from the server on (the default), the profile of @teleAppUpdates shows @tele, and @tele in messages, t.me/tele and tg://resolve?domain=tele open @teleAppUpdates, even when someone really owns @tele. the menu on such a link can still open the real one. your own aliases come first. @tele in a message you send becomes @teleAppUpdates, so other apps see the real username.

to keep it that way:

• serve the keys sorted, so their order says nothing about the accounts behind them.
• change the salt from time to time (the official server derives a new one every month), so lists from different times can't be compared key by key. every key has to be recomputed with the new salt.
• keep the costs within the limits above: tele computes one key for every account it shows, and rejects a list that asks for more.

tele also rejects a list over 4 MiB or with more than 100000 entries, and then keeps using the last good one. it sends If-None-Match with "<hex sha256 of the body it has>", so answering 304 when that matches the current body saves traffic, and a server can't tag clients with its own etags.

crash reports are optional. tele speaks the same protocol as telegram's own crash server, at <server>/v1/crash.php:

• GET ?act=query_report&apiid=…&version=…&dmp=0|1&platform=… answers Report as plain text when the server wants the report. anything else makes tele say thanks and send nothing.
• POST ?act=report is multipart/form-data with platform (like Windows64Bit, Linux, MacOS), version (like 7002009), report (the report text) and, when there is one, dump (a zip with one .dmp minidump, under 20 MiB). answer Done.
• answer 404 to both if you don't collect crashes.

bug fixes, conflict fixes and new features are welcome. for a feature, open an issue first. CONTRIBUTING.md walks through the whole cycle: getting the patched sources with tele.py, building, testing, exporting patches and opening a pull request.

• docs/architecture.md: the patch queue, tele.py, where the fork code lives and what ci does.
• docs/development.md: building, running a dev build safely and making a change.
• docs/conventions.md: code style, commits, patch hygiene and privacy rules.
• docs/releasing.md: how releases are built, signed and published.
• AGENTS.md: rules for ai coding agents.