n8n-nodes-telegram-account

An n8n community node that lets a workflow act as a Telegram user
account over MTProto (via GramJS), instead of
as a bot.

Why

The Telegram Bot API only sees chats the bot has been explicitly added to, and it cannot
join public channels or groups on its own, read history from before it joined, or read
channels/groups that don't allow bots at all. A logged-in user account has none of those
restrictions: it can watch any channel or group the account is a member of (or can join),
read full history, and send messages exactly as a normal Telegram client would.

This package trades that extra reach for extra responsibility — see Security below
before using it.

Installation

Install like any other n8n community node:

1. In n8n, go to Settings → Community Nodes.
2. Select Install.
3. Enter n8n-nodes-telegram-account.
4. Agree to the risk warning and select Install.

For a self-hosted / Docker instance, you can alternatively install it into the n8n
container's custom-extensions folder and restart n8n.

Getting API credentials

1. Go to my.telegram.org/apps and log in with the phone
   number you plan to automate.
2. Create an application (any name/platform works). Note the api_id and api_hash
   shown — you'll need both.

Logging in (one-time, inside n8n)

The credential type (Telegram Account API) needs a sessionString, which only exists
after you've completed an interactive login. Do that with the Telegram Account node
itself, using a throwaway workflow:

1. Add a Telegram Account node, set Resource to Auth and Operation to
   Send Code. Fill in API ID, API Hash, and Phone Number, then execute the
   node. Telegram sends a login code to the Telegram app (or SMS) on that phone number.
   Copy the phoneCodeHash and preAuthSession values from the output.
2. Add a second Telegram Account node (or change the same one), set Operation to
   Sign In. Fill in the same API ID/API Hash/Phone Number, plus Phone Code Hash and
   Pre-Auth Session from step 1, and Phone Code with the code you received. If
   the account has two-factor authentication enabled, also fill in Password — leave
   it out and n8n will throw a clear error telling you it's needed.
3. Execute the node. The output contains sessionString — copy it.
4. Create a Telegram Account API credential and paste apiId, apiHash, and
   sessionString (the value from step 3) into it. Every other node uses this
   credential from now on; you can delete the throwaway Auth nodes.

The session string is long-lived (it does not expire on its own — see Troubleshooting
for when it does get revoked).

Node: Telegram Account

The main action node. Auth operations don't need the credential (they take API ID/Hash
as parameters, since the credential doesn't exist yet during login); every other resource
uses the Telegram Account API credential.

Auth

Chat

Media

Message

User

Chat parameters everywhere accept a @username, a t.me/... link (including
t.me/+invite and t.me/c/<id>/... private-channel links), or a numeric chat ID
(including the -100-prefixed form Telegram uses for channels/supergroups).

Node: Telegram Account Trigger

Starts a workflow when the logged-in account observes activity in one or more chats.

Deleted-message events from Telegram don't reliably include which chat a message was
deleted from outside of channels/supergroups — this is a Telegram API limitation, not
something this node can work around.

Output shape

Every message-producing operation/event returns the same flat JSON:

{
  "id": 123,
  "chatId": "-1001234567890",
  "chat": { "id": "-1001234567890", "title": "Some Channel", "username": "somechannel", "type": "channel" },
  "date": "2026-08-25T12:00:00.000Z",
  "text": "hello",
  "sender": { "id": "111", "username": "someone", "firstName": "Some", "lastName": "One" },
  "replyToId": null,
  "editDate": null,
  "isForward": false,
  "forwardFrom": null,
  "link": "https://t.me/somechannel/123",
  "views": 42,
  "media": null,
  "entities": []
}

Security

The session string is equivalent to your Telegram password — anyone who has it can
read your chats, send messages as you, and stay logged in until you revoke it from
Telegram's Settings → Devices. Store it only inside an n8n credential (which n8n
encrypts at rest); never put it in a workflow parameter, a Set node, logs, or version
control. Treat the API ID/Hash the same way, though they're less sensitive on their own.

Troubleshooting

• PHONE_CODE_EXPIRED — the login code expired before Sign In was executed; go back to
  Send Code and start again.
• SESSION_PASSWORD_NEEDED — the account has two-factor authentication enabled; fill
  in the Password field on the Sign In operation.
• FloodWaitError — Telegram is rate-limiting this account; the trigger node sleeps
  for the requested time and retries automatically. If you see this from the action
  node, wait the indicated number of seconds before retrying.
• AUTH_KEY_UNREGISTERED — the session was revoked (logged out from Telegram's device
  list, or the account's 2FA/password changed). Repeat the login flow to get a new
  sessionString.