subscribe_telegram - new posts from Telegram channels and groups, live
Name the Telegram channels and groups you want to follow and you get each new post from them as a telegram event, seconds after it's posted, with the token addresses in it already picked out. It comes with Professional. You connect straight to one of our stream servers, the same ones as the X stream: one socket can follow both. Add and remove chats on the open socket whenever you like; telegram_chat tells you when a chat you added is live (or can't be followed).
| Channel | Socket.IO, on a stream server's own address (on your dashboard) |
| Auth | your Professional plan's key (the key) |
| Emits | telegram, telegram_chat |
| Limit | 25 chats and 5 sockets per key on each server (the sockets are shared with the X stream) |
| Plan | Professional |
Servers
There are stream servers in the US, Europe and Asia. Their addresses are on your dashboard once your plan is Professional, with whether each is up. Connect to the one closest to you: every one serves every chat. A chat's posts come in on the server nearest to it on Telegram's side and reach the others a moment later; that server is the chat's server (below). For the shortest delay on a chat, connect to its server too and keep whichever copy of a post comes first (by chatId and id).
Your key, follows and limits on one server don't affect another.
Example
- JavaScript
- Python
import { io } from "socket.io-client";
// YOUR_STREAM_SERVER: a server's address from your dashboard
const socket = io("https://YOUR_STREAM_SERVER", { auth: { api_key: "YOUR_KEY" } });
socket.on("telegram", (p) => {
const delay = ((p.receivedAt - p.postedAt) / 1000).toFixed(1);
console.log(`${p.title} (+${delay}s): ${p.text.slice(0, 100)}\n ${p.url ?? ""}`);
for (const mint of p.addresses.solana) console.log(" CA", mint);
});
socket.on("telegram_chat", (c) => console.log(`${c.chat}: ${c.status}`, c.message ?? ""));
socket.on("connect_error", (e) => console.error(e.message, e.data?.message));
// Follows belong to the socket: send them again after every (re)connect.
socket.on("connect", () => {
socket.emit("subscribe_telegram", { chats: ["@solana_calls", "https://t.me/+AbCdEf123456"] }, (ack) => {
if (!ack.ok) return console.error(ack.error, ack.message);
console.log(ack.chats, `feed ${ack.feed}`);
});
});
// later: socket.emit("unsubscribe_telegram", { chats: ["solana_calls"] });
import socketio
sio = socketio.Client()
@sio.on("telegram")
def on_post(p):
delay = (p["receivedAt"] - p["postedAt"]) / 1000
print(f"{p['title']} (+{delay:.1f}s): {p['text'][:100]}\n {p['url'] or ''}")
for mint in p["addresses"]["solana"]:
print(" CA", mint)
@sio.on("telegram_chat")
def on_chat(c):
print(f"{c['chat']}: {c['status']}", c.get("message", ""))
@sio.event
def connect(): # send the follows again after every (re)connect
sio.emit("subscribe_telegram", {"chats": ["solana_calls", "https://t.me/+AbCdEf123456"]},
callback=lambda ack: print(ack.get("chats") or ack))
# YOUR_STREAM_SERVER: a server's address from your dashboard
sio.connect("https://YOUR_STREAM_SERVER", auth={"api_key": "YOUR_KEY"}, transports=["websocket"])
sio.wait()
Connecting
The same as for the X stream: your key in the handshake, auth: { api_key } (or the x-api-key header). A refused connection gets a connect_error whose message says why: see Connecting on the X stream's page.
Subscribe
socket.emit("subscribe_telegram", { chats: ["@solana_calls", "https://t.me/+AbCdEf123456"] }, ack);
chats names Telegram channels and groups:
- public ones by username:
solana_calls,@solana_calls,https://t.me/solana_calls, in any case; - private ones by an invite link:
https://t.me/+AbCdEf123456orhttps://t.me/joinchat/AbCdEf123456, one that doesn't need an admin's approval.
A comma-separated string or { chat: "solana_calls" } work too. Each call adds to what the socket follows; following a chat twice changes nothing. People, bots and t.me/c/… links (they open only for members: use the chat's invite link) can't be followed.
Your key may follow 25 chats at once on a server, counted across all its sockets there: a chat two of your sockets follow takes one of the 25. A call that would go past 25 is refused whole (limit_exceeded), and nothing of it is followed.
A key may also add 25 new chats a day on each server, and the server takes so many new chats a day from all keys together. Chats already in use on that server don't count, so you can add and drop those as often as you like.
Ack
{
"ok": true,
"chats": [
{ "chat": "+AbCdEf123456", "status": "pending" },
{ "chat": "solana_calls", "status": "live", "chatId": -1001234567890, "title": "Solana Calls", "kind": "channel", "server": "SERVER_ADDRESS" }
],
"max": 25,
"feed": "up"
}
chats- everything the socket follows now, with its status:live- set up: new posts come through. With the chat'schatId,titleandkind(channel,supergrouporgroup), andserver: the address of the server its posts come in on (Servers);pending- being set up, usually seconds, at busy times a few minutes; atelegram_chatevent follows;error- could not be set up yet (message); it is tried again every few minutes.
rejected- only when a chat can't be followed: itsstatusandmessagesay why (below).feed-upwhile the stream is live,downfor the moment it reconnects. Your follows are kept either way.
Response - telegram
{
"chat": "solana_calls",
"chatId": -1001234567890,
"title": "Solana Calls",
"kind": "channel",
"id": 4821,
"text": "New launch 🚀 CA: 7GCihgDB8fe6KNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr",
"url": "https://t.me/solana_calls/4821",
"addresses": { "solana": ["7GCihgDB8fe6KNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr"], "evm": [] },
"fromId": null,
"editedAt": null,
"postedAt": 1794220480000,
"receivedAt": 1794220480312
}
chat- the chat's username, in lower case; for a private chat, the invite link you followed it by (+…).chatId- Telegram's id for the chat, the one bots use (-100…for channels and supergroups). It stays the same when the username changes.chatIdandidtogether name a post.id- the post's number in the chat.text- the post's text, or a photo's or video's caption; empty when it has neither.url- the post on t.me. For a private channel or supergroup at.me/c/…link, which opens for its members;nullin a small group.addresses- the token addresses in the post, in the order they appear, each once:solana- mints (base58, 32 bytes);evm-0xaddresses, in lower case. Taken from the text and from its links, the ones behind link text too. Transaction hashes and signatures are not taken for addresses.fromId- in a group, the sender's Telegram id (negative when someone posts as a channel); in a channel usuallynull.editedAt- when the post was edited (ms): an edit that changes the text or its links comes again, whole, with the sameid.nullfor a new post.postedAt- when the post was made, in ms (Telegram gives the second).receivedAt- when our servers had it, in ms: the chat'sserverfirst, the others a moment later.
Only posts made after you subscribe come through. Every post from a followed chat arrives once per socket that follows it.
Response - telegram_chat
{ "chat": "solana_calls", "status": "live", "chatId": -1001234567890, "title": "Solana Calls", "kind": "channel", "server": "SERVER_ADDRESS" }
{ "chat": "no_such_chat", "status": "not_found", "message": "no Telegram channel or group with this username" }
Sent when a chat you added is set up, or turns out it can't be, and when a live chat's server changes. A chat that can't be followed is dropped from your list and gives its slot back:
status | When |
|---|---|
not_found | No channel or group has this username. |
invite_invalid | The invite link is invalid or has expired. |
needs_approval | The chat approves new members by hand: use a link that doesn't need approval. |
not_a_chat | The username is a person or a bot. |
private | The chat is private: follow it by an invite link. |
chat_full | The chat has as many members as Telegram allows. |
Unsubscribe
socket.emit("unsubscribe_telegram", { chats: ["solana_calls"] }, (ack) => console.log(ack.removed, ack.chats));
socket.emit("unsubscribe_telegram", {}); // every chat on this socket
The ack's chats is what the socket still follows. Closing the socket unsubscribes everything on it.
Your subscriptions
socket.emit("subscriptions", {}, (s) => console.log(s.telegram.key, s.tweets.key));
Changes nothing: it tells you what this socket follows, and what your key follows on this server over all its sockets (what the limits count), for Telegram and X both:
{
"ok": true,
"sockets": 2,
"maxSockets": 5,
"telegram": {
"chats": [{ "chat": "solana_calls", "status": "live", "chatId": -1001234567890, "title": "Solana Calls", "kind": "channel", "server": "SERVER_ADDRESS" }],
"key": [{ "chat": "+AbCdEf123456", "status": "pending", "sockets": 1 },
{ "chat": "solana_calls", "status": "live", "chatId": -1001234567890, "title": "Solana Calls", "kind": "channel", "server": "SERVER_ADDRESS", "sockets": 2 }],
"max": 25,
"newToday": 3,
"newPerDay": 25,
"feed": "up"
},
"tweets": { "users": [], "key": [], "max": 50, "newToday": 0, "newPerDay": 100, "feed": "up" }
}
sockets- your key's sockets open on this server now, ofmaxSockets.chats- what this socket follows, as in the ack.key- every chat your key follows on this server, on any of its sockets, with how many of them follow it (sockets).max- the chats your key may follow at once here;newTodayofnewPerDay- the new chats your key added here today.tweets- the same for the X stream.
Follows belong to sockets: a socket that reconnects follows nothing until it subscribes again, while key still lists what your other sockets follow.
Errors
error | When |
|---|---|
plan_required | Your plan doesn't include the Telegram stream: it comes with Professional (plan, upgrade). |
invalid_request | Something in chats is not a channel or group (message names it); nothing of the call is followed. |
limit_exceeded | The call would take your key past 25 chats on this server (max, followed, message). Unsubscribe some first. |
rate_limited | No more new chats on this server for now: your key's 25 a day, or the server's day for all keys, is used up (retryAfterMs, message says which). Chats already in use there don't count and always work. |
unavailable | Telegram isn't running on this server right now: try again in a few minutes, or use another server. |
An error comes in the ack, and also as a subscription_error event (for clients that don't pass an ack).
Notes
- Included in Professional: posts don't count against any other limit.
- A private chat followed by its invite link sees a new member join through that link.
- If your plan ends or your key is switched off, the server closes your sockets within a couple of minutes, sending a
subscription_error(plan_requiredorkey_disabled) first. - A server restarting (an update) closes your socket once; reconnect and subscribe again in your
connecthandler, as above. - When a chat's
serveris down, another server takes the chat over after a minute or two and atelegram_chatnames it; posts made in between can be missed. Your follows stay as they are.
LimitsProfessional 5 sockets · 25 Telegram chatsSee plans →