This page lists general rules and detailed clarifications for creating good Instant View templates for news articles.
For more info on templates, see our Introduction and Sample Templates.
Instant View templates must meet these five basic requirements:
Instant View pages work best with relatively static articles. Dynamic pages (such as the main page of a news site) that are constantly refreshed with new links and media don't need IV.
Templates should only generate IV pages for articles and should not affect service areas of websites, as well as any other sections unsuitable for IV. IV pages should not be generated for articles that have content which is not supported in IV since this would result in unacceptable loss of information (e.g., IV pages don't support dynamic maps — if you generate an IV page for a wiki article with a dynamic map, the IV version will be missing a key element).
IV pages should show the entire text of the article, along with all its formatting, media, and embedded content. This includes headings, subheadings, quotes, captions, photos, videos, links, etc.
IV pages should display only the source’s content – removing all interface elements, advertisments and irrelevant embedded material.
Pages with irregular elements should be processed correctly. All media, embeds, quotes and separators should be properly displayed.
Any attempt to add content that is not present on the original page will cause your template to be rejected.
You may include the username of websites’ official channels in Instant View templates. The username is assigned to the channel property, and to be considered official, the channel must be labeled as such by the company or person who published it (on its website or social media).
More detailed criteria and clarifications are available below.
You can submit your template for review as soon as it covers a sufficient number of articles. Make sure you've enabled **Track Changes** for at least 10-15 different pages on the target website and that all IV pages are generated correctly.
When ready, simply tap Submit Template next to a template in the My Templates section:
Submitting a template from My Templates
Anyone can check how well Instant View templates process articles on their respective websites, and may submit feedback using the Report Issue button.
Click to select and highlight incorrectly parsed blocks in the source page or in the Instant View result and provide a detailed explanation of what is wrong (check the criteria below for ideas). The author of the template will be able to see all issues, fix and resubmit their work.
To make it easier to report issues in Instant View templates, we’ve compiled this list of characteristics that make a perfect template. Please use the list below as a reference when looking for issues in templates.
Templates must generate Instant View pages for all relevant pages on the target website.
1.1. Pages with static article-like content
Tip: It may be a good idea to identify a common feature of all the IV-positive pages and add rules so that the template only applies to them. Note that these pages only need IV pages if their essential content is supported in the IV format — otherwise, see 2.3.
Templates must not generate Instant View content for pages of the following types:
Tip: IV pages are cached. As articles get older, their cached IV pages update less frequently. Any pages that update content in real time would subsequently display outdated IV pages to users — which is unacceptable.
Tip: While it's possible to modify interactive components of a page into simple links, the IV format was primarily designed to allow Telegram users to enjoy web content in a quick and uniform way. Interacting with websites, buying things, writing reviews, etc. are outside of the current scope for IVs.
Tip: The rule is simple. If an essential part of an article is not available in the Instant View format, an IV page must not be generated. In most cases, this will happen automatically but template creators can further protect their templates from data loss by marking any unsupported essential content using the @unsupported function. See this section for advice on handling unsupported videos.
All essential content must be presented on the Instant View page.
These properties are also essential, but not always present or supported in IV:
NEW Right-To-Left pages (Arabic, Persian, Hebrew, etc.) must have the dir="rtl" attribute set.Important: See our Clarifications below for tips on how to best process cover images, date and time, author names and URLs, and other tricky elements.
site_name property must include the name that users see on the main page of the website (examples here).Note: Telegram apps will show
site_namein the header of the IV. It must match the name that users see on the main page of the website (see examples) and it must not contain any additional data. For this reason metadata should not be used blindly. If the main page doesn’t display a site name, use the name they use on social networks (Telegram channels have priority).
Tip: Check that pages featuring unsupported content do not generate IV pages. In most cases, this will happen automatically, but it is a good idea to confirm this before submitting your template. Mark any unsupported essential content using the @unsupported function. See this section for advice on handling unsupported videos.
Anything that is not essential to the article in question should be removed from the Instant View page, including:
The resulting IV page may not contain any content not present in the original.
Tip: You may display the official Telegram channel of the website that published the article at the top of the IV page (by using the channel property). To be considered official, the channel must be labelled as such somewhere on the source website (doesn't have to be on the same page as the original article).
Below are some clarifications for the trickier aspects of creating perfect Instant View templates.
Author name is required only if it is presented in the source article in a consistent, clear and identifiable way (in an html block with particular properties), especially if there's a name of an actual person.
In less obvious cases, what the user sees when viewing the original article in a browser has priority over invisible meta-information. Names of actual people are always preferable over entity names like 'team' or the name of the website.
You may omit the author in cases where no name can be seen by a regular user opening the original article in the browser. You may omit the name when there's no identifiable person, only the website's 'team', 'editors', 'website name' etc.
Absent author names for articles in which no author can be easily identified by a regular viewing user are not considered an issue.
The date of publication is obligatory for news publications. It must be obtained by any means possible, including meta tags, etc. If the date is specified correctly, time is optional.
If conflicting dates are stored in multiple places on the source page, preference should be given to the time that is visible to an ordinary user who views the page in a browser.
The IV editor's 'Preview' section will always show the date/time in UTC format, while the 'Original' section may use a different time zone. It is possible for a perfect template to display a date/time that looks different than the original.
Support for time zones is optional, unless the time zone is reliably identifiable from the source, in which case it’s obligatory.
Tip: If given 'date published' and 'date last edited', use 'date published' for articles. For wiki-like entries 'date last edited' must be used.
A subtitle is a subordinate title of a published work or article giving additional information about its content. If this is present in the original article, a subtitle is required. Here's an example of a subtitle:
A Subtitle
Few publications actually use subtitles. More commonly, short summary sentences are shown below the title (and are called standfirst in the UK). These summary sentences are usually short and are not part of the article's text. It is advisable but not required to represent them as subtitle elements. Here's an example:
A Summary
Many publications use a slightly different style for their lead paragraphs. Unlike subtitles and summaries, the lead paragraph is part of the article's text. Even if the lead uses a different style from the rest of the text, it is less desirable to present it as a subtitle — but this is not a critical issue.
If the lead paragraph uses a different style, it is recommended to use bold or italic text.
A summary, then lead in bold
In the example above, the lead paragraph is highlighted in bold: “TAXI giant Uber has reportedly fired over 20 workers following an internal investigation into sexual harassment allegations.”
The article then continues: “The company told staff of the layoffs on Tuesday and related claims by law firm Perkins Coie, a person close with the case told Bloomberg.” It would be acceptable to present the “TAXI giant Uber…” paragraph as bold, or italic, or plain text.
Tip: Generally, it is advisable to avoid setting too much text as the subtitle. If the website publishes summaries that take an entire paragraph or even multiple paragraphs, it's better to use italic/bold text instead of the subtitle element to represent this content in IV.
Kickers are separately formatted parts of the title supported in IV 2.0 with the _kicker_ property. The kicker property must be set if a kicker is present and its text is actually a part of the title/story (see 'UBER SEX CLAIMS' on the screenshot above).
If the kicker represents a regular section or category into which the article falls, (e.g. 'CRIME: Seventy suitcases stolen from Heathrow airport'), it should be omitted. Missing section/category kickers are not considered an issue.
When several image resolutions are available and can be extracted reliably, the IV page should use better quality images (within reason). The optimal resolution range is 1280px-2560px, using larger images is pointless. Note that images that are too large (>5 MB) will fail to load. We recommend updating your template to IV 2.1 to automatically extract optimal images from the srcset attribute.
If for some reason it is only technically possible to obtain low-resolution versions of images (lower than 320px) for a page, but its original web version has high-resolution images, the page should not generate an IV.
Note: For the
Icontype, we highly recommend setting the correct size using the width/height attributes so that they appear the same way in IV as they do in the text. Otherwise, you risk grabbing the 3x version of an emoji and displaying it as a full-blown image.
See also: ****
It is obligatory to use a cover image:
In other cases, cover images are optional:
Sometimes, a cover is less desirable:
A cover must not be set if:
Tip: Cover images can also have captions in IV, don't lose them.
Slideshows are required only if the source article shows several photos or other media as a slideshow or gallery. If this is the case, do the following:
- Present all images in the IV as a gallery, if possible.
- If that's not possible, keep a link to the full gallery.
- If none of the above are possible, generate no IV for the page.
If the source has several ordinary images/videos/GIFs following each other in the source, you may also convert them into a slideshow, but this is purely optional. This makes more sense in cases when images serve as additional content (e.g., a long text about a new car which is followed by ten images of the car).
We will not accept issue reports based on presence or absence of slideshows for ordinary images following each other in the source article.
EXCEPTION! Slideshows must not be used when:
In the cases above, use images with captions (or even plain paragraph text) following one another.
Tip: Remember that captions should be preserved for all images in the source. If you lose captions for images you've put into a slideshow, it's a valid issue. IV Slideshows support both a caption for the entire slideshows and different captions for each individual element.
Any captions present in the source article must be preserved. This includes captions for the cover image and captions for all individual elements of slideshows.
All Captions Preserved
If the image has no caption, but has meaningful text in the alt attribute, you may use that text as the caption. This is optional, we will not accept issue reports about alt-text missing from captions.
Tip: Please don't include meaningless alt-text as captions (e.g., the PlayStation blog always puts the name of the corresponding game in the alt attribute of all screenshots – there's no need to reproduce that on the IV page.)
IV 2.0 supports a dedicated <cite> tag for credits in media captions. Credits in captions must be preserved and placed inside the appropriate tag, provided it is possible to reliably identify them.
Tall infographic images are currently unreadable in Telegram apps. If there’s a reliable way to identify them (e.g., consistently used attributes or a specific section on the website that only contains infographics) the IV must add an image link to the full version of the image. If there is no reliable way to identify such images and they are not consistently featured on the website, it is acceptable to leave infographics as ordinary photos.
In IV 2.0, <img> tags support the attribute href to make the image clickable. It must be used to preserve the link behind the image if it leads to some different page or content.
Image links are required only if they are meaningful. If the link opens the same image in a higher resolution, it must be removed. Exception: Infographics.
IV 2.0 supports a dedicated type for RelatedArticles. Related articles are relatively static individual links or blocks of articles which are thematically related to the current one. They don't have to be located on the same domain.
It is obligatory to format “Related articles” links using the new <related> tag and/or remove other “More” links, provided all these links can be extracted from the article without endangering essential information.
We designed the RelatedArticles block to deliver a better IV-reading experience to users. The IV engine automatically checks whether articles in the <related> block have an IV, you don't need to worry about this.
If pages have no IV, they will not be displayed. If this results in an empty block, it will not be displayed.
There are cases when you must not use RelatedArticles:
1. Keep but don’t format as Related
Never put essential links into
, they will be lost if the page they are leading to doesn’t have an IV.
2. Remove
It is sufficient to put links into <related>. You only need the <a> – the IV engine will handle the rest (title, description, etc.). Your IV may only have one block of related articles at the end of the page. If the source has several blocks, merge them together or choose which one to keep.
Headers
Only one header may be present for the block of related articles at the end of the page. We will not accept reports about missing headers on Related blocks (unless the header contains critical information).
Note that if a header for a related article is not reliably extractable from the body, you must not use
“Inline” blocks
You may leave “inline” related links in the middle the article. If you do, these <related> blocks must not have headers (unless the header contains critical information).
You may display the official channel of the website that published the article on the IV page by using the channel property:
Official Channel Link
This channel link is optional. We will not accept issue reports based on the absence or presence of a channel link, with one exception:
If the channel property is set, the channel it is pointing to must be the official channel. To be considered official, the channel must be labelled as such somewhere on the source website (doesn't have to be on the same page as the original article).
Some articles include a link to their source. This link could be inserted at the end of the article in the format via <a href="https://example.org">Website Name</a>. A word with a similar meaning could be used instead of 'via' for websites in other languages.
Author links are optional. If there's a clearly identifiable author and they have a page on the target website, use that one. In more ambiguous cases, use what the regular viewing user can see in the original article or omit the link altogether.
Tip: IV only supports one author URL per article. If there are several in the article, it's permissible to choose one or omit them altogether.
Sharing buttons and other interface-based links must be removed as per Rule 4.
Many articles include something like “check out our Facebook page” at the end of the text. Such links must be removed if they are placed in a reliably identifiable container.
To parse several pages into one IV, update your template to IV 2.1 (which skips canonical redirects by default) and use the inline function. Make sure to check in-app to see if your solution is working. The IV should open correctly when users share a link to any part of the article.
If pages can’t be safely assembled into one IV, navigation must be preserved. Please confirm that navigation is working and all further pages open correctly. If navigation can’t be preserved, the article must not generate an IV.
Never format links to the other parts of an article as related. This may break navigation if one part of the article fails to generate IV (since related articles without IVs are omitted in the block).
Pages that display unsupported content (e.g. an interactive map widget) must not generate IVs.
Important: We will accept issue reports requesting to generate IVs for pages with content previously deemed unsupported if you include a link to a template that fully supports the content in question. This does not apply to supporting content from popular widgets that are likely to get official support in the future, see the list below.
IV 2.0 includes support for **Tables**. IVs can now be generated for articles with simple tables. However, complex tables may not render through existing means, and must be tagged as @unsupported.
Important: We will accept issue reports requesting to generate IVs for pages with content previously deemed unsupported if you include a link to a template that fully supports the content in question.
<iframe>. If you do that, the IV page will not be generated due to unsupported content, but things will work out of the box if and when we support that widget.<video> or <audio> with the correct src attribute.If an article that is otherwise supported includes a video or an audio track that would cause it to become unsupported, it is acceptable to include a link to the video instead of unsupporting the article. If there’s no other content on the page, it must not generate an IV.
Some pages include unsupported widgets that are not essential for the understanding of the article. A local news site may show a weather forecast widget on their pages. A business newspaper may show a stock price ticker for the companies covered in the article. Some websites include “And what would you do?” polls at the end of some of their articles to increase user engagement.
Such non-essential widgets may be omitted in IV. Warning: Make sure that this dynamic auxiliary data doesn't get added to the static IV page.
Telegram is likely to support the following popular widgets in the future:
Supporting content from these widgets is optional since it will eventually become available through official means.
Subdomains that present content in a similar way to the higher-level domain must be supported.
If a subdomain looks like a separate website, supporting it is optional. We will accept issue reports if a template generates broken IV pages for any subdomain.
Note: We will add the necessary redirects so that Telegram apps will show IVs for articles on the main domain when users share links to the mobile version. It is not necessary to support pages from the mobile version.
Non-article pages are strictly optional, unless there’s interactive content – in which case they must not generate IVs. This includes Terms of Service, Privacy Policies, About sections, Contacts sections and special “Print” versions of articles.
Support for pages that only contain a single media item (photo, GIF, video, etc.) is required if:
If the single-media page contains unsupported media, it must not generate an IV. See 6.4.2 Unsupported Video and Audio content.
In all other cases, supporting single-media pages is optional.
Support for news articles from 2015 and earlier is optional. We won’t accept issue reports on news articles posted before 2016 if the template correctly handles articles published recently.
Quotes must be formatted to match their appearance in the source article, provided it is possible to identify them (and their type) in a reliable way. Line breaks in quotes must be preserved.
Quotes support <cite> tags. If a quote includes an author, it must be formatted accordingly (provided the author can be reliably identified in the source).
We will be updating this document with further clarifications as new issues arise.
Don’t miss the IV 2.1 update.
Checklist 2.2:
Expanded clarifications
site_name must include the name that users see on the main page of the website; cover photo must be used in preview if metadata is empty or contains site logo; template must generate proper description if metadata is unsuitableAdded NEW clarifications
Checklist 2.1
Checklist 2.0: Changes for the Second Instant View Contest
The Clarifications section has been rewritten to better organize the lore we've accumulated during and after the previous contest. These clarifications have been updated:
UPDATED 6.02, see guidelines!).Don't forget to check out what's new in IV 2.0 to know what your templates are now able to support.