TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Send Paid Media with the Telegram Bot API

· 4 min read · 18+ readers

Send Paid Media with the Telegram Bot API: TSocial guide cover card

Paid media is a post whose photos or videos are hidden behind a Telegram Stars star icon Stars payment. People see a blurred preview, tap, pay and view. Creators can post it by hand in a channel, and bot icon 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 code icon API reference for the current method fields and the allowed range of Star prices, which Telegram has changed before.

The method

sendPaidMedia send icon (paper plane) sends a message with locked media. Its main parameters are:

  • chat_id: where to send. A user, or a channel megaphone icon channel where the bot can post.
  • star_count: the price in Stars. Telegram limits the allowed range, so check the documentation.
  • media: a list of InputPaidMedia objects.
  • payload: a string that identifies this post. You receive it back when someone pays.
  • caption, parse_mode, show_caption_above_media, reply_markup and 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 lock icon 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 safety icon 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 getStarTransactions and 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_updates excludes 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

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Send Paid Media with the Telegram Bot API | TSocial