Implement a complete, production-ready Telegram integration for the existing Vexora store.
IMPORTANT:
This task is ONLY about Telegram Bot + Customer/User Telegram integration.
Do NOT modify unrelated storefront features, UI, payments, products, reviews, ads, themes, languages, categories, authentication logic, or admin features except where strictly required for this Telegram integration.
Reuse the existing Telegram bot, webhook, order, payment, customer, and delivery systems wherever they already exist.
Do NOT create a second Telegram system.
Preserve all existing functionality.
Use minimal-diff changes.
━━━━━━━━━━━━━━━━━━━━
1. ADMIN TELEGRAM BOT USERNAME
━━━━━━━━━━━━━━━━━━━━
Add a Telegram Bot Username configuration to the existing admin panel.
The admin must be able to configure the store’s Telegram Bot Username.
Examples:
@VexoraBot
VexoraBot
Normalize the value safely:
Remove a leading @ if present.
Store only the normalized username.
When displaying it, show it as @Username.
The username must be stored persistently in the database/configuration system.
Do NOT hardcode the bot username.
IMPORTANT SECURITY:
NEVER display the Telegram Bot Token in the admin UI.
NEVER expose the Bot Token to the browser/client.
Keep the Bot Token server-side only.
Preserve the existing Telegram webhook secret verification.
Do not weaken any existing webhook security.
━━━━━━━━━━━━━━━━━━━━
2. TELEGRAM BOT CONFIGURATION
━━━━━━━━━━━━━━━━━━━━
The existing Telegram bot must use the configured Bot Username.
If the username is:
VexoraBot
then customer-facing links should use:
For Telegram deep-link account connection, use:
https://t.me/VexoraBot?start=<ONE_TIME_TOKEN>
Do not construct links using user-provided arbitrary URLs.
Validate the configured username server-side.
If the Telegram bot username is not configured:
Do not generate broken Telegram links.
Show a clear configuration status.
Existing non-Telegram functionality must continue working normally.
━━━━━━━━━━━━━━━━━━━━
3. CUSTOMER TELEGRAM ACCOUNT LINKING
━━━━━━━━━━━━━━━━━━━━
Implement secure Telegram account linking for authenticated customers.
IMPORTANT:
A Telegram username is NOT sufficient for reliable private-message delivery.
The system must securely obtain and store the customer’s Telegram chat_id after the customer explicitly connects their Telegram account through the bot.
Do NOT:
Ask the customer to manually enter a chat_id.
Trust a chat_id supplied by the browser.
Allow the customer to submit someone else’s Telegram chat_id.
Use Telegram username alone as the delivery identifier.
The correct flow:
Customer logs into their Vexora account.
Customer selects Telegram as their delivery method.
Website displays:
Telegram Bot: @ConfiguredBotUsername
Connect Telegram
Customer clicks “Connect Telegram”.
Server generates a cryptographically secure, random, short-lived, single-use linking token.
Website generates:
https://t.me/<bot_username>?start=<one_time_token>
Customer opens the Telegram bot.
Telegram sends /start <one_time_token> to the existing bot webhook.
Server validates the token.
If valid:
Identify the authenticated customer associated with the token.
Obtain the Telegram chat_id from the Telegram update.
Optionally obtain Telegram username when safely available.
Associate that Telegram account/chat_id with the authenticated customer.
Mark the token as consumed.
Website should be able to show:
“Telegram connected ✓”Future successful purchases can use the securely linked Telegram chat_id for delivery.
━━━━━━━━━━━━━━━━━━━━
4. LINKING TOKEN SECURITY
━━━━━━━━━━━━━━━━━━━━
The Telegram account-linking token must be:
Cryptographically random.
Unpredictable.
Short-lived.
Single-use.
Stored securely server-side.
Associated with the correct customer.
Invalid after expiration.
Invalid after successful use.
Invalid after explicit cancellation if cancellation exists.
Protect against:
Token guessing.
Token replay.
Token reuse.
Account takeover.
Linking a Telegram account to the wrong customer.
Forged Telegram /start requests.
Client-side manipulation.
Never use:
customerId as the token.
order number as the token.
email as the token.
Telegram username as the token.
Sequential numeric IDs as the token.
The server must be the authority for the customer ↔ Telegram relationship.
━━━━━━━━━━━━━━━━━━━━
5. TELEGRAM DATABASE DATA
━━━━━━━━━━━━━━━━━━━━
Use the existing Customer/User model if available.
Add only the minimum required persistent fields or a dedicated relation/table if that better matches the existing architecture.
The system must be able to distinguish:
Telegram Bot Username
Store configuration.
Customer Telegram Username
Optional profile information from Telegram.
Customer Telegram Chat ID
The actual secure delivery destination.
Telegram connection status
Connected / disconnected.
Telegram linking tokens
Token hash/value as appropriate.
Customer ID.
Expiration.
Used/consumed state.
Created timestamp.
Do not expose sensitive Telegram identifiers unnecessarily to the frontend.
Follow the existing Prisma/database architecture.
━━━━━━━━━━━━━━━━━━━━
6. CUSTOMER ACCOUNT UI
━━━━━━━━━━━━━━━━━━━━
Inside the authenticated customer’s account/order/delivery area, add Telegram connection controls using the existing UI design.
If Telegram is NOT connected:
Show:
Telegram Bot: @ConfiguredBotUsername
Button:
Connect Telegram
If Telegram IS connected:
Show:
Telegram connected ✓
Optionally display the connected Telegram username when safely available.
Provide:
Reconnect Telegram
if the customer wants to connect another Telegram account.
If the bot is not configured:
Show a clear message such as:
Telegram delivery is currently unavailable. Please try again later.
Do not expose the Bot Token.
━━━━━━━━━━━━━━━━━━━━
7. DELIVERY METHOD
━━━━━━━━━━━━━━━━━━━━
When an order supports Telegram delivery, the customer must be able to select:
Telegram
When Telegram is selected:
Check whether the customer has a verified Telegram connection.
If not connected, guide the customer to “Connect Telegram”.
Do not allow the system to pretend Telegram delivery is ready when there is no verified chat_id.
Display:
Telegram Bot: @ConfiguredBotUsername
and:
Open Telegram Bot
when appropriate.
The button must open:
https://t.me/<configured_bot_username>
━━━━━━━━━━━━━━━━━━━━
8. ORDER + PAYMENT DELIVERY
━━━━━━━━━━━━━━━━━━━━
Integrate Telegram delivery with the existing successful-payment flow.
After payment is successfully confirmed:
Verify the order is actually paid.
Verify the order has Telegram as its delivery method.
Verify the customer has a securely linked Telegram chat_id.
Deliver the purchased product through the existing Telegram delivery system.
Record delivery status.
Prevent duplicate delivery.
NEVER deliver based solely on:
Client-side payment status.
Client-provided Telegram chat_id.
Telegram username.
Client-provided order data.
The server must verify everything.
━━━━━━━━━━━━━━━━━━━━
9. DELIVERY IDEMPOTENCY
━━━━━━━━━━━━━━━━━━━━
Telegram product delivery must be idempotent.
If the payment webhook or delivery worker runs multiple times:
Do not send the same product multiple times unintentionally.
Do not create duplicate delivery records.
Do not mark delivery successful before Telegram confirms the send operation.
Use the existing order/delivery idempotency mechanisms if available.
If delivery fails:
Record the failure.
Keep the order/payment state correct.
Make the delivery safely retryable.
Do not falsely report successful delivery.
━━━━━━━━━━━━━━━━━━━━
10. TELEGRAM WEBHOOK
━━━━━━━━━━━━━━━━━━━━
Reuse the existing Telegram webhook.
Do NOT create a second webhook system.
The webhook must:
Validate the existing webhook secret.
Safely parse Telegram updates.
Handle /start <token> linking requests.
Obtain the sender’s Telegram chat_id from the verified Telegram update.
Validate the one-time linking token server-side.
Associate the Telegram chat_id with the correct customer.
Consume the token.
Return safe responses.
Do not trust Telegram identifiers supplied by the website.
Preserve all existing Telegram bot functionality.
━━━━━━━━━━━━━━━━━━━━
11. RECONNECT / DISCONNECT
━━━━━━━━━━━━━━━━━━━━
Support safe reconnection.
If a customer reconnects Telegram:
Generate a new one-time token.
Do not reuse an old token.
Replace/update the customer’s linked Telegram destination only after successful verification through Telegram.
Invalidate previous pending linking tokens.
If the existing application already has a disconnect mechanism, preserve it.
If adding disconnect functionality is necessary, make it safe and require the authenticated customer.
━━━━━━━━━━━━━━━━━━━━
12. ADMIN TELEGRAM DIAGNOSTICS
━━━━━━━━━━━━━━━━━━━━
Inside the existing admin Telegram/settings area, show safe diagnostics such as:
Bot Username
Configuration status
Webhook status, if available
Number of customers with linked Telegram accounts
Recent Telegram delivery status
Failed Telegram deliveries
Pending/retryable deliveries
NEVER display:
Telegram Bot Token
Webhook secret
Other private secrets
Use masked values if any secret-related diagnostic is absolutely necessary.
━━━━━━━━━━━━━━━━━━━━
13. ERROR HANDLING
━━━━━━━━━━━━━━━━━━━━
Handle these cases gracefully:
Telegram bot username is not configured.
Telegram bot is unavailable.
Linking token expired.
Linking token already used.
Invalid linking token.
Customer is not authenticated.
Customer has no linked Telegram account.
Telegram API error.
Telegram chat is unavailable.
Customer blocked the bot.
Product delivery fails.
Duplicate webhook/update.
Duplicate payment event.
Temporary Telegram API failure.
Never expose stack traces, secrets, tokens, database errors, or internal implementation details to customers.
Show clear user-friendly messages.
━━━━━━━━━━━━━━━━━━━━
14. MULTI-LANGUAGE UI
━━━━━━━━━━━━━━━━━━━━
Use the EXISTING i18n/translation system.
Do NOT create another translation system.
Add all new Telegram UI text to the existing translation architecture.
Support the existing storefront languages.
Translations must cover:
Telegram Bot
Connect Telegram
Telegram connected
Reconnect Telegram
Open Telegram Bot
Telegram delivery
Telegram unavailable
Telegram connection expired
Invalid Telegram connection
Telegram connection successful
Telegram delivery failed
Telegram delivery pending
Telegram delivery successful
Respect existing RTL/LTR behavior.
━━━━━━━━━━━━━━━━━━━━
15. PRIVACY + SECURITY
━━━━━━━━━━━━━━━━━━━━
Treat Telegram chat_id as sensitive account-linking information.
Do not expose it in URLs.
Do not expose it in browser-accessible public API responses unless strictly necessary.
Do not put it into logs unnecessarily.
Do not expose Bot Token or webhook secrets.
Prevent IDOR vulnerabilities.
Every customer-facing Telegram operation must verify the authenticated customer on the server.
Admin diagnostics must require existing admin authorization.
Do not weaken existing authentication, authorization, CSRF, webhook, rate limiting, or security protections.
━━━━━━━━━━━━━━━━━━━━
16. PRESERVE EXISTING SYSTEMS
━━━━━━━━━━━━━━━━━━━━
Do NOT replace the existing:
Telegram bot architecture
Telegram webhook
Payment system
Order system
Product delivery system
Authentication system
Customer system
Admin authorization
Database architecture
unless a change is strictly required to implement this integration.
Reuse existing functions/services/helpers whenever possible.
Do not duplicate business logic.
━━━━━━━━━━━━━━━━━━━━
17. PRODUCTION REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━
The implementation must be suitable for production deployment on the existing 2 GB RAM VPS target.
Avoid unnecessary dependencies.
Do not introduce a large framework or service for a simple Telegram linking flow.
Use the existing stack and architecture.
Use secure server-side cryptographic token generation.
Use proper database indexes/constraints where appropriate.
Ensure migrations are safe.
━━━━━━━━━━━━━━━━━━━━
18. VALIDATION
━━━━━━━━━━━━━━━━━━━━
After implementation, run the appropriate validation.
At minimum:
npx tsc --noEmit
npx prisma validate
npx next build
Also run the existing test suite if available.
Test the Telegram flow end-to-end as far as the available environment allows:
A. Admin configures:
@VexoraBot
B. Authenticated customer selects Telegram delivery.
C. Customer clicks Connect Telegram.
D. Server generates a secure one-time token.
E. Deep link is generated correctly.
F. Telegram /start <token> reaches the existing webhook.
G. Token is validated.
H. Telegram chat_id is associated with the correct customer.
I. Token becomes unusable after consumption.
J. Customer sees:
Telegram connected ✓
K. Customer completes a successful payment.
L. Server verifies the order/payment.
M. Product is delivered to the verified Telegram chat_id.
N. Repeated payment/webhook processing does NOT cause unintended duplicate delivery.
O. Failed Telegram delivery is recorded and safely retryable.
Also test:
Expired token.
Invalid token.
Reused token.
Wrong customer attempting to use a token.
Unauthenticated request.
Missing bot username.
Telegram API failure.
Existing webhook secret verification.
Existing non-Telegram checkout flow.
━━━━━━━━━━━━━━━━━━━━
19. FINAL REPORT
━━━━━━━━━━━━━━━━━━━━
After completing the work, report:
Files changed.
Database/schema changes.
Migration name.
Telegram bot configuration location.
Customer Telegram linking flow.
Delivery flow.
Security protections added.
Tests executed.
Exact TypeScript result.
Exact Prisma validation result.
Exact production build result.
Any known limitations.
Do not claim “100% bug-free”.
If something could not be tested because the real Telegram Bot/API credentials or external webhook environment are unavailable, clearly state that limitation.
IMPORTANT FINAL RULE:
Do not modify unrelated features.
Keep the implementation minimal, secure, production-ready, and fully integrated with the existing Vexora Telegram/order/payment architecture.