Overview
This node enables authentication with Telegram using the GramJS API, a Telegram MTProto client library. It facilitates logging into a Telegram account by sending and verifying confirmation codes received via Telegram, managing session strings, and optionally saving session data for reuse.
Common scenarios include:
- Automating Telegram account login within n8n workflows.
- Managing Telegram sessions programmatically without manual intervention.
- Integrating Telegram messaging capabilities that require authenticated access.
Practical example:
- A user triggers this node to authenticate their Telegram account by first requesting a verification code sent to their phone number. They then input the received code into the node to complete authentication. The node can display or save the session string for future use, enabling seamless subsequent operations like sending messages.
Properties
| Name | Meaning |
|---|---|
| Код подтверждения (verificationCode) | Confirmation code from Telegram. Leave empty for the initial request to send the code. |
| Отображать строку сессии в результате (showSessionString) | Whether to show the full session string in the execution result. |
| Автоматически сохранять сессию (saveSession) | Whether to automatically save session information between node executions. |
Output
The node outputs a JSON object describing the authentication status:
success: Boolean indicating if authentication succeeded.message: Human-readable status message.user: Object containing user details such asid,firstName,lastName,username, andphone.sessionString: (optional) The full session string ifshowSessionStringis enabled.sessionStringFormatted: (optional) An object with the full session string, its length, and a preview snippet.sessionStringHidden: (optional) A message indicating the session string is hidden.step: Indicates the current step, e.g.,"enter_code","enter_2fa", or"complete".- Additional fields may appear when two-factor authentication (2FA) is required, including
needPassword2FAandpasswordHint.
If the verification code is not provided initially, the output will prompt the user to enter the code received from Telegram.
Dependencies
- Requires an API key credential with Telegram API credentials (
apiIdandapiHash). - Uses the
telegramandtelegram/sessionsnpm packages (GramJS). - Network connectivity to Telegram servers is necessary.
- Node configuration must include valid Telegram API credentials and optionally saved session strings.
Troubleshooting
Common Issues
- Invalid or expired verification code: If the code entered is incorrect or expired, the node will throw errors prompting to re-enter a valid code.
- Two-factor authentication required: If 2FA is enabled on the Telegram account, the node will request the 2FA password. Failure to provide it results in an error.
- Invalid phone number format: The phone number must be in international format (+1234567890). Using an invalid format causes errors.
- Too many requests: Telegram may limit the number of authentication attempts; users should wait before retrying.
- Lost connection: Temporary network issues with Telegram servers may cause connection errors.
Error Messages and Resolutions
| Error Message (translated) | Cause | Resolution |
|---|---|---|
| "Too many requests. Try again in X seconds." | Rate limiting by Telegram | Wait the specified time before retrying authentication. |
| "Authorization error. Check your data or re-authenticate." | Incorrect verification code or session issue | Verify the code entered or restart the authentication process. |
| "Invalid phone number." | Phone number format incorrect | Use international phone number format (+1234567890). |
| "Two-factor authentication password required." | 2FA enabled but password not provided | Provide the 2FA password in the node parameters. |
| "Lost connection to Telegram server." | Network or server issues | Check internet connection and retry later. |
| "Invalid verification code." | Wrong code entered | Enter the correct code received from Telegram. |