Member Management

Part of the API Reference. Reached via client.members.

This is the core of what ptgc adds over the Bot API: acting as a user account, including in ways bots often can’t (e.g. inviting members to a public channel without them clicking a link).

chatId throughout this class is the same ID you’d get from Chats.listDialogs or [list] — ptgc figures out on its own whether it’s a basic group or a supergroup/channel and calls the right raw method. You do need to have seen the chat at least once this session (dialogs, a search, a previous call) so its access hash is cached — see Peer Cache.

`list`

Future<List<Participant>> list(
  int chatId, {
  ParticipantFilter filter = ParticipantFilter.recent,
  String query = '',
  int offset = 0,
  int limit = 200,
}) async {

Lists members of chatId.

filter narrows the results for supergroups/channels (ignored for basic groups, which always return everyone). query is required by ParticipantFilter.search and optional for ParticipantFilter.banned/ParticipantFilter.restricted (narrows by name there too). offset/limit page through large lists — Telegram caps limit at 200 per call.

`get`

Future<Participant?> get(int chatId, int userId) async {

Looks up a single member’s status. Returns null if userId isn’t a member of chatId.

`ban`

Future<void> ban(int chatId, int userId, {DateTime? until}) async {

Fully bans userId from chatId — they’re removed immediately and can’t rejoin, even via invite link, until [unban]ned. Pass until for a temporary ban; omit it for permanent.

If you want them removable-but-rejoinable instead (a “kick” in the usual sense), use [kick].

`kick`

Future<void> kick(int chatId, int userId) async {

Removes userId from chatId without a lasting ban — they can rejoin later (e.g. via invite link). This is what most people mean by “kick”.

Supergroups/channels have no separate “kick” RPC, so this bans and immediately unbans — Telegram’s own idiom for the same effect.

`unban`

Future<void> unban(int chatId, int userId) async {

Lifts a [ban]/[restrict] on userId in chatId. No-op for basic groups, which have no persistent banned state — removing a member there ([ban]) already just ends their membership.

`restrict`

Future<void> restrict(int chatId, int userId, BannedRights rights) async {

Applies specific restrictions to userId in chatId (e.g. mute them, or block them from sending media) without removing them from the chat. Supergroups/channels only — see Permissions & Rights for what you can restrict. Throws StateError on a basic group, which only supports full ban()/kick(), not partial restrictions.

`promote`

Future<void> promote(int chatId, int userId, AdminRights rights,
    {String rank = ''}) async {

Grants userId admin rights in chatId. rank is an optional custom title shown under their name (e.g. 'Moderator').

You need AdminRights.addAdmins yourself to do this. Basic groups only support an all-or-nothing admin flag — rights is ignored there beyond “grant admin”.

`demote`

Future<void> demote(int chatId, int userId) async {

Revokes userId’s admin rights in chatId, back to a regular member.

`invite`

Future<List<int>> invite(int chatId, List<int> userIds) async {

Adds userIds to chatId directly — no invite link needed, as long as your account has permission (public channels/supergroups allow this for anyone; private ones need you to already be a member with invite rights, and some users’ privacy settings will still block it).

Returns the subset of userIds that couldn’t be added (e.g. due to privacy settings) — an empty list means everyone was added.

Types

`Participant`

Returned by [list]/[get].

Field	Type	Meaning
`user`	`PtgcUser`
`role`	`ParticipantRole`	See below.
`adminRights`	`AdminRights?`	Only set when `role` is `admin` or `creator`.
`bannedRights`	`BannedRights?`	Only set when `role` is `restricted` or `banned`.
`rank`	`String?`	A custom admin title, if the chat owner set one.
`invitedBy`	`int?`	Who invited this member, if known.
`joinedAt`	`DateTime?`	When this member joined, if known.

`ParticipantRole`

creator, admin, member, restricted (has active restrictions but hasn’t left/isn’t fully banned), banned, left.

`ParticipantFilter`

Which subset of participants to fetch with [list]. Mirrors Telegram’s channels.getParticipants filters; only meaningful for supergroups/channels — basic groups always return every member.

recent (the default — the only filter that works without search text), admins, banned, restricted, bots, search (use alongside list’s query parameter).