Paid Media

Bot API 7.6 — July 2024, opened to any chat in 7.9

Paid media is a photo or video that arrives blurred. The recipient pays a number of Telegram Stars to unlock it, and the payment goes to whoever sent it. Nothing about the upload changes: it is an ordinary album with a price attached.

---

Sending

send_paid_media() takes the price in Stars and a list of InputMediaPhoto / InputMediaVideo:

from pyrogram.types import InputMediaPhoto, InputMediaVideo

await app.send_paid_media(
    chat_id="my_channel",
    stars_amount=25,
    media=[
        InputMediaPhoto("cover.jpg"),
        InputMediaVideo("clip.mp4"),
    ],
    caption="Behind the scenes from today's shoot",
)

The caption is not paid: everyone sees it, which is what makes it the sales pitch. Only the media behind it is locked.

payload is a string of your own that comes back to you when someone pays, so you can tie a purchase to a record on your side without a database lookup on the caption.

Knowing who paid

When a user unlocks paid media a bot sent, the bot is told:

@app.on_purchased_paid_media()
async def paid(client, purchase):
    print(f"{purchase.from_user.id} unlocked, payload={purchase.payload}")

Reading it back

On a message that carries paid media, message.paid_media holds a PaidMediaInfo: stars_amount is the price, and media is the list of items. Until the viewer pays, each item is a PaidMediaPreview — dimensions and a blurred thumbnail, with no file to download. After payment the same list holds real Photo and Video objects.

Gotchas

• stars_amount is per message, not per item. A five-photo album unlocks as one purchase.

• Sending paid media to a channel requires the channel to be eligible for Stars payouts; the API rejects it otherwise rather than sending it unpaid.

• A bot cannot unlock paid media on a user’s behalf, and a user session cannot buy media through the API without going through the normal payment form.