Folders

Telegram allows placing chats into folders, based on their type, mute status, or other custom criteria, thanks to folder blacklists and whitelists.
In the API, folders are called "dialog filters"; in the UI, they are typically represented as tabs.

Schema:

dialogFilter#7438f7e8 flags:# contacts:flags.0?true non_contacts:flags.1?true groups:flags.2?true broadcasts:flags.3?true bots:flags.4?true exclude_muted:flags.11?true exclude_read:flags.12?true exclude_archived:flags.13?true id:int title:string emoticon:flags.25?string pinned_peers:Vector<InputPeer> include_peers:Vector<InputPeer> exclude_peers:Vector<InputPeer> = DialogFilter;

dialogFilterSuggested#77744d4a filter:DialogFilter description:string = DialogFilterSuggested;

updateDialogFilter#26ffde7d flags:# id:int filter:flags.0?DialogFilter = Update;
updateDialogFilterOrder#a5d72105 order:Vector<int> = Update;
updateDialogFilters#3504914f = Update;

---functions---

messages.getDialogFilters#f19ed96d = Vector<DialogFilter>;
messages.getSuggestedDialogFilters#a29cd42c = Vector<DialogFilterSuggested>;
messages.updateDialogFilter#1ad4a04a flags:# id:int filter:flags.0?DialogFilter = Bool;
messages.updateDialogFiltersOrder#c563c1e4 order:Vector<int> = Bool;

help.getAppConfig#98914110 = JSONValue;

Folders

On startup, clients call:

• messages.getDialogFilters to fetch a list of previously configured folders.
• messages.getSuggestedDialogFilters to fetch a list of suggested folder combinations.
• help.getAppConfig to fetch app-specific configuration parameters.

The boolean under the dialog_filters_tooltip JSON key in the result of help.getAppConfig can be used to determine whether a folder tooltip should be presented to the user right away.
The UI should then show a list of suggested folder combinations.

Once configuration is finished, apps call messages.updateDialogFilter to create or update existing folders.
As per the dialogFilter constructor, folders have multiple flags that can be combined to determine which chats should be included in (or excluded from) the folder.
Folders can also have unlimited pinned chats, as determined by the pinned_peers field.

To reorder existing folders, messages.updateDialogFiltersOrder should be used with the IDs of the various dialog filters.

To delete folders, use messages.updateDialogFilter without populating the filter flag field.

Clients can receive updateDialogFilter, updateDialogFilterOrder updates with new filter information, generated by other clients when modifying folder info.
Clients can also receive updateDialogFilters, in which case folder info should be refetched manually using messages.getDialogFilters.

Peer folders

The API also has another method for identifying groups of peers, typically used only by archived chats.

Schema:

inputDialogPeer#fcaafeb7 peer:InputPeer = InputDialogPeer;
inputDialogPeerFolder#64600527 folder_id:int = InputDialogPeer;

dialogPeer#e56dbf05 peer:Peer = DialogPeer;
dialogPeerFolder#514519e2 folder_id:int = DialogPeer;

updateFolderPeers#19360dc0 folder_peers:Vector<FolderPeer> pts:int pts_count:int = Update;

updates#74ae4240 updates:Vector<Update> users:Vector<User> chats:Vector<Chat> date:int seq:int = Updates;

---functions---

folders.editPeerFolders#6847d0ab folder_peers:Vector<InputFolderPeer> = Updates;
folders.deleteFolder#1c295881 folder_id:int = Updates;

API peer folders are typically used only by archived chats, and are really handy for distinguishing groups of peers, since most peer-related constructors (updates, chat info) will contain the folder_id assigned the the specified chat.

In Telegram apps, API peer folders are used only to implement the chat archive, identified by folder_id 1; all other peers are in folder_id 0 by default; no other folder_id is allowed at the moment.

• folders.editPeerFolders can be used to add and remove peers from peer folders.
• folders.deleteFolder can be used to delete peer folders, moving all peers previously present in that folder to the default 0 folder.

Both methods return an updates constructor, containing a single updateFolderPeers with the new folder_id of moved peers.
Clients can also receive updateFolderPeers as a normal update, generated by other clients when modifying peer folders.