I'm a Job seeker Book demo Try for free

Telegram Integration - User Stories & Planning

Updated March 2, 2026

Telegram Integration - User Stories & Planning

Overview

A platform feature that enables:

  1. User Notifications - Route platform notifications (like Slack/Email) to users via Telegram
  2. Content Publishing - Distribute vacancies and posts to Telegram channels/groups

Technical Decisions

Decision Choice Rationale
Bot Strategy Platform shared bot Simplest approach, single bot for all clients
User Connection Bot deep link + QR code Both options for flexibility
Feature Flag :telegram_integration Per-client rollout control
Notification Parity Same as Slack/Email Users choose which notifications go to Telegram
Initial Content Format Simple text Rich formatting in v2

MVP Scope (v1)

Feature 1: User Notification Connection

Goal: Users can connect their Telegram account to receive platform notifications via the Marmend bot.

Flow:

  1. User goes to Profile → Notification Settings
  2. Sees "Connect Telegram" section with:
    • Deep link button (t.me/MarmendBot?start=<TOKEN>)
    • QR code (same link encoded)
  3. User clicks/scans → Opens Telegram → Starts chat with Marmend bot
  4. Bot receives /start <TOKEN>, validates token, stores telegram_chat_id for user
  5. User sees "Connected" status in platform
  6. User can now enable/disable Telegram for each notification category (same UI pattern as Slack/Email)

Notification Categories (same as existing):

  • Recruitment: New candidate, candidate updates, vacancies
  • Company account: Subscription
  • Team management: Probation, name changes
  • Leave requests
  • Events/reminders: Birthdays, meetings, reviews

Feature 2: Vacancy/Content Publishing

Goal: Publish vacancies and posts from platform to Telegram channels.

Publishing Targets:

  1. Marmend Global Channel - All platform vacancies (opt-in per client)
  2. Client Company Channel - Each client can register their company's Telegram channel
  3. Ad-hoc Channels - User specifies channel when creating post

Flow:

  1. Admin goes to Company Settings → Integrations → Telegram
  2. Registers company channel(s) by adding Marmend bot as admin
  3. When creating/viewing a vacancy, user clicks "Share to Telegram"
  4. Selects target channel(s)
  5. Previews simple text post
  6. Confirms → Marmend bot posts to selected channels

Post Format (v1) - Simple text:

📢 New Vacancy: Senior Developer

Company: TechCorp
Location: Kyiv, Ukraine
Type: Full-time

Apply here: https://marmend.com/v/abc123

Out of Scope (v1)

  • Epic 6: Receive & Monitor (incoming messages, comments)
  • AI-generated posts (US-3.2)
  • Post templates (US-3.3)
  • Scheduled posts (US-3.4)
  • Edit/delete published posts
  • Engagement metrics (views, forwards)
  • Destination lists/groups
  • Rich formatting (buttons, images)

Roadmap (v2+)

Content Formatting Enhancements

  • Rich text: Bold, italic, links, code blocks
  • Media attachments: Company logo, vacancy images
  • Interactive buttons: "Apply Now" inline button
  • Styled templates: Pre-designed vacancy card layouts

Post Lifecycle Management

  • Edit posts: Update Telegram message when vacancy is edited
  • Delete posts: Remove from Telegram when vacancy is closed/deleted
  • Post history: Track what was posted where and when

Advanced Distribution

  • Destination lists: Group channels into named lists (e.g., "Marketing Channels")
  • Scheduled posts: Queue posts for future delivery
  • Bulk distribution: Send to multiple channels with rate limiting

AI Features

  • AI-generated posts: Generate post text from vacancy details
  • Tone/style selection: Professional, casual, engaging
  • Multi-language: Auto-translate posts

Analytics

  • View counts: Track post views (where Telegram provides data)
  • Forward counts: Track shares
  • Click tracking: UTM parameters for apply links

Receiving & Monitoring (Epic 6)

  • Comment monitoring: See replies to posts in platform
  • Reply from platform: Respond to comments without opening Telegram
  • Incoming message routing: Forward relevant messages to platform inbox

Telegram API Capabilities (for reference)

The Telegram Bot API supports:

  • sendMessage - Text with markdown/HTML formatting
  • sendPhoto, sendDocument, sendVideo - Media attachments
  • InlineKeyboardMarkup - Interactive buttons
  • editMessageText - Edit existing messages
  • deleteMessage - Delete messages
  • getChat - Get channel/group info
  • getChatMemberCount - Get subscriber count
  • forwardMessage - Forward messages between chats

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Marmend Platform                        │
│                                                                 │
│  ┌─────────────────┐   ┌─────────────────┐   ┌───────────────┐  │
│  │  User Settings  │   │  Vacancy/Post   │   │  Notification │  │
│  │  (Connect TG)   │   │  Editor         │   │  Service      │  │
│  └────────┬────────┘   └────────┬────────┘   └───────┬───────┘  │
│           │                     │                    │          │
│           └─────────────────────┼────────────────────┘          │
│                                 │                               │
│                    ┌────────────▼────────────┐                  │
│                    │   Telegram Integration  │                  │
│                    │   Service               │                  │
│                    │   • User connections    │                  │
│                    │   • Channel registry    │                  │
│                    │   • Message sending     │                  │
│                    └────────────┬────────────┘                  │
│                                 │                               │
└─────────────────────────────────┼───────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Telegram Bot API                             │
│                    (Marmend Shared Bot)                         │
│                                                                 │
│    ┌──────────┐   ┌──────────┐   ┌──────────────────────────┐   │
│    │  User    │   │  Client  │   │  Marmend Global          │   │
│    │  DMs     │   │  Channels│   │  Channel                 │   │
│    └──────────┘   └──────────┘   └──────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Data Model (Proposed)

TelegramUserConnection

Links platform users to their Telegram chat for notifications.

schema "telegram_user_connections" do
  field :user_uuid, :binary_id        # FK to users
  field :telegram_chat_id, :integer   # Telegram chat ID for DMs
  field :telegram_username, :string   # Optional, for display
  field :connected_at, :utc_datetime
  field :connection_token, :string    # One-time token for /start
  field :token_expires_at, :utc_datetime

  timestamps()
end

TelegramChannel

Registered channels where clients can publish.

schema "telegram_channels" do
  field :client_uuid, :binary_id      # FK to clients
  field :telegram_chat_id, :integer   # Channel/group chat ID
  field :channel_username, :string    # @username
  field :channel_title, :string       # Display name
  field :channel_type, :string        # "channel" | "group" | "supergroup"
  field :is_verified, :boolean        # Bot confirmed as admin
  field :is_default, :boolean         # Default for this client

  timestamps()
end

TelegramPost

Track published posts.

schema "telegram_posts" do
  field :client_uuid, :binary_id
  field :vacancy_uuid, :binary_id     # Optional, if vacancy-related
  field :telegram_channel_id, :binary_id  # FK to telegram_channels
  field :telegram_message_id, :integer    # Telegram's message ID
  field :content, :text
  field :status, :string              # "sent" | "failed" | "deleted"
  field :posted_by_uuid, :binary_id   # User who triggered post
  field :posted_at, :utc_datetime
  field :error_message, :string

  timestamps()
end

User Stories (Original + Updated)

Epic 1: Account Connection (MVP - Simplified)

US-1.1: Connect Telegram for Notifications

As a platform user I want to connect my Telegram account to receive notifications So that I get platform updates directly in Telegram

Acceptance Criteria:

  • I see a "Connect Telegram" button with deep link and QR code
  • Clicking/scanning opens Telegram with Marmend bot
  • After starting chat, my account shows as "Connected"
  • I can disconnect at any time
  • I can choose which notifications go to Telegram (same options as Slack/Email)

US-1.2: Register Company Channel

As a company admin I want to register my company's Telegram channel So that we can publish vacancies and announcements there

Acceptance Criteria:

  • I can add Marmend bot as admin to my channel
  • Platform detects and lists channels where bot is admin
  • I can set a default channel for publishing
  • I can remove channels from the list

Epic 2: Manage Distribution Targets (v2)

Moved to roadmap - v1 uses simple channel selection

Epic 3: Create & Edit Posts (MVP - Simplified)

US-3.1: Share Vacancy to Telegram

As a recruiter I want to share a vacancy to Telegram channels So that I can reach candidates on Telegram

Acceptance Criteria:

  • I see "Share to Telegram" button on vacancy page
  • I can select which channel(s) to post to
  • I see a preview of the simple text post
  • I can confirm and send
  • I see success/failure confirmation

Epic 4: Send & Distribute (MVP - Simplified)

US-4.1: Send Notification via Telegram

As a platform user with Telegram connected I want to receive platform notifications in Telegram So that I stay informed without checking email

Acceptance Criteria:

  • Notifications I've enabled for Telegram arrive as DMs from Marmend bot
  • Message format is clear and includes relevant details
  • Messages include links back to platform where appropriate

US-4.2: Post to Company Channel

As a company admin or recruiter I want to post content to my company's Telegram channel So that followers see our updates

Acceptance Criteria:

  • Bot posts on behalf of company
  • Post appears in channel immediately
  • I receive confirmation in platform

Epic 5: Track & Analyze (v2)

Moved to roadmap

Epic 6: Receive & Monitor (v2+)

Moved to roadmap

Priority Summary

Priority Feature Description
P0 User Telegram Connection Deep link + QR, store chat_id
P0 Notification Routing Send notifications via Telegram DM
P0 Channel Registration Admin registers company channel
P0 Vacancy Sharing Manual "Share to Telegram"
P1 Notification Preferences Granular enable/disable per category
P1 Multiple Channels Support multiple channels per client
P2 Marmend Global Channel Aggregate vacancies from all clients
v2 Rich Formatting Buttons, images, styled posts
v2 Post Lifecycle Edit/delete posts
v2 Analytics View counts, tracking
v2+ Receive & Monitor Comments, incoming messages

Implementation Notes

Feature Flag

# lib/marmend/feature_flags.ex
%Definition{key: :telegram_integration, description: "Enables Telegram integration for notifications and publishing"}

Environment Variables

TELEGRAM_BOT_TOKEN=<bot token from BotFather>
TELEGRAM_BOT_USERNAME=MarmendBot
TELEGRAM_WEBHOOK_SECRET=<random secret for webhook validation>

Webhook vs Polling

For MVP, use long polling (getUpdates) - simpler setup, no SSL certificate needed for development. For production, switch to webhooks for better performance and real-time updates.