{"id":16775,"library":"better-auth-telegram","title":"Better Auth Telegram Plugin","description":"better-auth-telegram is a plugin for the Better Auth framework, providing comprehensive Telegram authentication capabilities. It supports various Telegram login methods including the traditional Login Widget, Mini Apps, and the more modern OpenID Connect (OIDC) flow, leveraging OAuth 2.0 Authorization Code flow with PKCE. The library handles HMAC-SHA-256 verification and is built on the Web Crypto API, ensuring compatibility across diverse JavaScript runtimes like Node.js (>=22.0.0), Bun, and Cloudflare Workers, without relying on Node.js-specific `node:crypto` modules. The current stable version is 1.5.0, with an active release cadence addressing features, fixes, and compatibility. It integrates seamlessly with Better Auth's client and server-side components, and offers explicit guidance for database schema updates, making it a robust solution for integrating Telegram login into applications.","status":"active","version":"1.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/vcode-sh/better-auth-telegram","tags":["javascript","better-auth","better-auth-plugin","telegram","telegram-login","telegram-mini-apps","authentication","oauth","plugin","typescript"],"install":[{"cmd":"npm install better-auth-telegram","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-telegram","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-telegram","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core authentication framework that this package extends.","package":"better-auth","optional":false}],"imports":[{"note":"This is the server-side plugin export. ESM-only for Node.js >=22.0.0 environments, as specified in `engines`.","wrong":"const { telegram } = require('better-auth-telegram');","symbol":"telegram","correct":"import { telegram } from 'better-auth-telegram';"},{"note":"This is the client-side plugin export, imported from a subpath. Ensure you target the `/client` entry point for browser-specific code.","wrong":"import { telegramClient } from 'better-auth-telegram';","symbol":"telegramClient","correct":"import { telegramClient } from 'better-auth-telegram/client';"},{"note":"When importing types, use `import type` for clarity and to ensure they are stripped during compilation, preventing accidental runtime imports.","wrong":"import { TelegramConfig } from 'better-auth-telegram';","symbol":"telegram","correct":"import type { TelegramConfig } from 'better-auth-telegram';"}],"quickstart":{"code":"import { betterAuth } from \"better-auth\";\nimport { telegram } from \"better-auth-telegram\";\n\n// Ensure TELEGRAM_BOT_TOKEN is set in your environment variables.\n// For local development, consider using ngrok for HTTPS as Telegram requires it.\nexport const auth = betterAuth({\n  plugins: [\n    telegram({\n      botToken: process.env.TELEGRAM_BOT_TOKEN ?? '', // Use environment variable\n      botUsername: \"your_bot_username\", // Replace with your bot's username (without @)\n      // Optional: Disable Login Widget if only using OIDC and to avoid schema clutter\n      // loginWidget: false,\n      // Optional: Enable OIDC and provide client secret (from BotFather > Web Login)\n      // oidc: { enabled: true, clientSecret: process.env.TELEGRAM_OIDC_CLIENT_SECRET ?? '' },\n    }),\n  ],\n});\n\nconsole.log(\"Telegram plugin initialized for Better Auth. Make sure your environment variables are configured.\");\n// In a real application, you would now expose 'auth' via an API handler or similar.","lang":"typescript","description":"Initializes the server-side Telegram authentication plugin for Better Auth using a bot token and username."},"warnings":[{"fix":"Upgrade `better-auth-telegram` to `1.1.0` or higher to ensure compatibility with `better-auth@^1.5.0`. The plugin now uses `defineErrorCodes()` for error code migration.","message":"When upgrading `better-auth` to `1.5.0` or higher, `better-auth-telegram` versions prior to `1.1.0` experienced type errors due to changes in Better Auth's error code structure (`$ERROR_CODES` changed from `Record<string, string>` to `Record<string, RawError>`).","severity":"breaking","affected_versions":"<1.1.0"},{"fix":"Ensure you retrieve the correct 'Client Secret' for Web Login from BotFather, not the main bot token. This fix was explicitly addressed in v1.4.0.","message":"For OIDC authentication, the `clientSecret` is distinct from the `botToken`. Many users incorrectly use the bot token for the OIDC client secret, leading to `invalid_client` errors. The `clientSecret` must be obtained from BotFather via 'Bot Settings > Web Login'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your `createAuthClient` configuration includes `fetchOptions: { credentials: \"include\" }` to send cookies/credentials with requests.","message":"When performing client-side operations like `linkTelegram` or `unlinkTelegram`, if you encounter 'Not authenticated' errors, it's likely due to missing credentials in your `fetchOptions`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `loginWidget: false` in the plugin configuration to disable Login Widget endpoints and omit Telegram-specific schema fields for OIDC-only integrations.","message":"When using OIDC-only setups, by default, the plugin adds database fields for the Login Widget/Mini Apps (`telegramId`, `telegramUsername`, `telegramPhoneNumber` to `User`, and `telegramId`, `telegramUsername` to `Account`). This can clutter your schema if not needed.","severity":"gotcha","affected_versions":">=1.5.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Obtain the correct 'Client Secret' for Web Login from BotFather ('Bot Settings > Web Login') and use it for the `oidc.clientSecret` option.","cause":"Incorrect client secret provided for OIDC. The bot token was used instead of the specific Web Login client secret.","error":"Error: invalid_client"},{"fix":"Configure your `createAuthClient` with `fetchOptions: { credentials: 'include' }`.","cause":"Client-side requests (e.g., `linkTelegram`, `unlinkTelegram`) are not sending authentication credentials (cookies) to the server.","error":"Not authenticated"},{"fix":"Upgrade `better-auth-telegram` to version `1.1.0` or higher to resolve the type mismatch with `better-auth@^1.5.0`.","cause":"Type incompatibility between `better-auth-telegram` and `better-auth` due to a change in the `better-auth`'s internal error code structure.","error":"Property '$ERROR_CODES' does not exist on type 'BetterAuthPlugin'."}],"ecosystem":"npm","meta_description":null}