Telegram Integration API

The Telegram Integration API enables users to connect their accounts with Telegram for receiving notifications and support communication. This feature provides a seamless way to receive updates and communicate with support through Telegram.

Overview

The API provides several key operations:

• Register Telegram Account
• Send/Receive Support Messages
• Manage Notification Preferences
• Test Connection Status
• Admin Support Interface

Flow Diagram

sequenceDiagram
    participant User
    participant Bot
    participant API
    participant Admin
    participant Database

    User->>Bot: 1. Start chat (/start)
    Bot->>Database: Store chat ID
    Bot-->>User: Welcome message
    User->>API: 2. Register username
    API->>Database: Link account
    API->>Bot: Send verification
    Bot-->>User: Verify connection
    User->>Bot: 3. Send support message
    Bot->>Database: Store message
    Bot->>Admin: Forward to support
    Admin->>Bot: Reply to message
    Bot-->>User: Deliver reply

API Reference

Register Telegram Account

Links a Telegram username with the user's account.

mutation RegisterTelegram($registration: TelegramRegistration!) {
  registerTelegram(registration: $registration) {
    success
    message
  }
}

Variables

{
  "registration": {
    "username": "user_telegram_name",
    "verificationCode": "123456"
  }
}

Test Connection

Tests the Telegram connection for a user.

mutation TestTelegramConnection($chatId: String!) {
  testTelegramConnection(chatId: $chatId)
}

Update Telegram Info

Updates a user's Telegram information.

mutation UpdateTelegramInfo($username: String!, $chatId: String!) {
  updateTelegramInfo(username: $username, chatId: $chatId) {
    telegramUsername
    telegramChatId
  }
}

Send Notification

Sends a Telegram notification to a user (Admin only).

mutation SendTelegramNotification(
  $userId: Int
  $username: String
  $message: String!
) {
  sendTelegramNotification(
    userId: $userId
    username: $username
    message: $message
  )
}

Get Message History

Retrieves message history for a user.

query GetTelegramMessages($userId: ID!, $page: Int, $size: Int) {
  getTelegramMessages(userId: $userId, page: $page, size: $size) {
    id
    message
    timestamp
    direction
    status
    adminUsername
  }
}

Implementation Guide

User Registration Flow

1. User starts bot interaction:

   • Find @OrbVPNbot on Telegram
   • Send /start command
   • Bot stores chat ID

2. Register account:

const response = await client.mutate({
  mutation: gql`
    mutation Register($registration: TelegramRegistration!) {
      registerTelegram(registration: $registration)
    }
  `,
  variables: {
    registration: {
      username: telegramUsername,
      verificationCode: code,
    },
  },
});

3. Test connection:

const testResponse = await client.mutate({
  mutation: gql`
    mutation Test($chatId: String!) {
      testTelegramConnection(chatId: $chatId)
    }
  `,
  variables: {
    chatId: userChatId,
  },
});

Message Types and Status

Type	Status	Description
INCOMING	RECEIVED	Message received from user
OUTGOING	SENT	Message sent to user
INCOMING	READ	Message read by support
OUTGOING	REPLIED	Message replied to by support

Best Practices

1. Validation

   • Verify Telegram username format
   • Validate chat ID
   • Check message length limits
   • Verify user permissions

2. Error Handling

   • Handle connection failures
   • Manage rate limits
   • Process message delivery failures
   • Handle bot errors

3. Security

   • Validate message sources
   • Rate limit message sending
   • Verify admin permissions
   • Protect user privacy

Error Codes

Error Code	Description	Resolution
CHAT_NOT_FOUND	Chat ID not found	Re-initiate bot chat
INVALID_USERNAME	Invalid Telegram username	Check username format
CONNECTION_FAILED	Connection test failed	Verify bot status
RATE_LIMITED	Too many messages	Wait and retry
UNAUTHORIZED	Missing permissions	Check authentication

Rate Limiting

• Message sending: 200 per hour
• User registration: 5 per hour
• Connection tests: 10 per minute
• Admin messages: 100 per hour

Configuration

Example configuration in application.yml:

messaging:
  telegram:
    bot-token: "YOUR_BOT_TOKEN"
    bot-username: "OrbVPNbot"
    admin-group-id: "ADMIN_GROUP_ID"
    rate-limit:
      max-per-hour: 200
      max-per-minute: 20

Security Considerations

• All mutations require authentication
• Admin operations require ADMIN role
• Rate limiting prevents abuse
• Message forwarding respects privacy
• Chat IDs are securely stored
• Bot tokens are environment-specific

Notifications

The system sends Telegram notifications for:

• Account registration confirmation
• Support message received
• Support replies
• System updates
• Subscription changes
• Payment confirmations
• Security alerts

Admin Support Interface

Administrators can:

1. View all user messages
2. Reply to support requests
3. Send broadcast messages
4. Monitor message status
5. View chat histories
6. Manage user connections

Database Schema

CREATE TABLE telegram_messages (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id INT NOT NULL,
    message TEXT NOT NULL,
    timestamp DATETIME NOT NULL,
    direction VARCHAR(20) NOT NULL,
    status VARCHAR(20) NOT NULL,
    admin_username VARCHAR(255),
    FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE TABLE user_telegram_info (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id INT NOT NULL,
    telegram_chat_id VARCHAR(255),
    telegram_username VARCHAR(255),
    FOREIGN KEY (user_id) REFERENCES users(id)
);