> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/telegram-user.md).

# Telegram User

https\://core.telegram.org/api

The Appmixer **Telegram User** connector signs in as a Telegram **user account** through the official client API (MTProto). Unlike a bot, a user account can read **public channels it has not joined**, so you can watch channels you do not own: news, competitors, topics you want to be alerted about.

Use the [Telegram](/connector-configuration/telegram.md) connector (Bot API) to send messages and to react to messages sent to your bot. Use Telegram User to read public channels.

There is no OAuth app to register. You need three values:

* an **API ID** and an **API Hash**, which you create once at my.telegram.org,
* a **Session String**, which you generate once on your own computer by logging in to the account.

{% hint style="warning" %}
The Session String grants **full access to the Telegram account**: its chats, contacts and settings. Treat it like a password. Use a **dedicated Telegram account** for Appmixer rather than your personal one.
{% endhint %}

{% hint style="info" %}
Telegram keeps accounts that log in through the client API under observation. An account used for flooding or spamming is banned for good. The connector only reads, and paces its requests, but keep the number of watched channels reasonable.
{% endhint %}

***

## 1. Get the API ID and API Hash

1. Open <https://my.telegram.org> and enter the phone number of the Telegram account, in international format (for example `+420123456789`).
2. Telegram sends a login code **as a message in the Telegram app** (from the *Telegram* service chat), not by SMS. Enter it.
3. Go to **API development tools** (<https://my.telegram.org/apps>).
4. Fill in the form. Only **App title** and **Short name** are required. The short name takes letters and digits only, 5 to 32 characters. Pick any **Platform**.
5. Click **Create application**.
6. Copy **App api\_id** (a number) and **App api\_hash** (32 characters).

![The Create new application form at my.telegram.org](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-ed587fad5a945350d4719082a9dfb0229b0ca812%2Ftelegram-user-create-application.png?alt=media)

A phone number can have **one** API ID. If the account already has one, the page shows it instead of the form and you use that.

### The form answers only with ERROR

![The ERROR message of the form](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-97a89db827a9236b81e392623f177623fc712e3f%2Ftelegram-user-apps-error.png?alt=media)

The form is known to reject a request with a bare `ERROR` and no explanation. It is almost never caused by what you typed:

* Turn off your **VPN or proxy**. Requests from well-known VPN address ranges are refused.
* Use a **private window without extensions**, or another browser. Ad blockers and privacy extensions break the request.
* After several attempts in a row, **wait 15 to 60 minutes** and try again. Repeated attempts are blocked for a while.
* A newly created account or a virtual (VoIP) phone number may be refused altogether. The API ID identifies the application, not the account you later log in to, so you can create it with another, older Telegram account and still generate the Session String for the account you want to connect.

***

## 2. Generate the Session String

### What the Session String is

Telegram has no API key and no OAuth for user accounts. An account logs in the way the Telegram app does: phone number, then a login code that Telegram sends to the account, then the two-step verification password if the account has one. The result of that login is a **session**, and the Session String is that session written as text. It works like a long-lived access token: whoever holds it is logged in as the account, without the phone or the code.

Appmixer cannot ask you for the login code while you connect the account, so you log in **once on your own computer** and give Appmixer the resulting Session String. The API ID and API Hash from Step 1 are not enough on their own. They identify your application, not the account.

### What you need

* The **API ID** and **API Hash** from Step 1.
* The **Telegram app**, on a phone or a computer, logged in to the account. The login code arrives there.
* The account's **two-step verification password**, if it has one (Telegram app: *Settings → Privacy and Security → Two-Step Verification*).
* [Node.js](https://nodejs.org) 18 or newer. `node --version` shows what you have. The steps are the same on macOS, Windows and Linux.

It takes about five minutes.

### Generate it

1. Create an empty folder and install the Telegram client library in it:

   ```bash
   mkdir telegram-session && cd telegram-session
   npm install teleproto
   ```
2. Save this file in the folder as `session.js`:

   ```javascript
   const readline = require('node:readline/promises');
   const { TelegramClient } = require('teleproto');
   const { StringSession } = require('teleproto/sessions');

   (async () => {
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
       const apiId = Number(await rl.question('API ID: '));
       const apiHash = (await rl.question('API Hash: ')).trim();

       const client = new TelegramClient(new StringSession(''), apiId, apiHash, { connectionRetries: 3 });
       client.setLogLevel('none');

       await client.start({
           phoneNumber: () => rl.question('Phone number (international format, e.g. +420123456789): '),
           phoneCode: () => rl.question('Login code Telegram sent to your account: '),
           password: () => rl.question('Two-step verification password: '),
           onError: (error) => {
               console.error('Login failed:', error.errorMessage || error.message);
               return true;
           }
       });

       console.log('\nSession String:\n\n' + client.session.save() + '\n');
       await client.destroy();
       process.exit(0);
   })().catch(() => process.exit(1));
   ```

   The script logs in and prints the session. It talks to Telegram only and sends nothing anywhere else.
3. Run it:

   ```bash
   node session.js
   ```

### What you will see

```
$ node session.js
API ID: 12345678
API Hash: 0123456789abcdef0123456789abcdef
[INFO] - [Running teleproto version 1.229.1]
Phone number (international format, e.g. +420123456789): +420123456789
Login code Telegram sent to your account: 12345
Two-step verification password: correct horse battery

Session String:

1BQANOTEuMTA4LjU2LjE2NwG7…(about 370 characters)…Xk=
```

What to enter at each question:

* **API ID** and **API Hash**: the values from Step 1.
* **Phone number**: with the `+` and the country code, without spaces.
* **Login code**: five digits. Within a few seconds Telegram sends them as a message from the official **Telegram** chat (the one with the blue checkmark), to every device where the account is logged in. Keep the account logged in in an official Telegram app; do not count on an SMS.
* **Two-step verification password**: asked only when the account has one. It is shown on the screen as you type.

The message with the code warns you not to give the code to anyone. Typing it into this script on your own computer is what the code is for. Do not paste it into a website or send it in a chat. A code that is sent in a Telegram message stops working.

The **Session String** is one line of about 370 characters. It starts with `1` and ends with `=`. Copy all of it, without spaces or line breaks.

Right after the login, Telegram sends the account a **New login** notification and the session appears in the Telegram app under **Settings → Devices**, named after the *App title* from Step 1. Both are expected.

### If the login fails

The script prints `Login failed:` with Telegram's reason and stops. Fix the cause and run it again.

* `API_ID_INVALID`: the API ID or API Hash is wrong. Copy both again from Step 1 and check for a stray space.
* `PHONE_NUMBER_INVALID`: the number is not in international format. Start with `+` and the country code.
* `PHONE_CODE_INVALID`: the code was mistyped. Run the script again; Telegram sends a new code.
* `PHONE_CODE_EXPIRED`: the code was entered too late, or it was sent in a Telegram chat, which invalidates it. Run the script again.
* `PASSWORD_HASH_INVALID`: the two-step verification password is wrong.
* `PHONE_NUMBER_BANNED`: Telegram has banned the account.
* `A wait of … seconds is required`: too many login attempts. Wait that long before you try again. Further attempts make the wait longer.
* The script hangs or reports a connection error: a firewall or VPN is blocking Telegram. Try another network.

The phone number must already have a Telegram account. The script does not sign a new account up; create it in the official Telegram app first.

### After you have it

* Paste the Session String into Appmixer (Step 3).
* **Delete the folder and clear the terminal.** The Session String and the password were printed on the screen. Do not keep the string in a note, a repository or a chat. If you need to keep it, use a password manager.
* **Need another one?** Run the script again, for example for a second Appmixer connection or another environment. Every run creates a new, independent session, and the earlier ones keep working.
* **It does not expire on a date.** It ends when you terminate it under **Settings → Devices** in the Telegram app, when you use *Terminate all other sessions* there, or when it has not been used for the period set under *Settings → Devices → If inactive for* (six months unless you changed it). A running flow keeps the session in use.

{% hint style="warning" %}
Generate **one Session String per Appmixer connection** and do not use the same string anywhere else at the same time. Telegram revokes a session that is used from two places at once, and the connection then has to be created again.
{% endhint %}

To cut Appmixer off from the account, terminate that session under **Settings → Devices** in the Telegram app. The Session String stops working immediately.

***

## 3. Connect in Appmixer

When you add a Telegram User component to a flow, Appmixer asks you to authenticate. Provide:

* **API ID**: the *App api\_id* from Step 1.
* **API Hash**: the *App api\_hash* from Step 1.
* **Session String**: the string from Step 2.

Appmixer verifies the values by reading the account's own profile and names the connection after its username (for example `@jana_novakova`). The phone number is not stored. A session that belongs to a bot is rejected; bots belong in the [Telegram](/connector-configuration/telegram.md) connector.

***

## 4. Which Channels You Can Read

Every component takes a channel as `@username` or as a link (`https://t.me/username`, a link to a single post works too).

* The channel must be **public**, which means it has a username. Public groups work as well.
* The account does **not** have to join the channel, and the connector never joins it.
* Private channels and invite links (`https://t.me/+…`) are not supported.
* A channel restricted in the account's region returns no messages. This is Telegram's restriction, not a fault of the connection.

***

## 5. How the New Channel Post Trigger Works

* The trigger checks the watched channels **once a minute** and delivers new posts oldest first.
* **Starting the flow sets the starting point.** Only posts published after the flow starts are delivered. To read older posts, use **Find Channel Messages**.
* If the connection to Telegram is down for a while, the posts published in the meantime are delivered once it is back, in order and without duplicates. A long backlog is delivered over several checks, at most 200 posts per channel per check.
* Service messages, such as "channel photo changed", are not delivered.
* The forward source of a forwarded post is shown only when it is a channel. Private users are never exposed.

***

## Limits

* **Find Channel Messages** returns at most 1,000 messages per call, newest first.
* Telegram does not publish fixed limits for user accounts. It answers bursts with a flood wait (see Troubleshooting). Looking up a channel by its username is the most restricted call, so Appmixer remembers the channels it has already looked up. Watching a few dozen channels is fine. Feeding hundreds of new usernames a day into a flow is not.

***

## Self-Managed Installations

Telegram revokes a session that is used from **two IP addresses at the same time**. If your Appmixer engine nodes reach the internet through different public IP addresses, route them through one address (a NAT gateway).

***

## Troubleshooting

### Invalid API ID / API Hash (API\_ID\_INVALID)

The API ID or the API Hash is wrong, or they do not belong together. Copy both again from <https://my.telegram.org/apps>.

### Invalid Session String

The value is not a session string, or it was copied incompletely. It is one long line with no spaces. Run the script from Step 2 again.

### The Session String is no longer valid

The session was ended in **Settings → Devices**, the account logged out everywhere, or the same string was used from two places at once (`AUTH_KEY_DUPLICATED`). Generate a new Session String and create the connection again.

### This session belongs to a bot

The Session String was created by logging in with a bot token. Log in with a phone number of a user account, or use the [Telegram](/connector-configuration/telegram.md) connector for the bot.

### Telegram did not answer within 30 seconds while connecting

A temporary network problem between Appmixer and Telegram. The request is retried.

### Channel does not exist

The username is misspelled or the channel was renamed. Open `https://t.me/username` in a browser to check it.

### Channel is private or not accessible

The channel has no public username, it was deleted, or the account is banned from it. Only public channels can be read.

### "is a user or a bot, not a channel"

The username belongs to a person or a bot. The connector reads channels and public groups only.

### Telegram asked to wait … seconds (FLOOD\_WAIT)

The account sent too many requests. Waits of up to a minute are handled silently. A longer wait fails the step, Appmixer retries it later, and the trigger continues at its next check. If it keeps happening, lower the number of channels or how often your flows call **Find Channel Messages** and **Get Channel**.

### The trigger never fires

* The post was published before the flow started. Only later posts are delivered.
* The channel is restricted in the account's region, so Telegram returns nothing for it.
* The channel went private or was renamed after the flow started. The flow log shows an error for that channel, and the other channels keep working.

***

## Resources

* [Telegram API: obtaining api\_id](https://core.telegram.org/api/obtaining_api_id)
* [Telegram API terms of service](https://core.telegram.org/api/terms)
* [teleproto, the client library used by the connector](https://docs.teleproto.dev)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/telegram-user.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.