search_messages()

async Client.search_messages()

Search for text and media messages inside a specific chat.

If you want to get the messages count only, see search_messages_count().

Usable by Users Bots
Parameters:
  • chat_id (int | str) – Unique identifier (int) or username (str) of the target chat. For your personal cloud (Saved Messages) you can simply use “me” or “self”. For a contact that exists in your Telegram address book you can use his phone number (str).

  • query (str, optional) – Text query string. Required for text-only messages, optional for media messages (see the filter argument). When passed while searching for media messages, the query will be applied to captions. Defaults to “” (empty string).

  • offset (int, optional) – Sequential number of the first message to be returned. Defaults to 0.

  • filter (MessagesFilter, optional) – Pass a filter in order to search for specific type of messages only. Defaults to EMPTY (search all messages).

  • limit (int, optional) – Limits the number of messages to be retrieved. By default, no limit is applied and all messages are returned.

  • from_user (int | str, optional) – Unique identifier (int) or username (str) of the target user you want to search messages from for groups and supergroups.

  • saved_peer_id (int | str, optional) – Unique identifier (int) or username (str) of the target chat you want to search messages from for your personal cloud (Saved Messages).

  • top_msg_id (int, optional) – Unique identifier of the forum topic the action is broadcast to.

  • offset_id (int, optional) – Identifier of the first message to be returned.

  • min_date (datetime, optional) – Pass a date to return only messages sent on or after that date.

  • max_date (datetime, optional) – Pass a date to return only messages sent on or before that date.

  • min_id (int, optional) – Identifier of the oldest message to be returned.

  • max_id (int, optional) – Identifier of the newest message to be returned.

Returns:

Generator – A generator yielding Message objects.

Example

# Search for "hello" in chat
async for message in app.search_messages(chat_id, query="hello"):
    print(message.text)

# Search for recent photos in chat
async for message in app.search_messages(chat, filter=enums.MessagesFilter.PHOTO):
    print(message.photo)

# Search for messages containing "hello" sent by yourself in chat
async for message in app.search_messages(chat, "hello", from_user="me"):
    print(message.text)