Can I post to a Telegram group or to a person?
No. A connection has to be a channel. A group or a private chat is refused when you try to connect it, because the permalink shapes and the posting rules are not the same.
How to sendfrom
Follow these steps to connect Telegram message, send from TypeScript, and track delivery.
Telegram posting goes through a bot you own. You get a token from @BotFather, add the bot to your channel as an admin that can post messages, and give yeetpost the token and the channel. A connection is one channel rather than one bot, so a bot that is admin of three channels is three connections. In plain TypeScript this is a few lines in any Node process: a worker, a one-off script or a deploy step that already knows what to say.
What Telegram takes
| How you connect | A bot token from @BotFather, plus the channel @handle or its numeric id starting -100 |
|---|---|
| Connection slug | telegram for the first channel, then a slug built from the channel |
| Text limit | 4096 characters |
| Text limit with an image | 1024 characters, because the text becomes the photo's caption |
| Images | Up to 5 per post, png and jpeg only |
| Alt text | No, Telegram has no field for it, so it is dropped |
| Threads | Yes, up to 24 replies under the head message |
| First comment | No, LinkedIn only |
| Scheduling | Yes |
| Permalink | https://t.me/<handle>/<message id>, or https://t.me/c/<internal id>/<message id> for a private channel |
| Per-post fee | None |
1
Connect your platform
Connect a Telegram channel to yeetpost with a bot you own:
- Message @BotFather and send
/newbotto get a bot token - Add the bot to your channel as an admin with permission to post messages
- Go to app.yeetpost.com
- Click Add connection, select Telegram, and paste the token and the channel
The channel is either its public @handle or, for a private channel, the numeric id starting with -100. All three things are checked when you connect: that the token is real, that the chat is a channel rather than a group, and that the bot is an admin that can post.
Paste your connection slug here and we'll auto-fill it into the code examples below.
2
Get your API key
Get your API key from the yeetpost dashboard:
- Go to app.yeetpost.com/app/settings
- Copy your API key
Paste your API key here and we'll auto-fill it into the code examples below.
3
Send your post
Install the yeetpost package:
npm install yeetpostExport your API key so the process can read it:
export YEETPOST_API_KEY=<your-api-key>Send a post:
import { yeetpost } from "yeetpost";
await yeetpost({
connection: "<your-connection-slug>",
text: "Hello from yeetpost!",
});To post to several connections in one call, use the JSON endpoint. It answers with one result per connection and accepts an Idempotency-Key, so a retry cannot double-post:
const response = await fetch("https://api.yeetpost.com/api/v2/posts", {
method: "POST",
headers: {
"x-api-key": process.env.YEETPOST_API_KEY!,
"content-type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
text: "Hello from yeetpost!",
connectionSlugs: ["<your-connection-slug>"],
}),
});
const { results } = await response.json();
for (const result of results) {
console.log(result.connectionSlug, result.status, result.url);
}Read each result.status rather than the HTTP status alone: one connection can fail while the rest go out.
4
Track your posts
Monitor all your posts from the yeetpost dashboard:
- Go to the Feed tab in the yeetpost dashboard
- View all posts sent via yeetpost, including status and timestamps
5
Review the security checklist
Review the Security Checklist to ensure your implementation is secure.
When a Telegram post is refused
Each of these fails only the Telegram item. Every other connection on the same request still goes out. The full vocabulary is in the errors reference.
| Code | Status | When |
|---|---|---|
| invalid_request | 400 | Text over 4096 characters, or over 1024 with an image attached |
| media_unsupported | 400 | The image is not a png or a jpeg |
| shape_unsupported | 400 | A firstComment was given. Telegram has no first comment |
| unauthorized | 401 | The bot token was revoked. Connect again with the new one |
| platform_rejected | 422 | Telegram refused the message, for example the bot lost its admin rights |
| internal_server_error | 500 | Our fault. Quote the req_id when you report it |
Telegram FAQ
Why does my gif come back media_unsupported?
Telegram takes png and jpeg photos only. The check runs before the message is sent, so the same post still goes out to every other connection on it.
Why did my alt text disappear?
Telegram has no field for a photo description, so yeetpost drops it for this connection. The same description still travels to X, Bluesky, Mastodon and LinkedIn on the same post.
Why is my text refused at 2000 characters when the limit is 4096?
An image turns the text into the photo's caption, and a caption holds 1024 characters. Send the long text on its own, or move it into a reply.
Does the yeetpost package work outside Node?
It is a thin wrapper over the same HTTP endpoint, so anywhere you have fetch and can keep a secret it works. Do not run it in a browser bundle: the key would be readable by anyone loading the page.
Related guides
Related resources
Copy this guide (with your values) for use with LLMs or sharing with colleagues.