DEV Community: Oleg Starnikov

Telethon is alive on Codeberg. Its GitHub repo has been archived since February

Oleg Starnikov — Sun, 20 Sep 2026 01:39:26 +0000

Here is how most of us decide whether a library is safe to depend on: open its GitHub page, look at the last commit, glance at open issues, check the stars. Thirty seconds, and you have an answer.

For the two most used Telegram libraries in Python, that answer is now wrong.

What the numbers say

Every figure below came from a public API on 16 September 2026 between 22:00 and 22:05 UTC, and every one of them was still standing when it was read again on 17 September.

Library	What GitHub shows	What is actually true
Telethon	`LonamiWebs/Telethon` archived, 12,057 stars, last push 21 Feb 2026, 1 open issue	`Lonami/Telethon` on Codeberg not archived, last commit 14 Sept 2026; PyPI serves 1.45.0, published 10 Sept 2026
Pyrogram	`pyrogram/pyrogram` archived, 4,616 stars, last push 23 Dec 2024	PyPI still serves 2.0.106 from 30 Apr 2023; the documentation site carries no notice
GramJS	repo archived	npm `telegram` 891,746 downloads between 13 Aug 2026 and 11 Sept 2026

Telethon did not die. It moved. The newest commit on Codeberg, dated 14 Sept 2026, is titled «Add missing parameters to friendly message methods», and the release before it bumped the version to 1.45. Meanwhile the GitHub page that every tutorial links to has one open issue, because an archived repo cannot receive new ones.

Pyrogram is the opposite case. The repo is archived, the last release on PyPI is from April 2023, and the documentation site still reads like the project is current. Nothing tells a newcomer that the last three years happened.

GramJS is the strangest of the three. Nearly nine hundred thousand downloads a month, against an archived repository. Nobody is watching that dependency, and almost everyone writing Telegram code in JavaScript is standing on it.

Why this matters more than it looks

Your bug report goes nowhere. An archived repo has issues disabled. If you hit a bug in Telethon today and file it where the stars are, you are filing it into a museum.

New developers pick the wrong signal. Someone starting a Telegram project this week searches, lands on the archived page, sees «archived» and concludes the whole ecosystem is dead. The opposite conclusion, «4,616 stars, must be fine», is equally wrong for Pyrogram.

Your assistant will be confidently wrong. Coding assistants lean on what GitHub says. Ask one whether Telethon is maintained and you will get an answer built on an archived page.

Tutorials keep pointing at the museum. Search results for Telegram scraping are dominated by proxy vendors publishing the same walkthrough. None of them updated the link.

How to actually check whether a library is alive

Four checks, none of which involve looking at stars.

Ask the package registry, not the repo. pypi.org/pypi//json gives you the upload time of the current version. For npm, api.npmjs.org/downloads/point/last-month/. A release from last week beats a repo badge from last year.
Find where the maintainer actually works. For Telethon that is Codeberg. The clue is usually in the README of the archived repo or in the maintainer's profile, and it is worth thirty seconds.
Read the download trend, not the total. A package with steady monthly downloads and no releases is a risk you are taking on purpose. A package with both is fine.
Check whether issues are even open. One open issue on a 12,000-star project usually means the tracker is closed, not that the bugs ran out.

The decision underneath all this

There is a question hiding behind «which library should I use», and it is worth asking out loud: do you need a Telegram session at all?

If you are building a bot that acts as itself, yes, and you should go with the library that is actually maintained, which today means Telethon from Codeberg, pinned to a version you tested.

If all you need is to read public channels, a session is a liability you took on by accident. It means a phone number, a session file that is worth stealing, FLOOD_WAIT timers you did not plan for, and an account that can be limited while you sleep. Plenty of projects carry that risk without ever needing the powers it buys them.

We built tgAtlas for the second case: public channels over HTTP, no phone number, no session file. It reads posts with view and forward counts, the discussion threads under them, and channel metadata. If you are in the first case, ignore us and go star the Codeberg mirror, codeberg.org/Lonami/Telethon. It had 132 stars on 17 September 2026, and it is the one doing the work.

The Telegram Bot API cannot read a channel your bot is not in

Oleg Starnikov — Tue, 15 Sep 2026 05:18:48 +0000

Your bot token is useless for this. That surprises people, and it surprised me.

A Telegram bot can read a channel only when it is a member of it, and adding a bot to a channel you do not own requires that channel's admin. So the usual plan (get a token from BotFather, call getUpdates, read a public channel) collapses at the first step. Public here means anyone can open the channel in the app. It does not mean the Bot API will hand it to you.

The route that does work is MTProto, the protocol the Telegram apps themselves speak. Telethon and TDLib both speak it well. The cost is the part nobody mentions in the tutorial: you authenticate as a user, with a phone number, you keep a session file that is a credential in its own right, and you keep a process alive, because MTProto is a persistent connection rather than a request and a response.

For a script that runs once an hour, that is a lot of moving parts to own.

One GET instead of a session

I work on an API that puts that MTProto layer behind plain HTTP, so a channel lookup is a request with a key on it. Here is the whole thing.

import os, requests

HOST = "telegram155.p.rapidapi.com"
H = {"x-rapidapi-key": os.environ["TELEGRAM_API_KEY"], "x-rapidapi-host": HOST}

r = requests.get(f"https://{HOST}/v1/usernames/durov", headers=H, timeout=30)
r.raise_for_status()
chat = r.json()["chats"][0]

print(chat["id"], chat["title"])

No phone number, no session file, nothing to keep running between calls.

The field that will bite you

Read the handle carefully. Telegram lets an account hold several usernames, and when it does, the flat username field comes back empty while the real handles sit in an array:

{
  "id": 1006503122,
  "title": "Pavel Durov",
  "username": "",
  "usernames": [
    { "username": "durov", "active": true, "editable": true },
    { "username": "rove",  "active": true, "editable": false }
  ]
}

A channel with a single handle fills username and leaves usernames empty, which is why this breaks in production rather than in your first test. @programmerjokes and @telegram both look ordinary; @durov does not. Read it like this:

def handle(chat):
    for u in chat.get("usernames") or []:
        if u.get("active") and u.get("editable"):
            return u["username"]
    return chat.get("username") or str(chat["id"])

The editable one is the primary handle, the others are aliases pointing at the same account.

Posting cadence, which is the number people actually want

Subscriber counts are easy to get and mostly vanity. What tells you whether a channel is alive is how often it posts and how its posts age. Both come out of one history call.

import datetime as dt

r = requests.get(f"https://{HOST}/v1/peers/1001142398/history",
                 headers=H, params={"limit": 5}, timeout=30)
msgs = r.json()["messages"]

for m in msgs:
    when = dt.datetime.fromtimestamp(m["date"], dt.UTC)
    print(m["id"], when.date().isoformat(), m.get("views"))

span = msgs[0]["date"] - msgs[-1]["date"]
print(f"{len(msgs) / (span / 86400):.2f} posts per day")

Real output for @programmerjokes, measured 2026-09-14 at 19:30 UTC:

3896 2026-09-14 4714
3895 2026-09-11 17410
3894 2026-09-09 23861
3893 2026-09-07 29896
3892 2026-09-04 38990
0.50 posts per day

Look at the view column rather than the top line. The post from that morning had 4 714 views; the one from ten days earlier had 38 990. A Telegram post keeps collecting views for days through forwards and search, so a fresh post is not a weak post, it is an unfinished one. If you are ranking channels by engagement and you divide views by subscribers on whatever the latest post happens to be, you are mostly measuring how many hours old that post is.

Take the median of posts older than a week instead, and the ranking stops jumping every time you run it.

Discovery without a crawler

The one that surprised me most: Telegram itself will tell you which channels are similar to a given one, and the API exposes it directly.

r = requests.get(f"https://{HOST}/v1/channels/recommendations",
                 headers=H, params={"peer_id": 1001142398}, timeout=30)
print(len(r.json()["chats"]), "similar channels")

That returned 10 channels in my run. Ten neighbours per seed, each of which has ten of its own, is a topical map you can walk instead of guessing search terms.

Retries, because quotas are real

Rate limits arrive as 429. Treat them as a signal to wait rather than an error to log and move past:

import time

def get(path, params=None, attempts=3):
    for i in range(attempts):
        r = requests.get(f"https://{HOST}{path}", headers=H, params=params, timeout=30)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        time.sleep(2 ** i)
    raise RuntimeError(f"still rate limited after {attempts} attempts")

Exponential backoff, three tries, and the body of a 429 tells you which quota you hit.

When to skip all of this

If you need to send messages, join chats, react, or read anything private, you need a real MTProto client with a real account, and none of the above replaces it. Telethon is excellent and the session file is the point, not the problem.

The HTTP route earns its place when you are reading public channels from something that is not a long-running process: a cron job, a Lambda, an agent tool call, a dashboard that refreshes on load.

That is the case I had, twice, before I stopped rewriting the same Telethon wrapper.

The API used here is Telegram Public Channels API on RapidAPI. There is a free plan: 2,500 calls a month, no card.

Written with an AI assistant; every number and code snippet was run against the live HiringIndex API by the team before publishing.

A key that isn't there: reading job postings without KeyError

Oleg Starnikov — Mon, 14 Sep 2026 09:51:38 +0000

Your loop works for nine hundred rows and then throws KeyError: 'city'.

Nothing broke. The row simply has no city, and the API left the key out instead of sending null. A posting that is remote only, or whose vendor never filled the field, arrives without it. Same for salary_text, for region, for remote_flag.

This is a small thing that costs an afternoon the first time, so here is the shape of it, with code you can run.

Read the optional fields with a fallback that means something

try/except around the whole loop hides which field was missing. .get() per field, with a fallback you choose deliberately, keeps the row usable:

import os, requests

HOST = "hiringindex.p.rapidapi.com"
H = {"x-rapidapi-key": os.environ["RAPIDAPI_KEY"], "x-rapidapi-host": HOST,
     "content-type": "application/json"}

# One page of postings. A key is left out of a row when that posting has no
# value for it, so every optional field is read with .get() and a fallback.
# row["city"] would raise KeyError on a remote-only posting.
r = requests.post(f"https://{HOST}/jobs/search", headers=H,
                  json={"keywords": ["python"], "limit": 20})
r.raise_for_status()

for row in r.json()["jobs"][:3]:
    where = row.get("city") or row.get("location_raw") or "location not given"
    print(f"{row['title'][:36]:<36} {where[:20]:<20} {row.get('salary_text', 'not stated')}")

Note the order in where: city first, then location_raw, which is the string the employer's board actually published, and only then a constant. Falling back to the raw location keeps rows that a naive city lookup would have dropped.

Output from that run:

Thermofluids Analysis Intern - Summe Los Angeles          $34 per hour
Robotics Engineer: Foundation Model  Redmond              not stated
GPU Kernel Engineer                  San Francisco        $190K – $250K • Offers Equity

When you want numbers, do not page for them

The second mistake is paging through rows to compute an average. The aggregates come from one call against the same filter, and they arrive already grouped by currency, city, platform and seniority.

One detail worth knowing before you write the retry: the endpoint answers 202 while the slice is still being computed, with a hint for how long to wait. Retry once after that delay rather than hammering it.

body = {"keywords": ["python"], "percentiles": True}
r = requests.post(f"https://{HOST}/jobs/insights", headers=H, json=body)
if r.status_code == 202:
    import time
    time.sleep(30)
    r = requests.post(f"https://{HOST}/jobs/insights", headers=H, json=body)

d = r.json()
head = d["headline"]
usd = next(s for s in d["salary"] if s["currency"] == "USD")
print(f"{head['row_count']} rows, {head['company_count']} employers, "
      f"{head['with_salary']} rows state a salary")
print(f"USD n={usd['count']}: lower band p50 {usd['min']['p50']}, "
      f"upper band p50 {usd['max']['p50']}")
print(f"median days a posting stays live: {d['freshness']['median_days_live']}")

Output, measured 2026-09-14 09:48 UTC on the keywords=python slice:

78115 rows, 7184 employers, 4667 rows state a salary
USD n=3248: lower band p50 168000, upper band p50 237550
median days a posting stays live: 47

Three numbers worth reading twice. The USD group holds 3 248 postings that state a band, and the median of their lower bounds is 168 000 while the median of their upper bounds is 237 550, so the middle posting advertises roughly 168k to 237k. And the median posting in that slice has been live for 47 days, which is a useful sanity check on anything you build on top: a "new this week" feature over a corpus with a 47 day median needs the posting date, not the fetch date.

What to take away

A missing key is not an error in the data. Read optional fields with .get() and pick a fallback per field, not one for the whole row.
Prefer the published raw value over a parsed one as your fallback. location_raw saved two of the three rows above.
Aggregates belong in the aggregate call. Paging to compute a median is slower and gives you a worse median.

The API used here is HiringIndex, which reads postings from thirteen applicant tracking systems and keeps the employer's own apply link on every row. I work on it. The free plan is 200 postings plus 5 insights calls a month, no card: rapidapi.com/starnikovoleg/api/hiringindex

Written with AI assistance (Claude). Every number above, and both output blocks, come from the live calls shown in the code.

Written with an AI assistant; every number and code snippet was run against the live HiringIndex API by the team before publishing.

A Telegram job alert bot in 60 lines of Python, on live ATS data

Oleg Starnikov — Sun, 13 Sep 2026 04:53:03 +0000

Job boards go stale fast. By the time a weekly digest reaches you, the interesting roles have been open
for a month. So let's build the smallest thing that fixes that: a Telegram bot that wakes up, asks one
API for everything posted in the last seven days, and sends you the new ones.

Sixty lines, no framework, no database.

The data

We'll read HiringIndex — job postings taken from
the catalogue APIs that applicant tracking systems publish, so every row carries the employer's own
apply link rather than an aggregator's redirect.

One call tells you what a slice looks like before you write any code. Two slices, both measured live at
2026-09-13 04:47–04:50 UTC:

	All remote, last 7 days	Python roles, remote, last 7 days
Postings	10,860	9
Companies	2,227	8
Median days open	4	—
Posted in the last 7 days	100%	100%

The second column is the filter the bot below actually uses, and it is deliberately narrow — nine
postings is a morning's worth of reading, not a firehose. Widen it by dropping job_titles and you
are back to the first column.

Salaries do not come from search at all: they come from /jobs/insights, per currency, and each
percentile says how many disclosures it rests on — for the wide slice, 744 USD postings give p25
115,000–150,000, p50 155,650–200,000, p75 199,000–260,000. Percentiles appear only where at least
30 salaries are disclosed, so a number you get is computed from real bands. (insights computes a
slice in the background the first time it is asked — see the snippet at the end for the two-line
202 handling.)

The bot

import os
import time

import requests

API = "https://hiringindex.p.rapidapi.com/jobs/search"
HEADERS = {
    "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
    "X-RapidAPI-Host": "hiringindex.p.rapidapi.com",
    "Content-Type": "application/json",
}
TELEGRAM = f"https://api.telegram.org/bot{os.environ['TG_BOT_TOKEN']}/sendMessage"
CHAT_ID = os.environ["TG_CHAT_ID"]

FILTER = {
    "job_titles": ["Python Developer"],
    "remote_flag": ["true"],
    "days_ago": 7,
    "limit": 20,
}


def fetch(page=1):
    r = requests.post(API, headers=HEADERS, json=FILTER | {"page": page}, timeout=60)
    if r.status_code == 503:                     # capacity, not an error on your side
        time.sleep(float(r.headers.get("Retry-After", 5)))
        return fetch(page)
    r.raise_for_status()
    return r.json()


def line(job):
    bits = [job.get("country_code"), job.get("employment_type"), job.get("seniority")]
    tail = " · ".join(b for b in bits if b)
    return (f"<b>{job['title']}</b>\n{job.get('company_name') or job.get('handle')}"
            f"{' · ' + tail if tail else ''}\nposted {job.get('posted_at')}\n"
            f"{job.get('apply_url') or job.get('posting_url')}")


def send(text):
    requests.post(TELEGRAM, json={"chat_id": CHAT_ID, "text": text,
                                  "parse_mode": "HTML", "disable_web_page_preview": True}, timeout=30)


def main():
    seen = set(open("seen.txt").read().split()) if os.path.exists("seen.txt") else set()
    data = fetch()
    fresh = [j for j in data["jobs"] if j["_id"] not in seen]
    for job in fresh:
        send(line(job))
        seen.add(job["_id"])
    with open("seen.txt", "w") as f:
        f.write("\n".join(seen))
    print(f"{len(fresh)} new of {data['total_count']} matching")


if __name__ == "__main__":
    main()

Run it from cron every morning. seen.txt is the whole state: a posting is sent once and never again.

Three things worth knowing before you build on it

days_ago filters by the employer's publication date, not by when the index saw the row. That is
why the median above is four days and not four hours — the filter is about the job, not about our
crawler.

Rows are not postings. A role advertised in three cities is three rows in search, one posting in
the aggregate. If you count anything, count with /jobs/insights, which deduplicates; total_count
on search is rows.

Errors arrive as one envelope. Branch on error, never on the message text:

{"error": "invalid_request", "message": "days_ago: expected an integer", "meta": {"request_id": "..."}}

An unknown filter key is rejected with 422 and the message names the valid keys, so a typo never
returns a silently wrong slice. An empty jobs array with total_count: 0 is a normal 200 — no
matches is not an error.

Making it yours

Swap the filter and the bot changes job:

{"keywords": ["kubernetes"], "days_ago": 3} — a stack watch
{"handles": ["walmart:wd504:WalmartExternal"]} — one employer's careers page, by ATS board handle
{"cities": ["Berlin"], "seniority": ["senior"], "salary": {"min": 80000}} — a narrow local search

Send the same filter to /jobs/insights instead of /jobs/search and you get the market around your
search: how many companies are hiring for it, where they are, and what they pay.

One thing to handle there, because aggregates are computed over the whole matching set rather than the
page you asked for: a filter nobody has requested yet comes back as 202 with Retry-After: 30
while the numbers are computed in the background. Ask again after the pause and you get 200 with a
meta.computed_at stamp. Measured 2026-09-13: a fresh filter answered 202 in 495 ms, and the same
filter returned 200 about a minute later.

INSIGHTS = "https://hiringindex.p.rapidapi.com/jobs/insights"   # same headers as above


def insights(body, attempts=4):
    for _ in range(attempts):
        r = requests.post(INSIGHTS, headers=HEADERS, json=body, timeout=60)
        # 202: the slice is being computed, not an error. A wide slice can answer 202 more than once,
        # so loop rather than retry exactly once. 429 is the plan limit, 503 is capacity.
        if r.status_code in (202, 429, 503):
            time.sleep(float(r.headers.get("Retry-After", 30)))
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError("insights did not return data in time")


market = insights(FILTER)                      # same filter, no limit and no page
head, fresh = market["headline"], market.get("freshness") or {}
print(head["job_count"], "postings,", head["company_count"], "employers")
print("median days open:", fresh.get("median_days_live", "—"))   # empty slice: counts are 0, median None

The free plan is 200 postings and 5 insights calls a month, no card:
get a key.

Written with an AI assistant; every number and code snippet was run against the live HiringIndex API by the team before publishing.

What a job-postings API can tell you about a skill: one call, real numbers

Oleg Starnikov — Tue, 08 Sep 2026 18:32:21 +0000

If you want to know how much demand there is for a skill — how many companies are hiring for it,
what they pay, where the roles are — the usual answer is to page through a jobs API and reduce the
list yourself. For a slice of 14,000 postings that is 140 paged calls plus your own statistics code.

We built the reduction as an endpoint. Same filter object as search, one call, computed server-side.

A slice nobody has asked for yet is computed in the background: the first call answers 202 with a
Retry-After, and the numbers arrive on the next one. Measured 2026-09-13: 202 in 495 ms, then 200
about a minute later. The snippet below handles it in two lines — worth keeping, because aggregates run
over the whole matching set rather than over the page you requested.
Everything below is a live response from Hiring Index,
captured on 2026-09-08. No rounded marketing numbers: the exact values the API returned.

The data

The index is read directly from the catalogue APIs of ten applicant tracking systems — Workday,
SmartRecruiters, Greenhouse, Workable, Lever, Ashby, Recruitee, Teamtailor, Breezy, Personio.
No job boards, no aggregators, no scraping of LinkedIn or Indeed. 1,597,584 postings today,
17,334 employers, re-read once a day.

That choice has a cost and we publish it rather than hide it: not every ATS publishes every field.
A salary is disclosed on a small minority of rows, and the coverage table per source is in the
listing docs. Where a field is missing it is null, never a guess.

One call, the whole slice

import time

import requests

H = {"X-RapidAPI-Key": "YOUR_KEY", "X-RapidAPI-Host": "hiringindex.p.rapidapi.com"}
BASE = "https://hiringindex.p.rapidapi.com"


def insights(body, attempts=4):
    for _ in range(attempts):
        r = requests.post(f"{BASE}/jobs/insights", headers=H, json=body, timeout=60)
        # 202 means the slice is being computed, not that it will be ready in 30 seconds: a wide
        # slice can answer 202 again. 429 is the plan limit, 503 is capacity. Loop, don't retry once.
        if r.status_code in (202, 429, 503):
            time.sleep(float(r.headers.get("Retry-After", 30)))
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError("insights did not return data in time")


d = insights({"keywords": ["Terraform"]})

h = d["headline"]
print(h["row_count"], "postings from", h["company_count"], "employers")
print(h["new_this_week"], "new in the last seven days")

14173 postings from 2071 employers
773 new in the last seven days

The same object carries the pay distribution, grouped by currency and pay period rather than
averaged into one meaningless number:

usd = max((g for g in d["salary"] if g["currency"] == "USD"), key=lambda g: g["count"])
print(usd["count"], "postings disclose a range")
print("p25", usd["min"]["p25"], "median", usd["min"]["p50"], "p75", usd["min"]["p75"])

688 postings disclose a range
p25 145000 median 170000 p75 200000

Those percentiles are computed on the lower bound of the advertised range, over the rows that
actually publish one — 688 of 14,173. The count travels with the number, so you can always tell how
much evidence is behind it.

Where the roles are, from the same response:

San Francisco 342 · London 242 · Bengaluru 106 · Singapore 105 · New York 101

And how long they have been open: median 62 days live, 51.4 % of them older than 60 days. For a
skill in demand that is a useful sanity check — a listing sitting open for months is a weaker signal
than a fresh one.

Title search and description search are different questions

The filter vocabulary has two text fields and the difference matters more than it looks:

Filter	Question it answers	`Kubernetes`
`job_titles`	is this the role?	314 postings
`keywords`	is it mentioned in the posting?	25,196 postings

Eighty times the volume, and both numbers are correct — they answer different questions. Titles
find the roles named after the technology; keywords find every posting that asks for it, which is
what you want when you are measuring demand for a skill.

Very common words are refused rather than served slowly:

{"error": "keyword_too_common",
 "message": "'excel' appears in about 38% of postings (~606,767 matches); keyword aggregates are computed for terms under 130,000 matches.",
 "meta": {"term": "excel", "estimated_matches": 606767, "limit": 130000}}

A fast, explicit refusal beats a request that ties up the database and times out. Narrowing by city
or country does not help, because the term scan comes first — the message says so instead of making
you discover it.

Values come as the employer wrote them

One deliberate choice worth flagging, because it is the opposite of what most APIs do. Vendor fields
are returned raw. The remote flag on the Terraform slice looks like this:

false 2519 · true 2042 · hybrid 139 · Hybrid 138 · remote 90 · onsite 71 · Partially Remote 51 · Flex 38

Fifteen distinct spellings, because fifteen spellings is what employers publish. We could fold them
into three tidy values, and every fold would be a small guess baked into your data. Instead the
split is returned as it is and the folding — if you want it — happens in your code, where you can
see it. Same for seniority: Mid-Senior level and Mid-Senior Level arrive as two rows.

One employer, precisely

Company names are ambiguous — contractors put a big name in their own job titles. Filtering by the
ATS board handle is exact:

requests.post(f"{BASE}/jobs/search", headers=H,
              json={"handles": ["walmart:wd504:WalmartExternal"], "limit": 1}).json()["total_count"]
# 22010  — Walmart's own Workday board
# company_name "Walmart" matches 396, mostly other companies naming it

Try it

Free tier, no card: rapidapi.com/starnikovoleg/api/hiringindex.
The same index with browsable market pages is at hiringindex.org — 4,350
pages of roles, cities and technologies, each one generated from the calls shown above.

If a field looks wrong, the error envelope carries meta.request_id; quote it and we can find the
exact call.

Written with an AI assistant; every number and code snippet was run against the live HiringIndex API by the team before publishing.

How to Give Your AI Agent Access to Telegram Data (MCP + REST API)

Oleg Starnikov — Mon, 08 Jun 2026 11:23:24 +0000

So I needed my AI agent to pull messages from Telegram channels. Sounds simple. Turns out it's kind of a pain.

The Bot API won't let you read channels unless your bot is added as a member. Telethon and Pyrogram work, but you have to self-host them, deal with phone number auth, and babysit session management yourself. I didn't want any of that. I just wanted a REST endpoint I could hit.

I ended up using this Telegram API on RapidAPI. It sits on top of MTProto (Telegram's native protocol), exposes 19 endpoints as both REST and MCP tools, and has a free tier with 2,500 requests/month. I'm still on that free plan and haven't needed more. No bot tokens, no phone numbers, no infra to maintain.

Here's how I set it up.

What you get

Once connected, your agent can:

Read messages from any public Telegram channel
Search across all public channels by keyword
Get channel details: member count, description, linked group
Look up user profiles (bio, premium status, etc.)

12 tools total, all available through one MCP endpoint.

The architecture

Nothing fancy:

Your AI Agent  ──MCP──▶  TG Gateway API  ──MTProto──▶  Telegram
                         (12 tools)                     (public data)

The API handles MTProto sessions, account rotation, and rate limiting under the hood. You just make HTTP calls.

Step 1: Grab an API key

Head to the API page on RapidAPI, hit "Subscribe to Test", pick the Basic plan. It's $0, no credit card. You get 2,500 req/month, which has been plenty for me.

Copy your X-RapidAPI-Key from the dashboard. That's your only credential.

Step 2: Connect via MCP

If you're using Claude, LangChain, CrewAI, or n8n, you can connect through MCP directly. The endpoint uses Streamable HTTP (protocol 2025-06-18):

POST https://telegram-public-api.p.rapidapi.com/v1/mcp

Initialize a session first:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    }
  }'

Grab the Mcp-Session-Id from the response headers. You'll pass it in every follow-up call.

Then list the tools:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'

You'll get back these 12:

Tool	Does what
`tg_resolve_username`	@username → peer ID
`tg_search_contacts`	Find channels and users
`tg_search_global`	Search messages across all public channels
`tg_get_full_user`	User profile: bio, premium, birthday
`tg_get_full_channel`	Channel info: description, member count
`tg_get_history`	Message history, paginated
`tg_get_channel_messages`	Specific messages by ID
`tg_get_replies`	Comments on a channel post
`tg_get_discussion_message`	Jump to discussion thread
`tg_get_channel_participants`	Channel members list
`tg_get_channel_recommendations`	Similar channels
`tg_check_chat_invite`	Preview invite link without joining

And call one:

curl -X POST "https://telegram-public-api.p.rapidapi.com/v1/mcp" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "tg_resolve_username",
      "arguments": { "username": "telegram" }
    }
  }'

That's it. Your agent now has Telegram access.

Step 3: Or just use Python

If MCP is overkill for your case, there's a Python client:

pip install rapidapi-telegram

from rapidapi_telegram import TelegramClient

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

# Resolve a username to a peer ID
resolved = client.resolve_username("telegram")
print(resolved)
# → {"Peer": {"UserID": 1005640892}, "Users": [...]}

# Get channel info in one call
channel = client.get_channel_by_username("telegram")
print(f"Members: {channel['FullChat']['ParticipantsCount']}")

# Last 10 messages
history = client.get_history_by_username("telegram", limit=10)
for msg in history["messages"]:
    print(f"  {msg['message'][:80]}...")

# Global search. This one's my favorite.
results = client.search_messages("bitcoin", limit=5)
for msg in results["messages"]:
    print(f"  [{msg['views']} views] {msg['message'][:60]}...")

The get_*_by_username helpers are nice. They resolve the username and fetch data in one call, so you don't have to chain requests manually.

Two things I actually built with this

Channel monitor

Dead simple. Polls a channel every minute, prints anything new:

from rapidapi_telegram import TelegramClient
import time

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

channel = "telegram"  # swap for whatever channel you want
last_id = 0

print(f"Monitoring @{channel}...")

while True:
    history = client.get_history_by_username(channel, limit=5, min_id=last_id)
    messages = history.get("messages", [])

    for msg in reversed(messages):
        text = msg.get("message", "")
        if text:
            views = msg.get("views", 0)
            print(f"[{views:,} views] {text[:120]}")
        last_id = max(last_id, msg.get("id", 0))

    time.sleep(60)

At one poll per minute, this burns ~1,440 requests/day. On the free tier I can run it for about 40 hours straight before hitting the cap. Enough for when I need to keep an eye on something.

Keyword alert across all channels

This is where the global search really shines:

from rapidapi_telegram import TelegramClient

client = TelegramClient(api_key="YOUR_RAPIDAPI_KEY")

results = client.search_messages("breaking OR launch", limit=20)

for msg in results.get("messages", []):
    text = msg.get("message", "")
    channel_id = msg.get("peer_id", {}).get("channel_id")
    views = msg.get("views", 0)
    print(f"Channel {channel_id} [{views:,} views]: {text[:100]}...")

You can search across all public Telegram channels at once. Try doing that with the Bot API (spoiler: you can't).

Bot API vs. this: quick comparison

I keep getting asked this, so here's the short version:

	Bot API	MTProto API
Read any public channel	Nope, bot has to be added	Yep, any public channel
Global message search	Not a thing	Works great
Channel members	Bot needs admin	Public channels, no problem
User profiles	Very limited	Full: bio, birthday, premium
Setup	Create bot, manage token, add to channels	One API key
MCP	No	Yes, native

If you just need to send messages from a bot, the Bot API is fine. But if you need to read public data (channels, messages, profiles), MTProto is the way.

On cost

Everything above runs on the free tier. I haven't paid anything. There are paid plans if you need high volume, but honestly, for personal projects and prototyping, the free 2,500/month is solid.

Links

If you end up building something with this, drop a comment. I'm curious what people use it for.