Send Paid Media with the Telegram Bot API
· 4 min read · 18+ readers

Paid media is a post whose photos or videos are hidden behind a Stars payment. People see a blurred preview, tap, pay and view. Creators can post it by hand in a channel, and bots can send it through the Bot API. This guide is for developers. For the non-technical overview, read paid media explained. Check the official Bot API reference for the current method fields and the allowed range of Star prices, which Telegram has changed before.
The method
sendPaidMedia sends a message with locked media. Its main parameters are:
chat_id: where to send. A user, or a channel where the bot can post.star_count: the price in Stars. Telegram limits the allowed range, so check the documentation.media: a list ofInputPaidMediaobjects.payload: a string that identifies this post. You receive it back when someone pays.caption,parse_mode,show_caption_above_media,reply_markupand the usual options.
Media types include photos and videos:
{
"chat_id": "@mychannel",
"star_count": 25,
"payload": "set_2026_11_a",
"caption": "Behind the scenes, 8 photos",
"media": [
{ "type": "photo", "media": "https://example.com/p1.jpg" },
{ "type": "photo", "media": "https://example.com/p2.jpg" }
]
}
The media value can be a file_id, an HTTP URL that Telegram fetches, or an upload with attach://name in a multipart request. Video items accept extra fields such as duration and dimensions. Look up the exact InputPaidMediaPhoto and InputPaidMediaVideo structures in the reference.
Where it can be sent
For channels, add the bot as an administrator with the right to post. See adding a bot as channel admin. The Bot API documentation describes how paid media can be sent to chats and channels, and how a bot can receive Stars from such posts. Behaviour can differ between private chats and channels, so test both.
Knowing when someone buys
When a user pays, your bot can receive a purchased_paid_media update. It includes the buyer (from) and the paid_media_payload you set. Use it to count sales per post, thank buyers or give extra access. Include the update type in allowed_updates if you filter. Check that the update name matches the current documentation.
What Telegram shows
- A blurred or locked preview with the price.
- After payment, the buyer sees the full media.
- Buyers may be able to forward, depending on content protection settings of the chat.
Content rules
Telegram's terms apply to everything sold with Stars. Do not sell content you do not own, content involving minors, non-consensual material or anything illegal. App stores and Telegram impose restrictions on sensitive content, and your channel can be limited if you break the rules. Keep public previews safe for work. See 18+ content rules.
Pricing and records
- Choose a price you have tested. See pricing.
- Keep a table of posts, prices and sales by
payload. - Reconcile with
getStarTransactionsand your Stars balance. - Keep records for tax. See record keeping.
Refunds
Paid media purchases are Star transactions. If you need to refund one, check how the documentation handles it, and which charge identifiers you must keep. Write a policy before you sell. See refunds and disputes.
Protecting content
Telegram has content protection settings for channels that limit forwarding and saving. They do not stop screenshots. Plan accordingly, with watermarks and rules. See protecting content from leaks.
A small helper
async function postPaid(chat, stars, files, caption, payload) {
return api("sendPaidMedia", {
chat_id: chat, star_count: stars, payload, caption,
media: files.map((u) => ({ type: "photo", media: u })),
});
}
Wrap errors, log the returned message id and store it with the payload.
Troubleshooting
- Bot cannot post: it lacks admin rights or the chat id is wrong.
- Invalid star count: outside the allowed range.
- Media rejected: wrong type, file too large or URL unreachable.
- No purchase updates:
allowed_updatesexcludes the type, or the post was made by hand, not by the bot.
Quick checklist
- Bot is an admin in the channel with posting rights.
- star_count is within the allowed range.
- Each post has a unique payload.
- purchased_paid_media is in allowed_updates.
- Previews and captions are honest and safe for work.
- Sales are reconciled with getStarTransactions.
- A refund policy is published.
- Content protection and watermarking are considered.
Test before you sell
Post a paid item to a private test channel with a low price, buy it from a second account and check that you receive the purchase update with the right payload. Only then use the same code in your real channel.
Frequently asked questions
Can I post paid media manually instead?
Yes. Creators can do this from the app in channels where the feature is available. The API is for automation.
Can I mix photos and videos?
The API accepts a list of paid media items. Check the current limits on count and types.
How do I price a bundle?
One star_count applies to the whole post.
Is this available everywhere?
Availability can depend on app version and region. Test from a normal account.
Related guides

Telegram Paid Media Explained: Sell Posts for Stars
How paid media works on Telegram: locked photos and videos priced in Stars, previews, bots, good practice and the content rules to follow.

Telegram Stars Payments in a Bot: Invoice to Refund
Sell digital goods in a bot with Telegram Stars: sendInvoice in XTR, pre_checkout_query, successful_payment, delivery and refundStarPayment.

Telegram Paid Channels and Subscription Links
How to charge for access to a Telegram channel: Stars subscription invite links, free versus paid access, retention, rules and how to run it well.

Add a Bot as Channel Admin and Post to Your Channel
Give a bot posting rights in a Telegram channel, find the chat id, send posts with sendMessage, schedule them from code and fix common permission errors.

Protecting Your Content from Leaks on Telegram
Practical steps to reduce leaks of paid or private content on Telegram: content protection, member vetting, watermarks, monitoring and response plans.

A Telegram Webhook on AWS Lambda or a Small Server
Two ways to receive Telegram updates: an AWS Lambda function URL and a tiny Node server behind HTTPS, with secret token checks, fast replies and queues.
More in Build on Telegram
- Bot Privacy Mode and Group Admin Rights Explained
- BotFather Commands: What Each One Does
- Common Telegram Bot Errors and How to Fix Them
- Connect a Bot to Your Telegram Business Account (Chatbot Mode)
All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial