Telegram Verification Setup Guide

This guide walks you through setting up the Telegram verification system in your Lovable application.

Prerequisites

• Lovable project with Supabase integration
• Telegram account
• Basic knowledge of React and Supabase

Step 1: Create Telegram Bot

1. Open Telegram and search for @BotFather
2. Start a chat and use /newbot command
3. Follow the instructions to create your bot
4. Save the bot token - you'll need it later
5. Note your bot username (e.g., @your_bot_name)

Step 2: Database Setup

In your Supabase SQL Editor, run:

-- 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 Row Level Security
ALTER TABLE public.verification_sessions ENABLE ROW LEVEL SECURITY;

-- Create policies for verification process
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);

Step 3: Set Environment Variables

In Supabase Dashboard > Settings > Edge Functions, add:

• TELEGRAM_BOT_TOKEN: Your bot token from Step 1

Step 4: Deploy Edge Functions

Create these edge functions in your supabase/functions/ directory:

Add the folloing in your supabase/config.toml/

[functions.telegram-webhook] verify_jwt = false

[functions.verify-otp] verify_jwt = false

Telegram Webhook (supabase/functions/telegram-webhook/index.ts)

// ... existing code ...

OTP Verification (supabase/functions/verify-otp/index.ts)

// ... existing code ...

Step 5: Set Up Webhook

1. Get your edge function URL from Supabase Dashboard
2. Set your bot webhook by calling:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://<YOUR_PROJECT_ID>.supabase.co/functions/v1/telegram-webhook"}'

Step 6: Copy Components

1. Copy the telegram-verification-components folder to your src directory
2. Install required dependencies:

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

Step 7: Integration

Basic Setup

// In your main App.tsx or layout file
import { TelegramVerificationProvider } from "gebeya-telegram-OTP";
import { supabase } from "./integrations/supabase/client";

function App() {
  return (
    <TelegramVerificationProvider
      supabaseClient={supabase}
      telegramConfig={{ botName: "@your_bot_name" }}
      onSuccess={(userData) => {
        console.log("Verification successful:", userData);
      }}
    >
      <YourAppContent />
    </TelegramVerificationProvider>
  );
}

Using the Button

import { TelegramVerifyButton } from "gebeya-telegram-OTP";

function LoginPage() {
  return (
    <TelegramVerifyButton
      buttonText="Verify with Telegram"
      onVerificationComplete={(userData) => {
        // Handle successful verification
        console.log("User verified:", userData);
      }}
    />
  );
}

Testing

1. Deploy your edge functions
2. Set up the webhook
3. Test the verification flow:
   • Enter a phone number
   • Scan QR code or click Telegram link
   • Share contact in Telegram
   • Enter OTP code
   • Verify successful authentication

Troubleshooting

Common Issues

1. Webhook not working: Check edge function logs in Supabase
2. Bot not responding: Verify bot token and webhook URL
3. Database errors: Check RLS policies and table structure
4. OTP not received: Check Telegram bot permissions

Debug Steps

1. Check Supabase edge function logs
2. Test webhook manually with curl
3. Verify database entries in verification_sessions table
4. Check Telegram bot settings with @BotFather

Security Considerations

1. Never expose bot token in client-side code
2. Implement rate limiting for verification attempts
3. Set appropriate session expiry times
4. Use HTTPS for all webhook URLs
5. Validate phone numbers on both client and server

Next Steps

• Customize styling to match your app
• Add additional security measures
• Implement user profiles
• Add multi-language support
• Set up monitoring and analytics