Sponsored messages

Related TL schema:

Getting sponsored messages

sponsoredMessage#bdedf566 flags:# recommended:flags.5?true can_report:flags.12?true random_id:bytes url:string title:string message:string entities:flags.1?Vector<MessageEntity> photo:flags.6?Photo color:flags.13?PeerColor button_text:string sponsor_info:flags.7?string additional_info:flags.8?string = SponsoredMessage;

messages.sponsoredMessages#c9ee1d87 flags:# posts_between:flags.0?int messages:Vector<SponsoredMessage> chats:Vector<Chat> users:Vector<User> = messages.SponsoredMessages;

---functions---

channels.getSponsoredMessages#ec210fbf channel:InputChannel = messages.SponsoredMessages;

Each time the user opens a channel, channels.getSponsoredMessages must be called to receive sponsored messages available for this channel. The result must be cached for 5 minutes.

More about sponsored messages on Telegram

Displaying sponsored messages

Sponsored messages must be displayed below all other posts in the channel, after the user scrolls further down, past the last message.

Sponsored messages have:

• A title (contained in title)
• A text (contained in message+entities)
• A button at the button (label in button_text) that when clicked, opens the URL in url.
  A confirmation prompt should be shown before opening the URL, unless the host part of the URL matches the following regex: (^|\\.)(telegram\.(org|me|dog)|t\.me|te\.?legra\.ph|graph\.org|fragment\.com|telesco\.pe)$, in which case the URL should be opened without confirmation (and if it's a deep link », it should be opened directly in-app, without passing through the browser).

The message should be marked as "Recommended" instead of "Sponsored" if the recommended flag is set.

If the photo flag is set, it should be used to display a profile photo bubble for the sponsored message, like for messages sent in groups.

If the sponsor_info or additional_info flags are set, an additional "Sponsor info" menu item must be present in the message context menu (the menu that pops up when clicking on a button), that when clicked, displays the contents of the flags.

If set, the sponsored message should use the message accent color » specified in color.

Counting sponsored message views

---functions---

channels.viewSponsoredMessage#beaedb94 channel:InputChannel random_id:bytes = Bool;

Once the entire text is shown on the screen (excluding the button), channels.viewSponsoredMessage must be called with the random_id of the sponsored message.

Clicking on sponsored messages

---functions---

channels.clickSponsoredMessage#18afbc93 channel:InputChannel random_id:bytes = Bool;

If the user either:

• Clicks on a link in the sponsored message
• Opens a sponsored chat or a sponsored website via the associated button
• Opens the sponsored chat via the sponsored message name, the sponsored message photo, or a mention in the sponsored message

channels.clickSponsoredMessage must be called with the random_id of the sponsored message.

Reporting sponsored messages

sponsoredMessage#bdedf566 flags:# recommended:flags.5?true can_report:flags.12?true random_id:bytes url:string title:string message:string entities:flags.1?Vector<MessageEntity> photo:flags.6?Photo color:flags.13?PeerColor button_text:string sponsor_info:flags.7?string additional_info:flags.8?string = SponsoredMessage;

sponsoredMessageReportOption#430d3150 text:string option:bytes = SponsoredMessageReportOption;

channels.sponsoredMessageReportResultChooseOption#846f9e42 title:string options:Vector<SponsoredMessageReportOption> = channels.SponsoredMessageReportResult;
channels.sponsoredMessageReportResultAdsHidden#3e3bcf2f = channels.SponsoredMessageReportResult;
channels.sponsoredMessageReportResultReported#ad798849 = channels.SponsoredMessageReportResult;

---functions---

channels.reportSponsoredMessage#af8ff6b9 channel:InputChannel random_id:bytes option:bytes = channels.SponsoredMessageReportResult;

To report a sponsored message to Telegram's moderators, invoke channels.reportSponsoredMessage, passing the channel ID, the random_id of the sponsored message and an empty option field.

Note that only sponsored messages with the sponsoredMessage.can_report flag set may be reported.

Then, if the result is:

• A channels.sponsoredMessageReportResultChooseOption constructor, the user must choose a report option from the localized options available in options, and after selection, the method must be invoked again, passing the option's option field to the option parameter of channels.reportSponsoredMessage.
  The title field of channels.sponsoredMessageReportResultChooseOption must be used as title of the option selection popup.
• A channels.sponsoredMessageReportResultAdsHidden constructor, sponsored messages were hidden for the user in all chats.
• A channels.sponsoredMessageReportResultReported constructor, the sponsored message was reported successfully.

The method may also return:

• An AD_EXPIRED RPC error, for expired (too old or not found) ads
• A PREMIUM_ACCOUNT_REQUIRED RPC error, if the user asked to hide sponsored messages in the chosen option, but Telegram Premium is required for this action.

Testing sponsored messages

For the channel https://t.me/SecretAdTestChannel the system will always return a sponsored message: promoting either a channel, a particular message in a channel, or a bot with a start parameter.

Withdrawing ad revenue as a channel owner

Telegram has one of the most generous reward systems in the history of social media. Telegram channel owners can now receive 50% of the revenue from ads displayed in their channels.

See here » for more info on how to withdraw channel ad revenue, as well as view detailed revenue stats.

Sponsored messages in third-party apps

Telegram continues to grow worldwide, in part thanks to third-party apps using the Telegram API. To cover the increasing costs that come with this growth, Telegram added sponsored messages – a paid privacy-friendly way to promote bots and channels.

If their app allows its users to access content from Telegram channels, third-party developers using the Telegram API are required to support and properly display official sponsored messages in their apps by January 1, 2022. Unfortunately, Telegram cannot financially sustain third-party apps that do not display sponsored messages and they will have to be disconnected.

Telegram's API usage will continue to be free of charge for all developers. The rules regarding monetization in third-party apps remain the same: developers are allowed to monetize their coding efforts through advertising of their own or other legitimate means, provided that all the methods of monetization used in their apps are prominently mentioned in their app store descriptions.