Wallpapers

Telegram apps support generating, sharing and synchronizing chat backgrounds.

Wallpapers must be rendered according to the instructions contained in the wallpaper constructors.

Wallpaper types

There are three main wallpaper types:

• Image wallpapers
• Pattern wallpapers
• Fill wallpapers

Fill and pattern wallpapers are generated using one of three fill types.

Image wallpapers

wallPaper#a437c3ed id:long flags:# creator:flags.0?true default:flags.1?true pattern:flags.3?true dark:flags.4?true access_hash:long slug:string document:Document settings:flags.2?WallPaperSettings = WallPaper;

wallPaperSettings#1dc1bca4 flags:# blur:flags.1?true motion:flags.2?true background_color:flags.0?int second_background_color:flags.4?int third_background_color:flags.5?int fourth_background_color:flags.6?int intensity:flags.3?int rotation:flags.4?int = WallPaperSettings;

Image wallpapers are wallpapers described by a wallPaper constructor, containing a JPEG image in the document field.
The settings field describes the transforms that should be applied to the image if the corresponding flags are set:

• settings.blur: The image should be downscaled to fit in 450x450 square and then box-blurred with radius 12.
• settings.motion: The image needs to be slightly moved when device is tilted, allowing for a parallax effect.

All other settings flags should be ignored.

Pattern wallpapers

wallPaper#a437c3ed id:long flags:# creator:flags.0?true default:flags.1?true pattern:flags.3?true dark:flags.4?true access_hash:long slug:string document:Document settings:flags.2?WallPaperSettings = WallPaper;

wallPaperSettings#1dc1bca4 flags:# blur:flags.1?true motion:flags.2?true background_color:flags.0?int second_background_color:flags.4?int third_background_color:flags.5?int fourth_background_color:flags.6?int intensity:flags.3?int rotation:flags.4?int = WallPaperSettings;

Pattern wallpapers are wallpapers described by a wallPaper constructor with the pattern flag set, combining the color fill specified by the settings field with the PNG or TGV (gzipped subset of SVG with MIME type "application/x-tgwallpattern") pattern image contained in the document field.

The pattern image should be completely transparent, except for the pattern itself which should be shades of black.

The following flags in the settings field describe how should the pattern be combined with the color fill:

• settings.intensity: A value ranging from -100 to 100.
  • Values from 0 to 100 mean that the pattern should be overlaid on top of the color fill with the specified intensity (@ 100 the black pattern is fully visible on the background fill, @ 0 only the background fill is visible).
  • Values from -1 to -100 mean that the pattern should be inverted (black background, transparent pattern) before overlaying on top of the color fill with the specified intensity (@ -100 the filled pattern is fully visible on a black background, @ -1 only black is visible).
• settings.motion: The pattern needs to be slightly moved on top of the background when device is tilted, allowing for a parallax effect.

Fill wallpapers

wallPaperNoFile#e0804116 id:long flags:# default:flags.1?true dark:flags.4?true settings:flags.2?WallPaperSettings = WallPaper;

Fill wallpapers are simple wallpapers described by the wallPaperNoFile constructor, containing only the fill specified by the settings field.

Fill types

Fill and pattern wallpapers are generated using one of three fill types:

• Solid fill
• Gradient fill
• Freeform gradient fill

Solid fill

wallPaperSettings#1dc1bca4 flags:# blur:flags.1?true motion:flags.2?true background_color:flags.0?int second_background_color:flags.4?int third_background_color:flags.5?int fourth_background_color:flags.6?int intensity:flags.3?int rotation:flags.4?int = WallPaperSettings;

If out of the *_background_color flags only background_color is set, the fill is made of just the specified RGB-24 color.

Gradient fill

wallPaperSettings#1dc1bca4 flags:# blur:flags.1?true motion:flags.2?true background_color:flags.0?int second_background_color:flags.4?int third_background_color:flags.5?int fourth_background_color:flags.6?int intensity:flags.3?int rotation:flags.4?int = WallPaperSettings;

If out of the *_background_color flags only background_color and second_background_color are set, the fill is made of a top-bottom (background-second_background) gradient of the specified RGB-24 colors.
If set, rotation indicates clockwise rotation angle of the gradient, in degrees; 0-359. Must be always divisible by 45, default to 0 if not set.

Freeform gradient fill

wallPaperSettings#1dc1bca4 flags:# blur:flags.1?true motion:flags.2?true background_color:flags.0?int second_background_color:flags.4?int third_background_color:flags.5?int fourth_background_color:flags.6?int intensity:flags.3?int rotation:flags.4?int = WallPaperSettings;

If the background_color, second_background_color, third_background_color and optionally fourth_background_color flags are set, the fill is made of a freeform gradient of the specified 3 or 4 RGB-24 colors.

Wallpaper API

Uploading wallpapers

wallPaperSettings#1dc1bca4 flags:# blur:flags.1?true motion:flags.2?true background_color:flags.0?int second_background_color:flags.4?int third_background_color:flags.5?int fourth_background_color:flags.6?int intensity:flags.3?int rotation:flags.4?int = WallPaperSettings;

wallPaper#a437c3ed id:long flags:# creator:flags.0?true default:flags.1?true pattern:flags.3?true dark:flags.4?true access_hash:long slug:string document:Document settings:flags.2?WallPaperSettings = WallPaper;

---functions---

account.uploadWallPaper#e39a8f03 flags:# for_chat:flags.0?true file:InputFile mime_type:string settings:WallPaperSettings = WallPaper;

account.uploadWallPaper is used to upload image and pattern wallpapers. The for_chat flag must be set when uploading wallpapers to be used with messages.setChatWallPaper.
Fill wallpapers don't require uploading since they have no associated file, and a wallPaper constructor can directly be generated client-side, specifying id=0.

Wallpapers can then be shared using a wallpaper deep link », and/or installed as specified here (image and pattern wallpapers only) ».

Installing wallpapers

inputWallPaper#e630b979 id:long access_hash:long = InputWallPaper;
inputWallPaperSlug#72091c80 slug:string = InputWallPaper;

wallPaper#a437c3ed id:long flags:# creator:flags.0?true default:flags.1?true pattern:flags.3?true dark:flags.4?true access_hash:long slug:string document:Document settings:flags.2?WallPaperSettings = WallPaper;

wallPaperSettings#1dc1bca4 flags:# blur:flags.1?true motion:flags.2?true background_color:flags.0?int second_background_color:flags.4?int third_background_color:flags.5?int fourth_background_color:flags.6?int intensity:flags.3?int rotation:flags.4?int = WallPaperSettings;

account.wallPapersNotModified#1c199183 = account.WallPapers;
account.wallPapers#cdc3858c hash:long wallpapers:Vector<WallPaper> = account.WallPapers;

messageActionSetChatWallPaper#bc44a927 wallpaper:WallPaper = MessageAction;
messageActionSetSameChatWallPaper#c0787d6d wallpaper:WallPaper = MessageAction;

---functions---

account.getWallPaper#fc8ddbea wallpaper:InputWallPaper = WallPaper;
account.getMultiWallPapers#65ad71dc wallpapers:Vector<InputWallPaper> = Vector<WallPaper>;

account.saveWallPaper#6c5a5b37 wallpaper:InputWallPaper unsave:Bool settings:WallPaperSettings = Bool;
account.installWallPaper#feed5769 wallpaper:InputWallPaper settings:WallPaperSettings = Bool;
account.getWallPapers#7967d36 hash:long = account.WallPapers;
account.resetWallPapers#bb3b9804 = Bool;

messages.setChatWallPaper#8ffacae1 flags:# peer:InputPeer wallpaper:flags.0?InputWallPaper settings:flags.2?WallPaperSettings id:flags.1?int = Updates;

Once you've uploaded your wallpaper or received a wallpaper deep link, it can be installed as follows.

Note that fill wallpapers cannot be globally installed using account.installWallPaper or account.saveWallPaper, clients should install and keep track of them only locally, without synchronizing the wallpaper list or signaling installations.

The API keeps a list of wallpapers that the user can set as chat background, including some preinstalled ones.
To fetch the list use account.getWallPapers.
To save a wallpaper to the list use account.saveWallPaper with unsave=false.
To remove a wallpaper (including preinstalled wallpapers) from the list use account.saveWallPaper with unsave=true.
To restore the default list, removing all installed wallpapers and reinstalling previously removed preinstalled wallpapers use account.resetWallPapers.

When a client sets a wallpaper as the default chat background, call account.installWallPaper to signal this installation to the server.
Note that calling this method will also automatically save the wallpaper, if it's not present in the saved wallpapers list.

In all cases where an InputWallPaper constructor is required, pass:

• inputWallPaperSlug when working with wallpaper deep links.
• inputWallPaper otherwise, using the ID and access hash fields of a full wallPaper.
  As mentioned earlier, fill wallpapers can't be saved to the server using account.installWallPaper or account.saveWallPaper: an inputWallPaperNoFile is available for fill wallpapers but can only be used when working with themes » or when using messages.setChatWallPaper.

Wallpapers can also be installed in a specific chat, by using messages.setChatWallPaper: this will emit a messageActionSetChatWallPaper service message, displaying the wallpaper in the UI along with an invitation for the other user to apply the same wallpaper.

If the other user decides to apply the same wallpaper to the chat, messages.setChatWallPaper should be invoked passing the wallpaper settings received in the messageActionSetChatWallPaper service message (or some different settings, if the user customized them before applying the wallpaper), along with the id of the messageActionSetChatWallPaper service message, without the wallpaper: this way, the action will emit a different messageActionSetSameChatWallPaper, which should be displayed in the UI as a simple acknowledgment service message, without the full wallpaper and without an invitation for the other user to apply it (since both participants already just did that).

Note that in order to pass image or pattern wallpapers to messages.setChatWallPaper, the for_chat flag must be set when uploading them with account.uploadWallPaper.

Also note that unlike account.installWallPaper or account.saveWallPaper, messages.setChatWallPaper accepts fill wallpapers as well.