Chats and channels may have a public username or a private invite link: private invite links may be further enhanced with per-user join requests.
contacts.resolvedPeer#7f077ad9 peer:Peer chats:Vector<Chat> users:Vector<User> = contacts.ResolvedPeer;
---functions---
contacts.resolveUsername#725afbbc flags:# username:string referer:flags.0?string = contacts.ResolvedPeer;
channels.joinChannel#24b524c5 channel:InputChannel = Updates;
channels.checkUsername#10e6bd2c channel:InputChannel username:string = Bool;
channels.updateUsername#3514b3de channel:InputChannel username:string = Bool;Only supergroups and channels may have a public usernames: normal groups must be migrated to a supergroup before they can be assigned a username, see the migration docs » for more info.
channels.updateUsername can be used to directly assign or change the public username of a supergroup or channel.
You can use channels.checkUsername before assigning the username to make sure that the specified username is valid and available.
channels.joinChannel can be used to join a supergroup or channel using peer information obtained using contacts.resolveUsername.
chatInviteExported#a22cbd96 flags:# revoked:flags.0?true permanent:flags.5?true request_needed:flags.6?true link:string admin_id:long date:int start_date:flags.4?int expire_date:flags.1?int usage_limit:flags.2?int usage:flags.3?int requested:flags.7?int subscription_expired:flags.10?int title:flags.8?string subscription_pricing:flags.9?StarsSubscriptionPricing = ExportedChatInvite;
messages.exportedChatInvites#bdc62dcc count:int invites:Vector<ExportedChatInvite> users:Vector<User> = messages.ExportedChatInvites;
messages.exportedChatInvite#1871be50 invite:ExportedChatInvite users:Vector<User> = messages.ExportedChatInvite;
messages.exportedChatInviteReplaced#222600ef invite:ExportedChatInvite new_invite:ExportedChatInvite users:Vector<User> = messages.ExportedChatInvite;
chatInviteImporter#8c5adfd9 flags:# requested:flags.0?true via_chatlist:flags.3?true user_id:long date:int about:flags.2?string approved_by:flags.1?long = ChatInviteImporter;
messages.chatInviteImporters#81b6b00a count:int importers:Vector<ChatInviteImporter> users:Vector<User> = messages.ChatInviteImporters;
chatAdminWithInvites#f2ecef23 admin_id:long invites_count:int revoked_invites_count:int = ChatAdminWithInvites;
messages.chatAdminsWithInvites#b69b72d7 admins:Vector<ChatAdminWithInvites> users:Vector<User> = messages.ChatAdminsWithInvites;
chatInviteAlready#5a686d7c chat:Chat = ChatInvite;
chatInvite#fe65389d flags:# channel:flags.0?true broadcast:flags.1?true public:flags.2?true megagroup:flags.3?true request_needed:flags.6?true verified:flags.7?true scam:flags.8?true fake:flags.9?true can_refulfill_subscription:flags.11?true title:string about:flags.5?string photo:Photo participants_count:int participants:flags.4?Vector<User> color:int subscription_pricing:flags.10?StarsSubscriptionPricing subscription_form_id:flags.12?long = ChatInvite;
chatInvitePeek#61695cb0 chat:Chat expires:int = ChatInvite;
---functions---
messages.exportChatInvite#a455de90 flags:# legacy_revoke_permanent:flags.2?true request_needed:flags.3?true peer:InputPeer expire_date:flags.0?int usage_limit:flags.1?int title:flags.4?string subscription_pricing:flags.5?StarsSubscriptionPricing = ExportedChatInvite;
messages.getExportedChatInvites#a2b5a3f6 flags:# revoked:flags.3?true peer:InputPeer admin_id:InputUser offset_date:flags.2?int offset_link:flags.2?string limit:int = messages.ExportedChatInvites;
messages.getExportedChatInvite#73746f5c peer:InputPeer link:string = messages.ExportedChatInvite;
messages.editExportedChatInvite#bdca2f75 flags:# revoked:flags.2?true peer:InputPeer link:string expire_date:flags.0?int usage_limit:flags.1?int request_needed:flags.3?Bool title:flags.4?string = messages.ExportedChatInvite;
messages.deleteRevokedExportedChatInvites#56987bd5 peer:InputPeer admin_id:InputUser = Bool;
messages.deleteExportedChatInvite#d464a42b peer:InputPeer link:string = Bool;
messages.getAdminsWithInvites#3920e6ef peer:InputPeer = messages.ChatAdminsWithInvites;
messages.getChatInviteImporters#df04dd4e flags:# requested:flags.0?true subscription_expired:flags.3?true peer:InputPeer link:flags.1?string q:flags.2?string offset_date:int offset_user:InputUser limit:int = messages.ChatInviteImporters;
messages.checkChatInvite#3eadb1bb hash:string = ChatInvite;
messages.importChatInvite#6c50051c hash:string = Updates;Private invite links can optionally have an expiration date, a usage limit, and can even be set to only allow users into the channel, supergroup or group upon explicit approval of an admin: see join requests » for more info.
Invite links match the following regex: @(?:t|telegram)\.(?:me|dog)/(joinchat/|\+)?([\w-]+)@i.
The first matching group can be passed to the hash parameter of messages.checkChatInvite to get info about the chat, and messages.importChatInvite to join the chat.
messages.checkChatInvite may return chatInvitePeek only for supergroups and channels, in which case the user may directly fetch chat messages using updates, messages.getHistory and channels.getMessages until the time indicated by the expires unixtime field.
Newly created groups, supergroups and channel already have a default invite link.
To generate a new one, use messages.exportChatInvite.
To get info about existing chat invites, optionally filtering only links created by a given admin, use messages.getExportedChatInvites.
messages.getExportedChatInvite can be used to obtain info about a specific invite link.
messages.editExportedChatInvite is used to edit or revoke existing invite links: revoked links cannot be used by users to join the group, but info about revoked links can still be fetched using messages.getExportedChatInvites with the revoked flag set.
Use messages.deleteExportedChatInvite to permanently remove an invite link, and messages.deleteRevokedExportedChatInvites to permanently remove a revoked invite link.
messages.getChatInviteImporters can be used to fetch info about users that joined using a specific invite link.
Some basic stats about the number of invite links generated by a given admin can be fetched using messages.getAdminsWithInvites.
starsSubscriptionPricing#05416d58 period:int amount:long = StarsSubscriptionPricing;
chatInvite#fe65389d flags:# channel:flags.0?true broadcast:flags.1?true public:flags.2?true megagroup:flags.3?true request_needed:flags.6?true verified:flags.7?true scam:flags.8?true fake:flags.9?true can_refulfill_subscription:flags.11?true title:string about:flags.5?string photo:Photo participants_count:int participants:flags.4?Vector<User> color:int subscription_pricing:flags.10?StarsSubscriptionPricing subscription_form_id:flags.12?long = ChatInvite;
inputInvoiceChatInviteSubscription#34e793f1 hash:string = InputInvoice;
payments.starsStatus#6c9ce8ed flags:# balance:StarsAmount subscriptions:flags.1?Vector<StarsSubscription> subscriptions_next_offset:flags.2?string subscriptions_missing_balance:flags.4?long history:flags.3?Vector<StarsTransaction> next_offset:flags.0?string chats:Vector<Chat> users:Vector<User> = payments.StarsStatus;
starsSubscription#2e6eab1a flags:# canceled:flags.0?true can_refulfill:flags.1?true missing_balance:flags.2?true bot_canceled:flags.7?true id:string peer:Peer until_date:int pricing:StarsSubscriptionPricing chat_invite_hash:flags.3?string title:flags.4?string photo:flags.5?WebDocument invoice_slug:flags.6?string = StarsSubscription;
---functions---
messages.exportChatInvite#a455de90 flags:# legacy_revoke_permanent:flags.2?true request_needed:flags.3?true peer:InputPeer expire_date:flags.0?int usage_limit:flags.1?int title:flags.4?string subscription_pricing:flags.5?StarsSubscriptionPricing = ExportedChatInvite;
messages.checkChatInvite#3eadb1bb hash:string = ChatInvite;
messages.importChatInvite#6c50051c hash:string = Updates;
payments.fulfillStarsSubscription#cc5bebb3 peer:InputPeer subscription_id:string = Bool;
payments.getStarsSubscriptions#032512c5 flags:# missing_balance:flags.0?true peer:InputPeer offset:string = payments.StarsStatus;
payments.changeStarsSubscription#c7770878 flags:# peer:InputPeer subscription_id:string canceled:flags.0?Bool = Bool;
payments.getStarsTransactions#69da4557 flags:# inbound:flags.0?true outbound:flags.1?true ascending:flags.2?true subscription_id:flags.3?string peer:InputPeer offset:string limit:int = payments.StarsStatus;
messages.getChatInviteImporters#df04dd4e flags:# requested:flags.0?true subscription_expired:flags.3?true peer:InputPeer link:flags.1?string q:flags.2?string offset_date:int offset_user:InputUser limit:int = messages.ChatInviteImporters;Channel administrators can create special invite links that allow joining a channel in exchange for a monthly payment in Telegram Stars.
To create such links, invoke messages.exportChatInvite passing a starsSubscriptionPricing constructor to subscription_pricing, passing in peer the private channel we wish to sell access to, and in amount the amount of Telegram Stars users should pay every period seconds to gain and maintain access to the channel.
Currently the only allowed subscription period is 30*24*60*60, i.e. the user will be automatically debited amount stars every month, and the maximum allowed amount is specified in the stars_subscription_amount_max config key ».
Users obtaining info about the invitation link using messages.checkChatInvite will obtain a chatInvite constructor with the subscription_pricing and subscription_form_id flags set.
To pay for the subscription, follow the usual payment flow », with the following variation: since subscriptions already have a pre-generated form contained in the subscription_form_id returned in chatInvite, the first two steps of the payment flow » (those used to generate a payment form) must be skipped, starting directly at the payments.sendStarsForm call in step 3 », passing to invoice an inputInvoiceChatInviteSubscription with the hash component of the invite link, and to form_id the chatInvite.subscription_form_id.
Once the payment is successfully completed, the user will be automatically added to the channel, without having to invoke messages.importChatInvite to join the private channel.
The end date of the current subscription period will be contained in channel.subscription_until_date.
The subscription will be automatically renewed at subscription_until_date, removing amount stars from the user's Star balance and pushing forward the subscription's subscription_until_date by period seconds.
If the user decides to leave the channel without cancelling the subscription (or before the end of the current cancelled subscription period), subsequent calls to messages.checkChatInvite will return a chatInvite with the can_refulfill_subscription flag set, indicating that they may re-join the channel using payments.fulfillStarsSubscription (passing inputPeerSelf to peer and the starsSubscription.id to subscription_id; alternatively, messages.importChatInvite may simply be used) without repeating the payment; the subscription_pricing will also be returned, but no subscription_form_id will be returned.
To obtain a list of all active and cancelled subscriptions invoke payments.getStarsSubscriptions, passing inputPeerSelf to peer: this will return a vector of starsSubscription constructors, containing info about each subscription.
To cancel an active subscription, invoke payments.changeStarsSubscription passing inputPeerSelf to peer, the starsSubscription.id to subscription_id and boolTrue to canceled; to resubscribe, invoke the same method passing boolFalse to canceled.
When we get close to the end of the subscription period of one or more active subscriptions, and the current Telegram Star balance is not high enough to autorenew at least one of them, the "STARS_SUBSCRIPTION_LOW_BALANCE" suggestion » will be activated: when the user clicks on the suggestion, the client should fetch and display the list of expiring subscriptions by invoking payments.getStarsSubscriptions, passing inputPeerSelf to peer and setting the missing_balance flag: the returned subscriptions may be renewed by filling up the current Telegram Star balance with at least payments.starsStatus.subscriptions_missing_balance stars.
payments.getStarsTransactions may be used to fetch only and all transactions for a specific subscription by populating the subscription_id flag.
Admins may also use messages.getChatInviteImporters with the subscription_expired flag set to fetch only and all users with an expired subscription.
Channel admins can also see the end date of the current subscription period for any user in channelParticipant.subscription_until_date.
channel#fe4478bd flags:# creator:flags.0?true left:flags.2?true broadcast:flags.5?true verified:flags.7?true megagroup:flags.8?true restricted:flags.9?true signatures:flags.11?true min:flags.12?true scam:flags.19?true has_link:flags.20?true has_geo:flags.21?true slowmode_enabled:flags.22?true call_active:flags.23?true call_not_empty:flags.24?true fake:flags.25?true gigagroup:flags.26?true noforwards:flags.27?true join_to_send:flags.28?true join_request:flags.29?true forum:flags.30?true flags2:# stories_hidden:flags2.1?true stories_hidden_min:flags2.2?true stories_unavailable:flags2.3?true signature_profiles:flags2.12?true id:long access_hash:flags.13?long title:string username:flags.6?string photo:ChatPhoto date:int restriction_reason:flags.9?Vector<RestrictionReason> admin_rights:flags.14?ChatAdminRights banned_rights:flags.15?ChatBannedRights default_banned_rights:flags.18?ChatBannedRights participants_count:flags.17?int usernames:flags2.0?Vector<Username> stories_max_id:flags2.4?int color:flags2.7?PeerColor profile_color:flags2.8?PeerColor emoji_status:flags2.9?EmojiStatus level:flags2.10?int subscription_until_date:flags2.11?int = Chat;
chatInvite#fe65389d flags:# channel:flags.0?true broadcast:flags.1?true public:flags.2?true megagroup:flags.3?true request_needed:flags.6?true verified:flags.7?true scam:flags.8?true fake:flags.9?true can_refulfill_subscription:flags.11?true title:string about:flags.5?string photo:Photo participants_count:int participants:flags.4?Vector<User> color:int subscription_pricing:flags.10?StarsSubscriptionPricing subscription_form_id:flags.12?long = ChatInvite;
updatePendingJoinRequests#7063c3db peer:Peer requests_pending:int recent_requesters:Vector<long> = Update;
updateBotChatInviteRequester#11dfa986 peer:Peer date:int user_id:long about:string invite:ExportedChatInvite qts:int = Update;
messages.chatInviteImporters#81b6b00a count:int importers:Vector<ChatInviteImporter> users:Vector<User> = messages.ChatInviteImporters;
peerSettings#acd66c5e flags:# report_spam:flags.0?true add_contact:flags.1?true block_contact:flags.2?true share_contact:flags.3?true need_contacts_exception:flags.4?true report_geo:flags.5?true autoarchived:flags.7?true invite_members:flags.8?true request_chat_broadcast:flags.10?true business_bot_paused:flags.11?true business_bot_can_reply:flags.12?true geo_distance:flags.6?int request_chat_title:flags.9?string request_chat_date:flags.9?int business_bot_id:flags.13?long business_bot_manage_url:flags.13?string = PeerSettings;
messageActionChatJoinedByRequest#ebbca3cb = MessageAction;
channelAdminLogEventActionParticipantJoinByRequest#afb6144a invite:ExportedChatInvite approved_by:long = ChannelAdminLogEventAction;
---functions---
messages.checkChatInvite#3eadb1bb hash:string = ChatInvite;
messages.importChatInvite#6c50051c hash:string = Updates;
messages.getChatInviteImporters#df04dd4e flags:# requested:flags.0?true subscription_expired:flags.3?true peer:InputPeer link:flags.1?string q:flags.2?string offset_date:int offset_user:InputUser limit:int = messages.ChatInviteImporters;
messages.hideChatJoinRequest#7fe7e815 flags:# approved:flags.0?true peer:InputPeer user_id:InputUser = Updates;
messages.hideAllChatJoinRequests#e085f4ea flags:# approved:flags.0?true peer:InputPeer link:flags.1?string = Updates;
channels.toggleJoinRequest#4c2985b6 channel:InputChannel enabled:Bool = Updates;If the request_needed flag is set when generating or editing an invite link, or if the appropriate option is toggled using channels.toggleJoinRequest, users importing the invite link using messages.importChatInvite will receive an INVITE_REQUEST_SENT RPC error, indicating that an join request was successfully sent to the chat admins.
Related supergroup information will also have the channel.join_request flag set accordingly.
Bot administrators will receive a updateBotChatInviteRequester update for each separate join request.
User administrators will receive an updatePendingJoinRequests, and should invoke messages.getChatInviteImporters with the requested flag set to obtain a list of users waiting to be admitted into the group.
Administrators can then use messages.hideChatJoinRequest to approve or dismiss a join request, and messages.hideAllChatJoinRequests to approve or dismiss in bulk multiple join requests.
Administrators can also choose to send a message to the user before admitting them into the group: in this case, graphical clients on the user side should display a message on the dialog bar of the chat with the admin, indicating that the chat was initiated by the admin of a chat/channel they have recently requested to join, see the action bar documentation » for more info.
missingInvitee#628c9224 flags:# premium_would_allow_invite:flags.0?true premium_required_for_pm:flags.1?true user_id:long = MissingInvitee;
messages.invitedUsers#7f5defa6 updates:Updates missing_invitees:Vector<MissingInvitee> = messages.InvitedUsers;
---functions---
messages.addChatUser#cbc6d107 chat_id:long user_id:InputUser fwd_limit:int = messages.InvitedUsers;
messages.createChat#92ceddd4 flags:# users:Vector<InputUser> title:string ttl_period:flags.0?int = messages.InvitedUsers;
channels.inviteToChannel#c9e33d54 channel:InputChannel users:Vector<InputUser> = messages.InvitedUsers;Users may also be directly invited to groups and channels during their creation (basic groups via messages.createChat) or afterwards (basic groups via messages.addChatUser, supergroups and channels via channels.inviteToChannel).
The methods will return a messages.invitedUsers constructor, containing a list of updates about successfully invited users (and eventually info about the created group), and a list of missingInvitee, with a list of users that could not be invited for some reason.
Specifically:
premium_would_allow_invite flag is set, we could not add the user only because the current account needs to purchase a Telegram Premium subscription to complete the operation. premium_required_for_pm flag is set, we could not add the user because of their privacy settings, and additionally, the current account needs to purchase a Telegram Premium subscription to directly share an invite link with the user via a private message.