<metaproperty="description"content="Telegram allows placing chats into folders, based on their type, mute status, or other custom criteria, thanks to folder blacklists and whitelists.">
<metaproperty="og:title"content="Folders">
<metaproperty="og:image"content="">
<metaproperty="og:description"content="Telegram allows placing chats into folders, based on their type, mute status, or other custom criteria, thanks to folder blacklists and whitelists.">
<p>Telegram allows placing chats into folders, based on their type, mute status, or other custom criteria, thanks to folder blacklists and whitelists: these folders may also be shared with other users. </p>
<p>The boolean under the <ahref="/api/config#dialog-filters-tooltip"><code>dialog_filters_tooltip</code> JSON key</a> in the result of <ahref="/method/help.getAppConfig">help.getAppConfig</a> can be used to determine whether a folder tooltip should be presented to the user right away.<br>
The UI should then show a list of suggested folder combinations. </p>
<p>Once configuration is finished, apps call <ahref="/method/messages.updateDialogFilter">messages.updateDialogFilter</a> to create or update existing folders.<br>
As per the <ahref="/constructor/dialogFilter">dialogFilter</a>/<ahref="/constructor/dialogFilterChatlist">dialogFilterChatlist</a> constructors, folders have multiple flags that can be combined to determine which chats should be included in (or excluded from) the folder, which emoji to use as icon for the folder and its name.<br>
Folders can also have up to <code>dialogs_folder_pinned_limit_*</code> pinned chats, as determined by the <ahref="/api/config#client-configuration">client configuration</a>.</p>
<p><ahref="/constructor/dialogFilterChatlist">dialogFilterChatlist</a> constructors are used to represent imported <ahref="#shared-folders">shareable folders</a>. </p>
<p>To reorder existing folders, <ahref="/method/messages.updateDialogFiltersOrder">messages.updateDialogFiltersOrder</a> should be used with the IDs of the various dialog filters.</p>
<p><ahref="/api/premium">Premium</a> users also have access to a <ahref="/constructor/dialogFilterDefault">dialogFilterDefault</a> constructor, used only when reordering folders to indicate the default (all chats) folder. </p>
<p>To delete folders, use <ahref="/method/messages.updateDialogFilter">messages.updateDialogFilter</a> without populating the <code>filter</code> flag field. </p>
<p>Clients can receive <ahref="/constructor/updateDialogFilter">updateDialogFilter</a>, <ahref="/constructor/updateDialogFilterOrder">updateDialogFilterOrder</a> updates with new filter information, generated by other clients when modifying folder info.<br>
Clients can also receive <ahref="/constructor/updateDialogFilters">updateDialogFilters</a>, in which case folder info should be refetched manually using <ahref="/method/messages.getDialogFilters">messages.getDialogFilters</a>.</p>
<p>Folder tags may be enabled or disabled for all <ahref="#folders">folders</a> using the <ahref="/method/messages.toggleDialogFilterTags">messages.toggleDialogFilterTags</a> method (<ahref="/api/business">Business</a> users only). </p>
<p>If the new value of the toggle is different, the method will emit an <ahref="/constructor/updateDialogFilters">updateDialogFilters</a> to all other currently-logged in sessions, which should trigger a call to <ahref="/method/messages.toggleDialogFilterTags">messages.toggleDialogFilterTags</a> to load the new value of the toggle, in <ahref="/constructor/messages.dialogFilters">messages.dialogFilters</a>.<code>tags_enabled</code>. </p>
<p>If folder tags are enabled, clients should add folder tags (one for each folder the dialog entry is a part of, except for the "All chats" folder represented by <ahref="/constructor/dialogFilterDefault">dialogFilterDefault</a> and tags with <code>color=-1</code>) to all dialog entries, under the preview of the latest message. </p>
<p>These folder tags should contain the name of the folder, and should be colored with the <code>color</code> specified in the dialog folder entry.<br>
The color is an integer ranging from -1 to 6; if -1, the tag must not be shown in the dialog list; use red, orange, violet, green, cyan, blue, pink for indexes 0 to 6 (i.e. the same colors used for randomized fallback <ahref="/api/colors">message accent colors</a>).</p>
<p>The tag <code>color</code> may only be changed if the user has a <ahref="/api/premium">Premium</a> subscription and tags are enabled. </p>
<p>Folders may be shared using <ahref="/api/links#chat-folder-links">chat folder deep links</a>.<br>
These links are generated by invoking <ahref="/method/chatlists.exportChatlistInvite">chatlists.exportChatlistInvite</a>, passing the ID of the folder that should be exported, along with a list of <code>peers</code> that should be included in the shared folder.<br>
Only channels and groups/supergroups may be specified in the <code>peers</code> array; these channels and groups must be public, or the user must have permission to manage invite links. Basic groups will automatically be <ahref="/api/channel#migration">converted to supergroups</a> when invoking the method.<br>
An optional name for the shared link may also be specified using <code>title</code>. </p>
<p>Use <ahref="/method/chatlists.getExportedInvites">chatlists.getExportedInvites</a> to list all links generated for a folder, use <ahref="/method/chatlists.editExportedInvite">chatlists.editExportedInvite</a> to edit the title or list of <code>peers</code> of a specific link and <ahref="/method/chatlists.deleteExportedInvite">chatlists.deleteExportedInvite</a> to revoke an exported link, preventing new users from importing it. </p>
<p>The maximum number of per-folder invites that can be created by <ahref="/api/premium">Premium</a>/non-<ahref="/api/premium">Premium</a> users is specified by the <code>chatlist_invites_limit_default</code>/<code>chatlist_invites_limit_premium</code><ahref="/api/config#chatlist-invites-limit-default">client configuration parameters»</a>. </p>
<p>Use <ahref="/method/chatlists.checkChatlistInvite">chatlists.checkChatlistInvite</a> to obtain information about a chat folder deep link before importing it with <ahref="/method/chatlists.joinChatlistInvite">chatlists.joinChatlistInvite</a>, specifying in <code>peers</code> which channels and groups to join (excluding inaccessible channels/supergroups, i.e. the user may not join a supergroup/channel where they were banned, corresponding to a <ahref="/constructor/channelForbidden">channelForbidden</a> constructor).<br>
If the user can't join any of the <code>peers</code> of a folder, the folder can't be imported.</p>
<p>The maximum number of shareable folders that a <ahref="/api/premium">Premium</a>/non-<ahref="/api/premium">Premium</a> user may join is specified by the <code>chatlists_joined_limit_default</code>/<code>chatlists_joined_limit_premium</code><ahref="/api/config#chatlists-joined-limit-default">client configuration parameters»</a>. </p>
<p>Users that import a folder should retrieve additions made to the peer list by invoking <ahref="/method/chatlists.getChatlistUpdates">chatlists.getChatlistUpdates</a> at most every <code>chatlist_update_period</code> seconds (a <ahref="/api/config#chatlist-update-period">client configuration parameter»</a>).<br>
If the returned <code>missing_peers</code> list is non-empty, the client should present it to the user, who may choose to join all or a subset of them (excluding inaccessible channels/supergroups), passing them to the <code>peers</code> parameter of <ahref="/method/chatlists.joinChatlistUpdates">chatlists.joinChatlistUpdates</a>.<br>
If after excluding inaccessible peers and peers deselected by the user the <code>peers</code> list is empty, invoke <ahref="/method/chatlists.hideChatlistUpdates">chatlists.hideChatlistUpdates</a> instead of <ahref="/method/chatlists.joinChatlistUpdates">chatlists.joinChatlistUpdates</a>.</p>
<p>When removing an imported folder, the list of included peers should be presented to the user prior to deletion, with the peers listed in <ahref="/method/chatlists.getLeaveChatlistSuggestions">chatlists.getLeaveChatlistSuggestions</a> already pre-marked for deletion: the user may then choose to delete or keep some or all of the groups and channels of the folder when invoking <ahref="/method/chatlists.leaveChatlist">chatlists.leaveChatlist</a> to delete the folder, specifying in <code>peers</code> the list of channels and groups from the folder that should also be removed.</p>
<p>API peer folders are typically used only by <ahref="https://telegram.org/blog/archive-and-new-design">archived chats</a>, and are really handy for distinguishing groups of peers, since most peer-related constructors (updates, chat info) will contain the <code>folder_id</code> assigned the specified chat. </p>
<p>In Telegram apps, API peer folders are used only to implement the chat archive, identified by <code>folder_id</code><code>1</code>; all other peers are in <code>folder_id</code><code>0</code> by default; no other <code>folder_id</code> is allowed at the moment.</p>
<ul>
<li><ahref="/method/folders.editPeerFolders">folders.editPeerFolders</a> can be used to add and remove peers from peer folders.</li>
</ul>
<p>Both methods return an <ahref="/constructor/updates">updates</a> constructor, containing a single <ahref="/constructor/updateFolderPeers">updateFolderPeers</a> with the new <code>folder_id</code> of moved peers.<br>
Clients can also receive <ahref="/constructor/updateFolderPeers">updateFolderPeers</a> as a normal <ahref="/api/updates">update</a>, generated by other clients when modifying peer folders.</p>
<p>Clients can then use <ahref="/type/InputDialogPeer">InputDialogPeer</a> to refer either to a specific chat, or to all chats in a peer folder: the server will return a <ahref="/type/DialogPeer">DialogPeer</a> in certain constructors for the same purpose.</p></div>
