Messages Endpoints
Message Endpoints
1. Search Messages
Description:
Performs a search across messages based on various optional criteria like text content, group, user, message type, bot/spammer status, and date range.
Parameters:
text(string, optional): Search in message textgroup_username(string, optional): Filter by group usernameusername(string, optional): Filter by sender usernamemessage_type(string, optional): Filter by message type ("raw" or "clean")user_is_bot(boolean, optional): Filter by bot statususer_is_spammer(boolean, optional): Filter by spammer statusspam_flag(boolean, optional): Filter by spam flagstart_date(string, optional): Start date in ISO 8601 formatend_date(string, optional): End date in ISO 8601 formatfrom_(integer, optional, default=0): Starting offset for paginationsize(integer, optional, default=100): Number of messages to return
Example request:
Response:
Response Fields:
id(integer)Unique message ID (only unique within the same chat_id)
chat_id(integer)Internal Telegram chat ID
user_id(integer)Internal Telegram user ID
date(string)Timestamp of when the message was sent (ISO 8601 format)
group_username(string)Username of the group where the message was sent
username(string)Telegram username of the sender
user_is_bot(boolean)Indicates if the user has been previously identified as a bot
user_is_spammer(boolean)Indicates if the user has been previously identified as a spammer
sender_type(string)Type of sender: MessageSenderUser (user) or MessageSenderChat (chat)
text(string)Raw original message text
clean_text(string)Cleaned version of the message text after processing
message_type(string)Type of message, can be “raw” or “clean” depending if the message has been cleansed or not
spam_flag(boolean)Whether the message has been flagged as spam
views(integer)Number of times the message has been viewed
replies(integer)Number of replies to this message
forwards(integer)Number of times the message has been forwarded
reply_to_id(integer/null)If the message is a reply, contains the ID of the referenced message
member_online_count(integer)Number of members online in the group at the time the message was sent
2. Get User Messages
Description:
Retrieves a list of messages sent by a specific user, identified by either username or user_id, within a given date range. Allows filtering by message type and spam status.
Parameters:
username(string, required): Telegram usernamestart_date(string, required): Start date in ISO formatend_date(string, required): End date in ISO format
Example request:
Response Fields have same structure as Search Messages, filtered for specific user.
3. Get Chat Messages
Description:
Retrieves a list of messages for a specific chat group, identified by either group_username or chat_id, within a given date range. Allows filtering by message type (raw/clean) and spam status.
Parameters:
group_username(string, optional): The username of the group chat. Either this or chat_id must be provided.chat_id(integer, optional): The internal Telegram ID of the chat. Either this or group_username must be provided.start_date(datetime, required): Start date for the message query in ISO 8601 format (e.g., 2023-10-26T00:00:00).end_date(datetime, required): End date for the message query in ISO 8601 format (e.g., 2023-10-27T23:59:59).message_type(string, optional): Filter messages by type. Accepts "raw" or "clean". If omitted, retrieves messages regardless of type.with_spams(boolean, optional): Filter messages based on spam status. true includes spam, false excludes spam. If omitted, the default behavior depends on the service implementation (likely excludes spam unless specified).from_(integer, optional, default: 0): Starting offset for pagination.size(integer, optional, default: 100): Number of messages to return per page.
Example request:
Response fields have the same structure as Search Messages, filtered for specific chat.
Example response:
4. Get Messages by Timeframe
Description:
Retrieves all messages across all monitored chats within a specific date range. Allows optional filtering by message type and spam status. Useful for broad analysis over time.
Parameters:
start_date(string, required): Start date in ISO 8601 format (e.g., 2023-01-01T00:00:00)end_date(string, required): End date in ISO 8601 format (e.g., 2023-01-31T23:59:59)message_type(string, optional): Type of messages to retrieve ("raw" or "clean")with_spams(boolean, optional): Filter by spam statusfrom_(integer, optional, default=0): Starting point for paginationsize(integer, optional, default=100): Number of messages to return
Example request:
Response fields have the same structure as Search Messages, filtered for timeframe.
Last updated