{"id":16747,"library":"telegram-better-auth","title":"Telegram Better Auth Plugin","description":"The `telegram-better-auth` package provides a plugin to seamlessly integrate Telegram login functionality into applications built with the `better-auth` authentication framework. This library, currently at version `0.0.8`, offers a streamlined approach to allowing users to authenticate via their Telegram accounts, managing both the server-side logic for verifying authorization data and the client-side interaction with the Telegram Login Widget. While a formal release cadence is not explicitly stated, the frequent minor version bumps (0.0.x) suggest active development. A key differentiator is its tightly coupled design with `better-auth`, abstracting complex Telegram API interactions, such as the generation of temporary emails based on Telegram IDs. Proper functioning requires a valid Telegram bot token and ensuring the bot is linked to the application's domain via BotFather.","status":"active","version":"0.0.8","language":"javascript","source_language":"en","source_url":"https://github.com/vitalygashkov/telegram-better-auth","tags":["javascript","telegram","better-auth","auth","authentication","plugin","typescript"],"install":[{"cmd":"npm install telegram-better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add telegram-better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add telegram-better-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication framework that this package extends; required as a peer dependency.","package":"better-auth","optional":false}],"imports":[{"note":"Used for configuring the server-side Telegram plugin within better-auth. This package is ESM-only since its inception.","wrong":"const { telegram } = require('telegram-better-auth');","symbol":"telegram","correct":"import { telegram } from 'telegram-better-auth';"},{"note":"Used for configuring the client-side Telegram plugin within better-auth/client. Ensure consistency between server and client plugin configurations.","wrong":"const { telegramClient } = require('telegram-better-auth');","symbol":"telegramClient","correct":"import { telegramClient } from 'telegram-better-auth';"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { createAuthClient } from 'better-auth/client';\nimport { telegram, telegramClient } from 'telegram-better-auth';\n\n// --- Server-side configuration (auth.ts) ---\nexport const auth = betterAuth({\n  plugins: [\n    telegram({\n      botToken: process.env.TELEGRAM_BOT_TOKEN ?? '', // Ensure BOT_TOKEN is set in your environment\n      getTempEmail: (id) => `${id}@t.me`, // Function to generate a temporary email for Telegram users\n    }),\n  ],\n});\n\n// --- Client-side configuration (auth-client.ts) ---\nconst authClient = createAuthClient({\n  plugins: [telegramClient()],\n});\n\ninterface TelegramUserAuthData {\n  id: number;\n  first_name: string;\n  last_name?: string;\n  username?: string;\n  photo_url?: string;\n  auth_date: number;\n  hash: string;\n}\n\n// Example function to handle data from Telegram Login Widget callback\nconst onTelegramAuth = async (user: TelegramUserAuthData) => {\n  try {\n    console.log('Attempting Telegram sign-in for user:', user.username || user.id);\n    const data = await authClient.signIn.telegram(user);\n    console.log('Telegram sign-in successful:', data);\n    // Implement session refetch, redirect, etc.\n  } catch (error) {\n    console.error('Telegram sign-in failed:', error);\n    // Handle error (e.g., display message to user)\n  }\n};\n\n// This function would typically be called from the Telegram Login Widget's callback\n// For demonstration, a placeholder:\n// For testing, mock a user object (replace with actual data from Telegram):\n// const mockTelegramUser: TelegramUserAuthData = {\n//   id: 123456789,\n//   first_name: 'Test',\n//   username: 'testuser',\n//   auth_date: Math.floor(Date.now() / 1000),\n//   hash: 'mockhash_for_dev_only' // This hash must be generated by Telegram, don't hardcode in production\n// };\n// onTelegramAuth(mockTelegramUser);\n","lang":"typescript","description":"Demonstrates both server-side and client-side setup for Telegram authentication using `telegram-better-auth` with `better-auth`. It covers plugin configuration and an example of handling authentication data from the Telegram Login Widget."},"warnings":[{"fix":"Contact @BotFather on Telegram, use the `/setdomain` command, and link your bot to the exact domain(s) where your Telegram Login Widget will be hosted.","message":"The Telegram bot used for authentication must be correctly configured with a domain via the @BotFather bot using the `/setdomain` command. Failure to do so will prevent the Telegram Login Widget from functioning correctly or lead to verification failures.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Obtain a valid bot token from @BotFather. Set it as an environment variable (e.g., `TELEGRAM_BOT_TOKEN`) and ensure it's correctly accessed in your server-side configuration, e.g., `process.env.TELEGRAM_BOT_TOKEN ?? ''`.","message":"The `botToken` passed to the `telegram` plugin on the server-side is crucial for verifying the authenticity of Telegram login data. Ensure this token is securely stored (e.g., in environment variables) and is valid. An invalid or missing token will lead to authentication failures.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Regularly review the package's GitHub repository and changelog before upgrading to new `0.0.x` versions. Consider pinning to exact versions to prevent unexpected breaking changes.","message":"As this package is currently in version `0.0.x`, its API surface may undergo breaking changes without a major version increment (e.g., 1.0.0). Developers should be aware of potential API instability and review changelogs for updates.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure your project's Node.js environment is updated to version 20 or newer. Check your `package.json` engines field to reflect this requirement.","message":"This package, and its peer dependency `better-auth`, require Node.js version 20 or higher. Running on older Node.js versions will result in runtime errors related to unsupported syntax or APIs.","severity":"gotcha","affected_versions":"<=0.0.8"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `telegram` plugin is added to the `plugins` array of `betterAuth` on the server and `telegramClient` plugin is added to `createAuthClient` on the client. Verify correct import paths.","cause":"The `telegram` plugin was not correctly registered in the `betterAuth` instance, or the `signIn.telegram` method was called on an `authClient` instance without `telegramClient` plugin.","error":"TypeError: Cannot read properties of undefined (reading 'telegram')"},{"fix":"Verify that the `botToken` in your server-side `telegram` plugin configuration is correct and matches the token of the bot linked to your domain. Ensure no modifications occur to the data object received from Telegram before sending it to the server.","cause":"The `hash` provided by the Telegram Login Widget does not match the server-calculated hash, indicating tampered data or an incorrect bot token configuration.","error":"Error: Telegram login data verification failed: Invalid hash"},{"fix":"Ensure the user re-authenticates via the Telegram Login Widget to obtain fresh `auth_date` and `hash` values. This error is typically handled by guiding the user to try logging in again.","cause":"The `auth_date` from the Telegram Login Widget is too old (typically more than 24 hours ago), meaning the authentication session has expired.","error":"Error: Telegram login data verification failed: Auth date out of range"}],"ecosystem":"npm"}