Telegram Bot Administration - JOIP Web Application

Overview

The JOIP platform integrates with Telegram to provide users with bot interactions, notifications, and payment processing. The Telegram admin panel provides tools for monitoring bot health, configuring messages, and managing webhooks.

Prerequisites

To use the Telegram integration, configure these environment variables:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_BOT_USERNAME=your_bot_username
TELEGRAM_WEBHOOK_SECRET=your_webhook_secret
TELEGRAM_PREMIUM_CHANNEL_ID=@your_channel_id  # Optional

The bot must be created via @BotFather before configuration.

Bot Health Monitoring

Access the bot health dashboard at:

GET /api/admin/telegram/health

Health Metrics

Bot Identity

Bot username
Bot user ID
Is bot verified
Can join groups
Can read all messages

Webhook Status

Webhook URL configured
Pending update count
Last error timestamp
Last error message

Command Configuration

Required commands configured
Command count
Command list

Channel Status

Premium channel linked
Channel member count
Bot permissions in channel

Health Check Response

{
  "enabled": true,
  "configured": true,
  "botInfo": {
    "id": 123456789,
    "username": "joip_bot",
    "firstName": "JOIP",
    "canJoinGroups": true,
    "canReadAllGroupMessages": false
  },
  "webhookInfo": {
    "url": "https://app.joip.io/api/telegram/webhook",
    "hasCustomCertificate": false,
    "pendingUpdateCount": 0,
    "lastErrorDate": null,
    "lastErrorMessage": null,
    "maxConnections": 40,
    "allowedUpdates": ["message", "callback_query", "pre_checkout_query"]
  },
  "commands": [
    { "command": "start", "description": "Start using JOIP" },
    { "command": "credits", "description": "Check credit balance" },
    { "command": "link", "description": "Link Telegram account" },
    { "command": "buy", "description": "Purchase credits" }
  ]
}

Webhook Configuration

Sync Webhook Settings

Automatically configure webhook and commands:

POST /api/admin/telegram/sync

This endpoint:

Sets the webhook URL to production endpoint
Configures required bot commands
Validates webhook connectivity
Returns updated health status

Response:

{
  "success": true,
  "webhookUrl": "https://app.joip.io/api/telegram/webhook",
  "commands": ["start", "credits", "link", "buy", "help"],
  "health": { /* health status */ }
}

Required Webhook Updates

The bot is configured to receive these update types:

const REQUIRED_TELEGRAM_WEBHOOK_UPDATES = [
  'message',           // User messages
  'callback_query',    // Inline button clicks
  'pre_checkout_query' // Payment verification
];

Bot Commands

The following commands must be configured:

Command	Description	Handler
`/start`	Initialize bot interaction	Welcome message with app link
`/credits`	Check credit balance	Display current balance
`/link`	Link Telegram to JOIP account	OAuth flow initiation
`/buy`	Purchase credits	Payment menu
`/help`	Get help information	Command list and support

Command Configuration

Commands are automatically synced via:

await setTelegramCommands([
  { command: 'start', description: 'Start using JOIP' },
  { command: 'credits', description: 'Check credit balance' },
  { command: 'link', description: 'Link Telegram account' },
  { command: 'buy', description: 'Purchase credits' },
  { command: 'help', description: 'Get help' }
]);

Bot Message Management

Admins can customize bot messages via the Messages section.

Available Messages

Access the message list:

GET /api/admin/telegram/messages

Message Types:

Welcome Message

Sent when user sends /start commandKey: welcomeVariables:

{username} - User’s Telegram username or “there”

Credits Balance

Sent when user checks balance with /creditsKey: credits_balanceVariables:

{credits} - User’s current credit balance

Link Account

Instructions for linking Telegram to JOIP accountKey: link_accountVariables:

{link_url} - Deep link to OAuth flow

Payment Success

Confirmation after successful credit purchaseKey: payment_successVariables:

{credits} - Credits purchased
{amount} - Amount paid (formatted)

Payment Failed

Notification when payment failsKey: payment_failedVariables:

{reason} - Failure reason

Edit Message Content

Update a bot message:

PATCH /api/admin/telegram/messages/:key
{
  "content": "Welcome to JOIP, {username}! 🎉",
  "parseMode": "HTML"  // Optional: HTML, Markdown, MarkdownV2
}

Message editing requires acquiring a lock to prevent concurrent edits. Locks are automatically released after update.

Message Locking

Prevents simultaneous edits by multiple admins:

// Acquire lock
POST /api/admin/telegram/messages/:key/lock

// Release lock
DELETE /api/admin/telegram/messages/:key/lock

Lock status includes:

Admin user ID who locked
Admin email
Lock timestamp
Auto-expires after 10 minutes

Message History

View edit history for a message:

GET /api/admin/telegram/messages/:key/history

Returns up to 50 previous versions with:

Content and parse mode
Editor user ID
Edit timestamp
Change type (update, rollback, reset)

Rollback Message

Restore a previous message version:

POST /api/admin/telegram/messages/:key/rollback/:historyId

Reset to Default

Restore original message template:

POST /api/admin/telegram/messages/:key/reset

Test Message Delivery

Admins can test message delivery to their own Telegram account:

POST /api/admin/telegram/messages/:key/test

Requirements:

Admin must have linked Telegram account
users.telegramId must be set
Rate limit: 10 messages per minute per admin

Example Response:

{
  "success": true
}

Test messages are sent with placeholder variable values (e.g., {credits} = “25”).

Premium Channel Management

If a premium channel is configured, admins can:

View Channel Status

GET /api/admin/telegram/channel/status

Response:

{
  "channelInfo": {
    "id": -1001234567890,
    "title": "JOIP Premium",
    "username": "joip_premium",
    "type": "channel"
  },
  "stats": {
    "memberCount": 150
  },
  "permissions": {
    "canPostMessages": true,
    "canEditMessages": true,
    "canDeleteMessages": true,
    "canInviteUsers": true
  }
}

View Channel Members

GET /api/admin/telegram/channel/users

Query Parameters:

page (number) - Page number (default: 1)
limit (number) - Results per page (default: 20, max: 100)
status (string) - Filter: all, member, not_member
search (string) - Search by email/name

Response:

{
  "users": [
    {
      "id": "user-123",
      "email": "user@example.com",
      "telegramId": 123456789,
      "telegramUsername": "john_doe",
      "telegramLinkedAt": "2024-01-15T10:30:00Z",
      "telegramChannelMember": true
    }
  ],
  "total": 150,
  "page": 1,
  "hasMore": true
}

Bulk Invite Users

Invite multiple users to the premium channel:

POST /api/admin/telegram/channel/invite
{
  "userIds": ["user-123", "user-456"]
}

Payment Integration

The Telegram bot supports payment processing via Telegram Payments.

Configure Payment Provider

Set up via environment variables:

TELEGRAM_PAYMENT_PROVIDER_TOKEN=your_provider_token

Payment Flow

User sends /buy command
Bot presents credit package options (inline keyboard)
User selects package
Bot creates invoice via createInvoiceLink()
User completes payment in Telegram
Bot receives pre_checkout_query
Bot validates and answers with answerPreCheckoutQuery()
Telegram processes payment
Bot receives successful payment notification
Credits are added to user account
Bot sends payment success message

Invoice Creation

const invoiceLink = await createTelegramInvoiceLink({
  title: '100 JOIP Credits',
  description: 'Purchase 100 credits for JOIP platform',
  payload: JSON.stringify({ userId, packageId }),
  currency: 'USD',
  prices: [{ label: '100 Credits', amount: 500 }] // $5.00 in cents
});

Webhook Security

Webhook requests are verified using the secret token:

const isValid = verifyWebhookSecret(
  req.headers['x-telegram-bot-api-secret-token'],
  process.env.TELEGRAM_WEBHOOK_SECRET
);

All webhook endpoints reject requests with invalid secret tokens (403 Forbidden).

Rate Limiting

Telegram webhook endpoints have specific rate limits:

const createTelegramWebhookLimiter = () => rateLimit({
  windowMs: 1000,           // 1 second
  max: 30,                  // 30 requests per second
  message: 'Too many webhook requests'
});

Best Practices

Message Management

Test Before Deployment - Always test messages before making them live
Use Variables - Leverage message variables for personalization
Parse Mode - Use HTML for better formatting control
Lock Messages - Acquire locks before editing to prevent conflicts
Review History - Check message history before rollbacks

Channel Management

Regular Monitoring - Check channel status and member count weekly
Permission Verification - Ensure bot has necessary channel permissions
Member Sync - Periodically sync member status with database
Invite Validation - Verify user tier before bulk invites

Security

Webhook Secret - Use strong, unique webhook secret
Token Protection - Never expose bot token in client code
Rate Limiting - Monitor webhook rate limits
Input Validation - Validate all user inputs from Telegram

Troubleshooting

Common Issues

Webhook Not Receiving Updates

Verify webhook URL is accessible publicly
Check webhook secret is configured correctly
Review Telegram webhook info for errors: GET /api/admin/telegram/health
Ensure SSL certificate is valid

Bot Commands Not Working

Sync commands via POST /api/admin/telegram/sync
Verify commands are registered: GET /api/admin/telegram/health
Check bot has necessary permissions

Messages Not Sending

Verify user has linked Telegram account
Check users.telegramId is populated
Review server logs for API errors
Ensure bot is not blocked by user

Payment Issues

Verify payment provider token is configured
Check invoice creation logs
Ensure currency and amounts are valid
Review pre-checkout query handling

API Reference

Get Bot Health

GET /api/admin/telegram/health

Sync Bot Configuration

POST /api/admin/telegram/sync

Get Bot Messages

GET /api/admin/telegram/messages

Get Specific Message

GET /api/admin/telegram/messages/:key

Update Message

PATCH /api/admin/telegram/messages/:key
Content-Type: application/json

{
  "content": "New message content",
  "parseMode": "HTML"
}

Lock Message

POST /api/admin/telegram/messages/:key/lock

Test Message

POST /api/admin/telegram/messages/:key/test

​Overview

​Prerequisites

​Bot Health Monitoring

​Health Metrics

Bot Identity

Webhook Status

Command Configuration

Channel Status

​Health Check Response

​Webhook Configuration

​Sync Webhook Settings

​Required Webhook Updates

​Bot Commands

​Command Configuration

​Bot Message Management

​Available Messages

​Edit Message Content

​Message Locking

​Message History

​Rollback Message

​Reset to Default

​Test Message Delivery

​Premium Channel Management

​View Channel Status

​View Channel Members

​Bulk Invite Users

​Payment Integration

​Configure Payment Provider

​Payment Flow

​Invoice Creation

​Webhook Security

​Rate Limiting

​Best Practices

​Message Management

​Channel Management

​Security

​Troubleshooting

​Common Issues

​API Reference

​Get Bot Health

​Sync Bot Configuration

​Get Bot Messages

​Get Specific Message

​Update Message

​Lock Message

​Test Message

Overview

Prerequisites

Bot Health Monitoring

Health Metrics

Health Check Response

Webhook Configuration

Sync Webhook Settings

Required Webhook Updates

Bot Commands

Command Configuration

Bot Message Management

Available Messages

Edit Message Content

Message Locking

Message History

Rollback Message

Reset to Default

Test Message Delivery

Premium Channel Management

View Channel Status

View Channel Members

Bulk Invite Users

Payment Integration

Configure Payment Provider

Payment Flow

Invoice Creation

Webhook Security

Rate Limiting

Best Practices

Message Management

Channel Management

Security

Troubleshooting

Common Issues

API Reference

Get Bot Health

Sync Bot Configuration

Get Bot Messages

Get Specific Message

Update Message

Lock Message

Test Message