Sponsored messages

Related TL schema:

Getting sponsored messages

sponsoredMessage#4d93a990 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 media:flags.14?MessageMedia 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---

messages.getSponsoredMessages#9bd2f439 peer:InputPeer = messages.SponsoredMessages;

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

More about sponsored messages on Telegram

Displaying sponsored messages

Sponsored messages must be displayed as follows:

• In channels, they must be displayed below all other posts in the channel, after the user scrolls further down, past the last message.
  Sponsored channel messages have:

  • A title (contained in title)
  • A text (contained in message+entities)
  • An optional media (contained in media, clicking on it should open the URL in url as below; a separate button should be available to expand the video in fullscreen, which should not open the linked url when clicked).
  • 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.

• In bots, they must be displayed above the chat, akin to an action bar Bot ads have:

  • A title (contained in title): must be locally prepended with a blue-colored "Ad" prefix, or a "Recommended" prefix if the recommended flag is set.
  • A text (contained in message+entities)
  • When the ad action bar is clicked, clients should open 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).

  If the photo flag is set, a thumbnail-sized version of it should be displayed in the right section of the action bar.

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

Counting sponsored message views

---functions---

messages.viewSponsoredMessage#673ad8f1 peer:InputPeer random_id:bytes = Bool;

Once the entire text of the ad is shown on the screen (excluding the button for channel ads), messages.viewSponsoredMessage must be called with the random_id of the sponsored message.

Clicking on sponsored messages

---functions---

messages.clickSponsoredMessage#f093465 flags:# media:flags.0?true fullscreen:flags.1?true peer:InputPeer random_id:bytes = Bool;

If the user does one of the following actions, messages.clickSponsoredMessage must be called with the random_id of the sponsored message:

• Clicks on a link in the sponsored message
• Clicks on the bot ad bar
• 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
• Clicks on the media (the media flag must also be set in this case)
• Clicks on the fullscreen button, then clicks on the media (the fullscreen and media flags must be set)

Reporting sponsored messages

sponsoredMessage#4d93a990 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 media:flags.14?MessageMedia 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---

messages.reportSponsoredMessage#1af3dbb8 peer:InputPeer random_id:bytes option:bytes = channels.SponsoredMessageReportResult;

To report a sponsored message to Telegram's moderators, invoke messages.reportSponsoredMessage, passing the channel/bot 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/bot owner

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

See here » for more info on how to withdraw channel/bot 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.