Working with Chats and Channels

Note

These examples assume you have read Accessing the Full API.

Joining a chat or channel

Note that Chat are normal groups, and Channel are a special form of Chat, which can also be super-groups if their megagroup member is True.

Joining a public channel

Once you have the entity of the channel you want to join to, you can make use of the JoinChannelRequest to join such channel:

from telethon.tl.functions.channels import JoinChannelRequest
client(JoinChannelRequest(channel))

# In the same way, you can also leave such channel
from telethon.tl.functions.channels import LeaveChannelRequest
client(LeaveChannelRequest(input_channel))

For more on channels, check the channels namespace.

Joining a private chat or channel

If all you have is a link like this one: https://t.me/joinchat/AAAAAFFszQPyPEZ7wgxLtd, you already have enough information to join! The part after the https://t.me/joinchat/, this is, AAAAAFFszQPyPEZ7wgxLtd on this example, is the hash of the chat or channel. Now you can use ImportChatInviteRequest as follows:

from telethon.tl.functions.messages import ImportChatInviteRequest
updates = client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg'))

Adding someone else to such chat or channel

If you don’t want to add yourself, maybe because you’re already in, you can always add someone else with the AddChatUserRequest, which use is very straightforward, or InviteToChannelRequest for channels:

# For normal chats
from telethon.tl.functions.messages import AddChatUserRequest

# Note that ``user_to_add`` is NOT the name of the parameter.
# It's the user you want to add (``user_id=user_to_add``).
client(AddChatUserRequest(
    chat_id,
    user_to_add,
    fwd_limit=10  # Allow the user to see the 10 last messages
))

# For channels (which includes megagroups)
from telethon.tl.functions.channels import InviteToChannelRequest

client(InviteToChannelRequest(
    channel,
    [users_to_add]
))

Retrieving all chat members (channels too)

You can use client.get_participants to retrieve the participants (click it to see the relevant parameters). Most of the time you will just need client.get_participants(entity).

This is what said method is doing behind the scenes as an example.

In order to get all the members from a mega-group or channel, you need to use GetParticipantsRequest. As we can see it needs an InputChannel, (passing the mega-group or channel you’re going to use will work), and a mandatory ChannelParticipantsFilter. The closest thing to “no filter” is to simply use ChannelParticipantsSearch with an empty 'q' string.

If we want to get all the members, we need to use a moving offset and a fixed limit:

from telethon.tl.functions.channels import GetParticipantsRequest
from telethon.tl.types import ChannelParticipantsSearch
from time import sleep

offset = 0
limit = 100
all_participants = []

while True:
    participants = client(GetParticipantsRequest(
        channel, ChannelParticipantsSearch(''), offset, limit,
        hash=0
    ))
    if not participants.users:
        break
    all_participants.extend(participants.users)
    offset += len(participants.users)

Note

If you need more than 10,000 members from a group you should use the mentioned client.get_participants(..., aggressive=True). It will do some tricks behind the scenes to get as many entities as possible. Refer to issue 573 for more on this.

Note that GetParticipantsRequest returns ChannelParticipants, which may have more information you need (like the role of the participants, total count of members, etc.)

Recent Actions

“Recent actions” is simply the name official applications have given to the “admin log”. Simply use GetAdminLogRequest for that, and you’ll get AdminLogResults.events in return which in turn has the final .action.

Admin Permissions

Giving or revoking admin permissions can be done with the EditAdminRequest:

from telethon.tl.functions.channels import EditAdminRequest
from telethon.tl.types import ChannelAdminRights

# You need both the channel and who to grant permissions
# They can either be channel/user or input channel/input user.
#
# ChannelAdminRights is a list of granted permissions.
# Set to True those you want to give.
rights = ChannelAdminRights(
    post_messages=None,
    add_admins=None,
    invite_users=None,
    change_info=True,
    ban_users=None,
    delete_messages=True,
    pin_messages=True,
    invite_link=None,
    edit_messages=None
)
# Equivalent to:
#     rights = ChannelAdminRights(
#         change_info=True,
#         delete_messages=True,
#         pin_messages=True
#     )

# Once you have a ChannelAdminRights, invoke it
client(EditAdminRequest(channel, user, rights))

# User will now be able to change group info, delete other people's
# messages and pin messages.

Note

Thanks to @Kyle2142 for pointing out that you cannot set all parameters to True to give a user full permissions, as not all permissions are related to both broadcast channels/megagroups.

E.g. trying to set post_messages=True in a megagroup will raise an error. It is recommended to always use keyword arguments, and to set only the permissions the user needs. If you don’t need to change a permission, it can be omitted (full list here).

Restricting Users

Similar to how you give or revoke admin permissions, you can edit the banned rights of an user through EditAdminRequest and its parameter ChannelBannedRights:

from telethon.tl.functions.channels import EditBannedRequest
from telethon.tl.types import ChannelBannedRights

from datetime import datetime, timedelta

# Restricting an user for 7 days, only allowing view/send messages.
#
# Note that it's "reversed". You must set to ``True`` the permissions
# you want to REMOVE, and leave as ``None`` those you want to KEEP.
rights = ChannelBannedRights(
    until_date=datetime.now() + timedelta(days=7),
    view_messages=None,
    send_messages=None,
    send_media=True,
    send_stickers=True,
    send_gifs=True,
    send_games=True,
    send_inline=True,
    embed_links=True
)

# The above is equivalent to
rights = ChannelBannedRights(
    until_date=datetime.now() + timedelta(days=7),
    send_media=True,
    send_stickers=True,
    send_gifs=True,
    send_games=True,
    send_inline=True,
    embed_links=True
)

client(EditBannedRequest(channel, user, rights))

Kicking a member

Telegram doesn’t actually have a request to kick an user from a group. Instead, you need to restrict them so they can’t see messages. Any date is enough:

from telethon.tl.functions.channels import EditBannedRequest
from telethon.tl.types import ChannelBannedRights

client(EditBannedRequest(channel, user, ChannelBannedRights(
    until_date=None,
    view_messages=True
)))

Increasing View Count in a Channel

It has been asked quite a few times (really, many), and while I don’t understand why so many people ask this, the solution is to use GetMessagesViewsRequest, setting increment=True:

# Obtain `channel' through dialogs or through client.get_entity() or anyhow.
# Obtain `msg_ids' through `.get_message_history()` or anyhow. Must be a list.

client(GetMessagesViewsRequest(
    peer=channel,
    id=msg_ids,
    increment=True
))

Note that you can only do this once or twice a day per account, running this in a loop will obviously not increase the views forever unless you wait a day between each iteration. If you run it any sooner than that, the views simply won’t be increased.