Gebeya Telegram Verify

A reusable React component library for phone verification using Telegram. Perfect for integrating secure phone verification into your React applications with Supabase backend.

Features

• 🔐 Secure phone verification via Telegram
• 🔐 Automatic redirection to existing Supabase magic links
• 📱 Responsive UI with mobile-optimized experience
• 📱 Smart device detection (mobile vs desktop)
• 📱 Mobile: Direct "Open Telegram App" button
• 🖥️ Desktop: QR code with alternative access options
• 🎨 Customizable UI components
• 🔧 Framework-agnostic (works with any React + Supabase setup)
• 📋 Built-in country selector
• ⚡ Automatic OTP handling
• 🎯 TypeScript support

Installation

Install the package from npm:

npm install gebeya-telegram-verify

Then install the required peer dependencies:

npm install @supabase/supabase-js lucide-react input-otp sonner qrcode react react-dom

Note: Ensure you have Tailwind CSS configured in your project as the components use Tailwind classes.

Quick Start

1. Set up the Provider

Wrap your app with the TelegramVerificationProvider:

import { TelegramVerificationProvider } from 'gebeya-telegram-verify'
import { supabase } from './supabase/client'

function App() {
  return (
    <TelegramVerificationProvider
      supabaseClient={supabase}
      telegramConfig={{ botName: '@your_bot_name' }}
      onSuccess={(userData) => {
        console.log('Verification successful:', userData)
        // Handle successful verification
      }}
      onError={(error) => {
        console.error('Verification error:', error)
        // Handle verification errors
      }}
    >
      <YourApp />
    </TelegramVerificationProvider>
  )
}

2. Use the Verification Button

import { TelegramVerifyButton } from 'gebeya-telegram-verify'

function LoginPage() {
  return (
    <div>
      <h1>Sign In</h1>
      <TelegramVerifyButton
        buttonText="Verify with Telegram"
        variant="default"
        size="lg"
        onVerificationComplete={(userData) => {
          // User successfully verified
          console.log('User data:', userData)
        }}
        onVerificationStart={() => {
          // Verification process started
          console.log('Verification started')
        }}
      />
    </div>
  )
}

Device Detection & Responsive UI

The library automatically detects the user's device type and adapts the verification flow accordingly:

Mobile Devices

• UI: Shows "Open Telegram App" button with clear instructions
• Behavior: Opens Telegram app and automatically proceeds to OTP page
• Experience: Streamlined flow with automatic progression to next step
• Modal Behavior: Stays open during the process, auto-advances to OTP

Desktop/Larger Screens

• UI: Shows QR code with alternative access options
• Behavior: QR code can be scanned, alternative buttons auto-proceed to OTP
• Experience: Full verification flow with multiple options (QR code, Telegram Web, Desktop App) - all auto-proceed

Detection Criteria

The device detection uses multiple criteria:

• User agent string analysis
• Touch capability detection
• Screen size analysis (≤768px considered mobile)
• Mobile-specific features (orientation, device pixel ratio)

Utilities

You can also use the device detection utilities directly:

import { isMobileDevice, getDeviceType } from 'gebeya-telegram-verify'

// Check if current device is mobile
const isMobile = isMobileDevice()

// Get device type ('mobile' or 'desktop')
const deviceType = getDeviceType()

Supabase Authentication

The library automatically redirects to existing Supabase magic links after successful verification:

// The verification response includes a magic link
const response = {
  session: {
    properties: {
      properties: {
        action_link: "https://your-project.supabase.co/auth/v1/verify?token=..."
      }
    }
  }
}

// Users are automatically redirected to this magic link

Note: This uses the existing magic link from the verification response instead of generating a new one.

African Country Codes

The package includes comprehensive African country codes for phone number selection:

import { africanCountries } from 'gebeya-telegram-verify'

// Access all African countries with their codes
console.log(africanCountries) // Array of 54 African countries

Default Country: Ethiopia (+251) is set as the default country code.

Configuration

1. Create a Telegram bot via @BotFather
2. Get your bot token and store it in Supabase secrets as TELEGRAM_BOT_TOKEN
3. Set up your bot webhook endpoint
4. Deploy the required edge functions (see setup guide)

Supabase Auth Configuration

For passwordless phone authentication to work:

1. Enable Phone Auth: In your Supabase dashboard, go to Authentication > Settings > Auth Providers
2. Enable Phone Provider: Turn on the "Phone" provider
3. Configure SMS Settings: Set up your SMS provider (Twilio, etc.)
4. Enable Magic Links: Ensure "Enable magic links" is enabled for phone authentication

Database Setup

Run these SQL commands in your Supabase SQL editor:

-- Create verification sessions table
CREATE TABLE public.verification_sessions (
  id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
  phone_number TEXT NOT NULL,
  telegram_user_id BIGINT,
  otp_code TEXT,
  verified BOOLEAN NOT NULL DEFAULT false,
  expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
);

-- Enable RLS
ALTER TABLE public.verification_sessions ENABLE ROW LEVEL SECURITY;

-- Create policies
CREATE POLICY "Anyone can insert verification sessions" 
  ON public.verification_sessions FOR INSERT WITH CHECK (true);

CREATE POLICY "Anyone can read verification sessions for verification process" 
  ON public.verification_sessions FOR SELECT USING (true);

CREATE POLICY "Anyone can update verification sessions" 
  ON public.verification_sessions FOR UPDATE USING (true);

Component Props

TelegramVerifyButton

| Prop | Type | Default | Description | |------|------|---------|-------------| | onVerificationComplete | (userData) => void | - | Called when verification succeeds | | onVerificationStart | () => void | - | Called when verification starts | | buttonText | string | "Verify with Telegram" | Button text | | variant | 'default' \| 'outline' \| 'secondary' \| 'ghost' | 'default' | Button style variant | | size | 'sm' \| 'default' \| 'lg' \| 'xl' | 'default' | Button size | | className | string | '' | Additional CSS classes | | color | 'default' \| 'blue' \| 'green' \| 'red' \| 'purple' \| 'orange' \| 'gray' \| 'custom' | 'default' | Button color theme | | customColors | CustomColors | - | Custom color configuration |

TelegramVerificationProvider

| Prop | Type | Required | Description | |------|------|----------|-------------| | supabaseClient | SupabaseClient | ✅ | Your Supabase client instance | | telegramConfig | TelegramConfig | ✅ | Telegram bot configuration | | onSuccess | (userData) => void | - | Global success handler | | onError | (error) => void | - | Global error handler | | theme | ThemeConfig | - | Custom theme configuration | | buttonConfig | ButtonConfig | - | Global button styling configuration |

TelegramConfig

| Prop | Type | Required | Description | |------|------|----------|-------------| | botName | string | ✅ | Your Telegram bot username (e.g., "@your_bot_name") | | botToken | string | - | Your Telegram bot token (optional) |

Styling Customization

The components are designed to integrate seamlessly with your existing CSS framework. By default, they use your website's existing styles and only apply custom styling when explicitly requested.

Default Behavior

• No Custom Styling: Components inherit your website's CSS by default
• Framework Agnostic: Works with any CSS framework (Tailwind, Bootstrap, etc.)
• Minimal Override: Only applies custom styles when explicitly defined

Customization Options

1. CSS Classes: Pass custom className props
2. Theme Configuration: Use the theme prop on the provider
3. CSS Variables: Override default colors and styles
4. Color Variants: Use predefined color themes (only when explicitly requested)
5. Custom Colors: Define your own color schemes

Available Color Themes

• Default: Uses your website's existing CSS styles (no custom styling)
• Blue: Professional and trustworthy
• Green: Success and positive actions
• Red: Warning and destructive actions
• Purple: Creative and premium
• Orange: Attention-grabbing and energetic
• Gray: Neutral and subtle
• Custom: Define your own colors with hex values or Tailwind classes

Example theme configuration:

<TelegramVerificationProvider
  theme={{
    primaryColor: 'blue',
    borderRadius: 'lg',
    fontSize: 'sm'
  }}
  // ... other props
>

Integration Examples

Default Integration (Uses Your CSS)

// This button will use your website's existing CSS styles
<TelegramVerifyButton
  buttonText="Verify with Telegram"
  // No color prop = inherits your website's button styles
  onVerificationComplete={(userData) => {
    console.log('Verification successful:', userData)
  }}
/>

Global Button Configuration

// Configure all buttons globally through the provider
<TelegramVerificationProvider
  supabaseClient={supabase}
  telegramConfig={{ botName: '@your_bot_name' }}
  buttonConfig={{
    defaultColor: 'custom',
    defaultVariant: 'default',
    defaultSize: 'lg',
    customColors: {
      background: '#185D2A',
      text: '#fff',
      border: '#185D2A'
    }
  }}
>
  <YourApp />
</TelegramVerificationProvider>

// Now all buttons will use the global configuration
<TelegramVerifyButton buttonText="Verify" />

With Custom Styling

// Default behavior - uses your website's CSS
<TelegramVerifyButton
  buttonText="🔐 Secure Login"
  // No color prop = uses your website's styles
  variant="default"
  size="lg"
  onVerificationComplete={(userData) => {
    // Custom success handling
    window.location.href = '/dashboard'
  }}
/>

// Explicit color theme
<TelegramVerifyButton
  buttonText="🔐 Secure Login"
  color="green"
  variant="default"
  size="lg"
  onVerificationComplete={(userData) => {
    // Custom success handling
    window.location.href = '/dashboard'
  }}
/>

// Custom colors with hex values <TelegramVerifyButton buttonText="Verify with Telegram" color="custom" customColors={{ background: "#185D2A", text: "#fff", border: "#185D2A", }} variant="default" size="sm" />

// Custom colors with gradient <TelegramVerifyButton buttonText="✨ Magic Verify" color="custom" customColors={{ background: "bg-gradient-to-r from-pink-500 to-violet-500", text: "text-white", hover: "hover:from-pink-600 hover:to-violet-600" }} size="xl" className="font-bold shadow-lg" />

// Outline variant with custom colors <TelegramVerifyButton buttonText="Verify with Style" color="custom" customColors={{ background: "bg-transparent", text: "text-purple-600", border: "border-purple-300", hover: "hover:bg-purple-50" }} variant="outline" size="default" />

### Multiple Verification Methods

```tsx
function AuthPage() {
  const handleVerificationSuccess = (userData) => {
    // Handle successful verification
    setUser(userData.user)
    router.push('/dashboard')
  }

  return (
    <div className="space-y-4">
      <TelegramVerifyButton
        buttonText="Quick Telegram Verification"
        onVerificationComplete={handleVerificationSuccess}
      />
      
      <TelegramVerifyButton
        buttonText="Alternative Verification"
        variant="outline"
        onVerificationComplete={handleVerificationSuccess}
      />
    </div>
  )
}

Required Dependencies

The package has the following peer dependencies that you need to install:

{
  "peerDependencies": {
    "@supabase/supabase-js": ">=2.39.0",
    "input-otp": ">=1.0.0",
    "lucide-react": ">=0.300.0",
    "qrcode": ">=1.4.0",
    "react": ">=17.0.0",
    "react-dom": ">=17.0.0",
    "sonner": ">=1.0.0"
  }
}

Installation Command

npm install gebeya-telegram-verify @supabase/supabase-js lucide-react input-otp sonner qrcode

Note: This package now supports a wider range of dependency versions for better compatibility:

• React 17.0.0+ (instead of requiring 18.0.0+)
• lucide-react 0.300.0+ (compatible with newer versions like 0.462.0+)
• Flexible version ranges for all other dependencies

Environment Variables

Set these in your Supabase project secrets:

• TELEGRAM_BOT_TOKEN: Your Telegram bot token
• SUPABASE_URL: Your Supabase project URL
• SUPABASE_ANON_KEY: Your Supabase anon key
• SUPABASE_SERVICE_ROLE_KEY: Your Supabase service role key

Troubleshooting

Common Issues

1. Bot not responding: Check if your bot token is correct and webhook is set up
2. Database errors: Ensure RLS policies are configured correctly
3. Styling issues: Make sure Tailwind CSS is properly configured
4. Type errors: Ensure all peer dependencies are installed

Debug Mode

Enable debug logging by setting NODE_ENV=development.

Development

To build the package locally:

git clone https://github.com/your-username/gebeya-telegram-verify.git
cd gebeya-telegram-verify
npm install
npm run build

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the setup guide
3. Check your Supabase edge function logs
4. Verify your Telegram bot configuration
5. Open an issue on GitHub

License

MIT License - feel free to use in your projects!

Contributing

We welcome contributions! Please read our contributing guidelines and submit pull requests to our GitHub repository.

Changelog

v1.2.0

• NEW: Enhanced mobile-responsive UI with device-specific experiences
• NEW: Mobile devices show "Open Telegram App" button with automatic OTP progression
• NEW: Desktop devices retain full QR code + alternative options interface with auto-proceed
• NEW: Automatic redirection to existing Supabase magic links after successful verification
• NEW: Comprehensive button styling system with 6 color themes and custom colors
• NEW: Extended button sizes (sm, default, lg, xl) for better customization
• NEW: Comprehensive African country codes (54 countries) with Ethiopia as default
• NEW: Dynamic bot name configuration from provider settings
• IMPROVED: Modal only closes with explicit close button (no accidental backdrop closing)
• IMPROVED: All Telegram opening buttons automatically proceed to OTP page
• IMPROVED: Better device detection with additional mobile-specific criteria
• IMPROVED: Updated UI icons and messaging for mobile vs desktop contexts
• IMPROVED: Default behavior now uses your website's CSS (no custom styling unless explicitly requested)
• REMOVED: Success screen - verification completes directly after OTP
• DOCS: Updated documentation with mobile-responsive behavior details

v1.1.0

• FIXED: Peer dependency version conflicts by using flexible version ranges (>=)
• IMPROVED: Better backward compatibility with React 17+ and newer lucide-react versions
• RESOLVED: npm ERESOLVE errors when installing with existing dependencies

v1.0.0

• Initial release
• Basic Telegram verification functionality
• QR code support
• OTP handling
• TypeScript support