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 Next.js, 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. From Next.js you call it through the yeetpost npm package, from a route handler, a server action or a scheduled job.
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 yeetpostSet your API key as an environment variable in .env.local. Keep it out of any name that starts with NEXT_PUBLIC_, because those are inlined into the browser bundle:
YEETPOST_API_KEY=<your-api-key>Send the post from a route handler, a server action or a scheduled job, never from a client component:
// app/api/announce/route.ts
import { yeetpost } from "yeetpost";
export async function POST(request: Request) {
const { text } = await request.json();
await yeetpost({
connection: "<your-connection-slug>",
text,
});
return Response.json({ ok: true });
}Deploying on Vercel? Add YEETPOST_API_KEY under Project Settings, Environment Variables, so the server build has it as well as your machine.
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.
Where should this run in a Next.js app?
On the server: a route handler, a server action or a cron job. The API key has to stay there, so read it from process.env and never put it behind a NEXT_PUBLIC name, which would ship it to the browser.
Related guides
Related resources
Copy this guide (with your values) for use with LLMs or sharing with colleagues.