Posting a Telegram story with MTProto

How do you post a story through the Telegram API?

Bot API vs MTProto for stories

This is the first question and the most expensive one to answer the hard way. A bot token cannot post stories, and that is not a temporary restriction.

A bot only receives a story and can answer it. That is why Socialift does not mirror the story methods on the Telegram (bot) client — they exist only on TelegramAccount.

Why a bot cannot post stories

Check first: can_send_story

Telegram's documentation asks for exactly this: "Before posting a story, clients should invoke stories.canSendStory". You see the error before the upload, not after it.

import asyncio
from socialift import ApiError, TelegramAccount

async def main():
    async with TelegramAccount.from_env() as tg:
        targets = await tg.story_targets()
        print("channels you can post as:", targets.chats)

        try:
            check = await tg.can_send_story("me")
        except ApiError as exc:
            print("cannot post right now:", exc)
            return
        print("free slots:", check.count)

asyncio.run(main())

Who may post, and the errors you get

When a condition is not met, Telegram returns a specific error code and the SDK maps it onto its own exception types.

Duration: the period values

Telegram accepts exactly four period values and the server rejects anything else. The Socialift SDK checks this before the file is uploaded.

If period is omitted the field is not sent at all and Telegram applies 24 hours. When it expires the story moves to the archive; with pinned=True it also stays on the profile.

Privacy: who sees the story

In MTProto this is a Vector<InputPrivacyRule>. The SDK reduces it to four shorthands and still accepts a ready-made rule list for the complicated cases.

everyone

The default, matching the app — InputPrivacyValueAllowAll. Everyone sees the story.

contacts

Contacts only — InputPrivacyValueAllowContacts.

close_friends

Close friends only — InputPrivacyValueAllowCloseFriends. The list itself is managed through contacts.editCloseFriends.

selected

Only the chosen users — InputPrivacyValueAllowUsers. With this value the allow list is mandatory.

deny

Exceptions — InputPrivacyValueDisallowUsers. Rules apply in the order given, so deny is appended last: "contacts, but not these people".

Media and text: vertical, 30 MB and the caption trap

Posting a story with the Socialift SDK

send_story uploads the file, assembles the privacy rules and calls stories.sendStory. The response is an Updates object carrying the new story id.

import asyncio
from socialift import RateLimitError, TelegramAccount

async def main():
    async with TelegramAccount.from_env() as tg:
        check = await tg.can_send_story("me")
        if not check.count:
            print("active story limit reached")
            return
        try:
            result = await tg.send_story(
                "me",
                "story.mp4",
                caption="New collection",
                period=43200,
                privacy="close_friends",
                deny=["@competitor"],
                pinned=True,
                noforwards=True,
            )
        except RateLimitError as exc:
            print("weekly or monthly cap, wait:", exc.retry_after)
            return
        print(result)

asyncio.run(main())

Reading, editing and deleting

An edit sends only the fields you pass and leaves the rest untouched — which is why privacy defaults to None in edit_story.

import asyncio
from socialift import TelegramAccount

async def main():
    async with TelegramAccount.from_env() as tg:
        peer = await tg.stories("me")
        for story in peer.stories:
            print(story.id, story.expire_date)

        await tg.edit_story("me", 42, caption="Corrected text")
        await tg.edit_story("me", 42, privacy="contacts", deny=["@competitor"])
        await tg.delete_story("me", [42, 43])

asyncio.run(main())

Checklist before going live

• ▸Make sure you are not trying to post with a bot token — the Bot API has no such method.
• ▸Call can_send_story() before every post and check count.
• ▸Keep the media vertical and under 30 MB; police the aspect ratio yourself, since Telegram never fixed one.
• ▸Pass only 21600, 43200, 86400 or 172800 as period; without Premium, only 86400 works.
• ▸With privacy="selected", the allow list is mandatory.
• ▸Catch STORY_SEND_FLOOD_WEEKLY and MONTHLY as RateLimitError and honour retry_after.
• ▸When posting as a channel, verify the post_stories right and the boost level in advance.
• ▸Store the session file encrypted — it grants full access to the account.
• ▸Formatting in story text depends on the server-side stories_entities config and does not work everywhere.