> For the complete documentation index, see [llms.txt](https://runtimedesigns.gitbook.io/token-buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://runtimedesigns.gitbook.io/token-buzz/connecting-data-byok/telegram.md).

# Telegram

TokenBuzz connects to Telegram via the MTProto user-account API using [GramJS](https://gram.js.org/). You supply three values — an `api_id`, an `api_hash`, and a **GramJS StringSession** — which together represent an authenticated Telegram user session. TokenBuzz uses these credentials to read messages from public Telegram channels you want to monitor.

## What you'll need

* A Telegram account (phone number required).
* A Telegram application registered at `my.telegram.org` (takes about one minute).
* A GramJS `StringSession` — a base64 string generated by signing in once with your api\_id and api\_hash using a GramJS script.

## Get your credentials

### Step 1 — Register a Telegram application

1. Log in at <https://my.telegram.org> using your phone number.
2. Click **API development tools**.
3. Fill in any **App title** and **Short name** (these are internal labels; they don't affect TokenBuzz).
4. Click **Create application**.
5. Telegram displays your **App api\_id** (a number, e.g. `12345678`) and **App api\_hash** (a hex string). Copy both.

Reference: [Obtaining api\_id — Telegram documentation](https://core.telegram.org/api/obtaining_api_id)

### Step 2 — Generate a GramJS StringSession

A StringSession is a portable, serialised Telegram login token. You generate it once by running a short authentication script with GramJS.

The [GramJS documentation](https://gram.js.org/) provides starter scripts for generating a session string. The typical flow:

1. Install GramJS (`npm install telegram`).
2. Run a small Node.js script that creates a `TelegramClient` with your `apiId` and `apiHash`, calls `client.start()` (which will prompt you for your phone number and a Telegram login code), then prints `client.session.save()` — that output is your StringSession.
3. Copy the printed session string; it looks like a long base64-encoded blob.

Keep the session string secret — it represents a full login to your Telegram account.

## Connect in TokenBuzz

1. In TokenBuzz, open **Account → API Keys**.
2. Make sure the mode selector is set to **Per-source keys**.
3. Select the **Telegram** tab.
4. Fill in the three fields:
   * **API ID** — your numeric `api_id` from `my.telegram.org`.
   * **API hash** — your `api_hash` string from `my.telegram.org`.
   * **Session string** — the GramJS StringSession you generated.
5. Click **Validate & save**. TokenBuzz stores the credentials (encrypted) and confirms the connection.
6. Optionally enable **Use my key for background polling** to have TokenBuzz monitor Telegram channels in the background (default polling interval is approximately 15 minutes, bounded by Telegram's FLOOD\_WAIT rate limits).

To remove the credentials, click **Remove key** on the configured card.

## Security & notes

* All three fields are encrypted with AWS KMS before being stored. The session string in particular is treated as a secret (equivalent to a password). Only the last four characters of the stored credential are shown in the UI.
* Credentials can be rotated by removing the existing entry and saving a new one.
* The session string gives TokenBuzz access to your Telegram account for the purpose of reading public channel messages. It does not expose your private messages — only channels the account can observe.
* If Telegram returns an authentication error (invalid or expired session), TokenBuzz marks the key as invalid and notifies you by email.
* Telegram enforces rate limits via `FLOOD_WAIT` responses. TokenBuzz respects these with per-channel bounded retry and skip logic — a rate-limited channel is skipped for the current poll cycle rather than blocking all monitoring.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://runtimedesigns.gitbook.io/token-buzz/connecting-data-byok/telegram.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.