Skip to main content

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).

ChannelSocket.IO, on a stream server's own address (on your dashboard)
Authyour Professional plan's key (the key)
Emitstelegram, telegram_chat
Limit25 chats and 5 sockets per key on each server (the sockets are shared with the X stream)
PlanProfessional

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​

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"] });

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/+AbCdEf123456 or https://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's chatId, title and kind (channel, supergroup or group), and server: the address of the server its posts come in on (Servers);
    • pending - being set up, usually seconds, at busy times a few minutes; a telegram_chat event 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: its status and message say why (below).
  • feed - up while the stream is live, down for 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. chatId and id together 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 a t.me/c/… link, which opens for its members; null in a small group.
  • addresses - the token addresses in the post, in the order they appear, each once: solana - mints (base58, 32 bytes); evm - 0x addresses, 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 usually null.
  • editedAt - when the post was edited (ms): an edit that changes the text or its links comes again, whole, with the same id. null for 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's server first, 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:

statusWhen
not_foundNo channel or group has this username.
invite_invalidThe invite link is invalid or has expired.
needs_approvalThe chat approves new members by hand: use a link that doesn't need approval.
not_a_chatThe username is a person or a bot.
privateThe chat is private: follow it by an invite link.
chat_fullThe 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, of maxSockets.
  • 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; newToday of newPerDay - 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​

errorWhen
plan_requiredYour plan doesn't include the Telegram stream: it comes with Professional (plan, upgrade).
invalid_requestSomething in chats is not a channel or group (message names it); nothing of the call is followed.
limit_exceededThe call would take your key past 25 chats on this server (max, followed, message). Unsubscribe some first.
rate_limitedNo 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.
unavailableTelegram 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_required or key_disabled) first.
  • A server restarting (an update) closes your socket once; reconnect and subscribe again in your connect handler, as above.
  • When a chat's server is down, another server takes the chat over after a minute or two and a telegram_chat names it; posts made in between can be missed. Your follows stay as they are.

LimitsProfessional 5 sockets · 25 Telegram chatsSee plans →