Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OPENNOVA2026/telegram-connector/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint iterates through all subscribed channel messages using Telethon’s iter_messages, collecting every message that falls within the specified time window. It filters out MessageService objects (e.g. join/leave events, pin notifications) and direct messages (PeerUser), returning only channel messages. Each message dict is enriched with a meta.channel_name field containing the @username of the source channel. Media fields are stripped from every message before the response is returned.

​
Endpoint

GET /messages

​
Authentication

Requires an active, authenticated Telethon session on the server. When the server is started with API_ID=0, the endpoint automatically falls back to FakeClient, which generates a synthetic stream of messages useful for local development and testing.

​
Query Parameters

​
start_time
string
required
ISO 8601 datetime string representing the beginning of the time window. Messages whose date is less than or equal to start_time are excluded — the iteration loop breaks as soon as such a message is encountered.Example: 2025-01-01T00:00:00Z
​
end_time
string
ISO 8601 datetime string representing the end of the time window. Passed directly to Telethon’s iter_messages as offset_date, so iteration begins at this point and proceeds backwards in time. Defaults to the current time when omitted.Example: 2025-01-02T00:00:00Z

​
How the Time Range Works

Telethon’s iter_messages streams messages in reverse chronological order, starting from end_time and moving backwards toward older messages. The endpoint breaks out of the loop the moment it encounters a message whose date is less than or equal to start_time. The practical result is:
  • Set end_time to the upper bound of your window (newest messages you want).
  • Set start_time to the lower bound of your window (oldest messages you want).
  • All messages with start_time < date <= end_time are returned.
If you omit end_time, iteration starts from the current moment, so you will receive all recent messages up until start_time.

​
Filtering Behavior

The following items are silently skipped and will never appear in the response:
  • MessageService objects — system events such as member join/leave notifications, message pin events, call records, and similar service entries generated by Telegram itself.
  • PeerUser messages — any message originating from a direct message (DM) conversation. Only messages belonging to channels are returned.
  • Media content — the media field is removed from every message dict before the response is serialized. Other message fields that reference media metadata may still be present.

​
Response

​
data
array
required
Array of raw Telethon message dicts. Each element corresponds to one channel message that falls within the requested time window. An extra meta field is injected by the Telegram Connector before the response is returned.

​
Status Codes

StatusDescription
200 OKRequest succeeded. The data array contains all matching messages (may be empty if no messages fall within the window).

​
Example Request

curl 'http://localhost:5004/messages?start_time=2025-01-01T00:00:00Z&end_time=2025-01-02T00:00:00Z'

​
Example Response

{
  "data": [
    {
      "_": "Message",
      "id": 12345,
      "date": "2025-01-01T15:30:00+00:00",
      "message": "Breaking news: new feature released!",
      "peer_id": {
        "_": "PeerChannel",
        "channel_id": 1234567890
      },
      "views": 42000,
      "forwards": 1200,
      "entities": [],
      "meta": {
        "channel_name": "examplechannel"
      }
    }
  ]
}
Large time windows combined with many subscribed channels can produce a very large number of messages. This endpoint does not paginate — it collects all matching messages in memory and returns them in a single response. Consider using narrow time windows (e.g., hourly chunks) when querying high-volume channels to avoid excessive memory usage and long response times.
When API_ID=0, the server uses FakeClient instead of a real Telethon session. FakeClient generates an infinite stream of synthetic messages and only stops when the loop encounters a message whose date falls at or before start_time. Always provide a start_time that is close to end_time (e.g., within a few minutes) in FakeClient mode to prevent the loop from running indefinitely.In FakeClient mode, meta.channel_name values are "Channel 1" through "Channel 10" — these are raw string identifiers, not valid @username handles. Message text is randomly drawn from three fixed strings:
  • "FAKE: I'm on vacations next week! Can't wait!"
  • "FAKE: Burned myself yesterday, but love correfocs"
  • "FAKE: To speak my truth, I love pizza over any other meal"
To retrieve the latest messages from the past hour, set start_time to one hour ago and omit end_time entirely — it defaults to the current server time, so you will receive everything published in that window.
curl "http://localhost:5004/messages?start_time=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)"

Build docs developers (and LLMs) love

Get started for freeTalk to us