From 9634e88e5d5d2e0bac878a2318379482cab10596 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 21:25:31 -0300
Subject: [PATCH 01/35] Add Telegram publishing (backend foundation)

Register Telegram as a platform: Platform/ContentType enum cases, a
platforms.telegram config block (shared bot token via env), TelegramPublisher
(sendMessage / sendPhoto|Video|Document / sendMediaGroup over the Bot API, HTML
parse mode, 4096 limit with long text split off a 1024 caption), wired into the
publisher dispatch. Add a Telegram ContentSanitizer branch (Telegram-allowed
HTML + ampersand escaping), MediaOptimizer/profile-url/factory support, and the
TelegramPublishException. Tests cover text, single media, album, long-text split,
overflow, API errors, private-channel URLs, and sanitization.
---
 app/Enums/PostPlatform/ContentType.php        |   9 +
 app/Enums/SocialAccount/Platform.php          |  12 ++
 .../Social/TelegramPublishException.php       |  68 +++++++
 app/Jobs/PublishToSocialPlatform.php          |   4 +-
 app/Models/SocialAccount.php                  |   1 +
 app/Services/Media/MediaOptimizer.php         |   6 +
 app/Services/Social/ContentSanitizer.php      |  26 +++
 app/Services/Social/TelegramPublisher.php     | 186 ++++++++++++++++++
 config/trypost.php                            |   9 +
 database/factories/SocialAccountFactory.php   |  17 ++
 .../Services/Social/ContentSanitizerTest.php  |  18 ++
 .../Services/Social/TelegramPublisherTest.php | 171 ++++++++++++++++
 12 files changed, 526 insertions(+), 1 deletion(-)
 create mode 100644 app/Exceptions/Social/TelegramPublishException.php
 create mode 100644 app/Services/Social/TelegramPublisher.php
 create mode 100644 tests/Feature/Services/Social/TelegramPublisherTest.php

diff --git a/app/Enums/PostPlatform/ContentType.php b/app/Enums/PostPlatform/ContentType.php
index 6fdf0e3d..4c3214ff 100644
--- a/app/Enums/PostPlatform/ContentType.php
+++ b/app/Enums/PostPlatform/ContentType.php
@@ -50,6 +50,9 @@ enum ContentType: string
     // Mastodon
     case MastodonPost = 'mastodon_post';
 
+    // Telegram
+    case TelegramPost = 'telegram_post';
+
     /**
      * AI generation format for an Instagram carousel. Not a content type —
      * carousel posts are persisted as InstagramFeed.
@@ -77,6 +80,7 @@ public function label(): string
             self::PinterestCarousel => 'Carousel',
             self::BlueskyPost => 'Post',
             self::MastodonPost => 'Post',
+            self::TelegramPost => 'Post',
         };
     }
 
@@ -99,6 +103,7 @@ public function platform(): SocialPlatform
             self::PinterestPin, self::PinterestVideoPin, self::PinterestCarousel => SocialPlatform::Pinterest,
             self::BlueskyPost => SocialPlatform::Bluesky,
             self::MastodonPost => SocialPlatform::Mastodon,
+            self::TelegramPost => SocialPlatform::Telegram,
         };
     }
 
@@ -167,6 +172,7 @@ public function maxMediaCount(): int
             self::PinterestCarousel => 5,
             self::BlueskyPost => 4,
             self::MastodonPost => 4,
+            self::TelegramPost => 10,
         };
     }
 
@@ -186,6 +192,7 @@ public function supportsVideo(): bool
             self::PinterestPin, self::PinterestCarousel => false,
             self::BlueskyPost => true,
             self::MastodonPost => true,
+            self::TelegramPost => true,
         };
     }
 
@@ -222,6 +229,7 @@ public function requiresMedia(): bool
             self::ThreadsPost => false,
             self::BlueskyPost => false,
             self::MastodonPost => false,
+            self::TelegramPost => false,
             self::FacebookPost => false,
             self::InstagramFeed => false,
             default => true,
@@ -304,6 +312,7 @@ public static function defaultFor(SocialPlatform $platform): self
             SocialPlatform::Pinterest => self::PinterestPin,
             SocialPlatform::Bluesky => self::BlueskyPost,
             SocialPlatform::Mastodon => self::MastodonPost,
+            SocialPlatform::Telegram => self::TelegramPost,
         };
     }
 }
diff --git a/app/Enums/SocialAccount/Platform.php b/app/Enums/SocialAccount/Platform.php
index f94112dc..25337147 100644
--- a/app/Enums/SocialAccount/Platform.php
+++ b/app/Enums/SocialAccount/Platform.php
@@ -20,6 +20,7 @@ enum Platform: string
     case Pinterest = 'pinterest';
     case Bluesky = 'bluesky';
     case Mastodon = 'mastodon';
+    case Telegram = 'telegram';
 
     public function label(): string
     {
@@ -36,6 +37,7 @@ public function label(): string
             self::Pinterest => 'Pinterest',
             self::Bluesky => 'Bluesky',
             self::Mastodon => 'Mastodon',
+            self::Telegram => 'Telegram',
         };
     }
 
@@ -53,6 +55,7 @@ public function color(): string
             self::Pinterest => '#E60023',
             self::Bluesky => '#0085FF',
             self::Mastodon => '#6364FF',
+            self::Telegram => '#26A5E4',
         };
     }
 
@@ -69,6 +72,7 @@ public function allowedMediaTypes(): array
             self::Pinterest => [MediaType::Image, MediaType::Video],
             self::Bluesky => [MediaType::Image, MediaType::Video],
             self::Mastodon => [MediaType::Image, MediaType::Video],
+            self::Telegram => [MediaType::Image, MediaType::Video],
         };
     }
 
@@ -85,6 +89,7 @@ public function maxImages(): int
             self::Pinterest => 5,
             self::Bluesky => 4,
             self::Mastodon => 4,
+            self::Telegram => 10,
         };
     }
 
@@ -107,6 +112,8 @@ public function maxImages(): int
      *  - Pinterest pin description: 800 (title is 100, not modeled here)
      *  - Bluesky: 300 graphemes
      *  - Mastodon: 500 default; instances may be higher (we stay conservative)
+     *  - Telegram: 4096 for a text message (media captions are capped at 1024,
+     *    handled in the publisher by sending long text as its own message)
      */
     public function maxContentLength(): int
     {
@@ -121,6 +128,7 @@ public function maxContentLength(): int
             self::Pinterest => 800,
             self::Bluesky => 300,
             self::Mastodon => 500,
+            self::Telegram => 4096,
         };
     }
 
@@ -162,6 +170,8 @@ public function recommendedAiContentLength(): int
             // YouTube Shorts — fits within the 100-char title (with " #Shorts"
             // suffix taking 8 chars) so the same string works as title + desc
             self::YouTube => 80,
+            // Telegram channel posts — short announcements read best
+            self::Telegram => 400,
         };
     }
 
@@ -183,6 +193,7 @@ public function requiredPublishScopes(): array
             self::Pinterest => ['pins:write'],
             self::Bluesky => [],
             self::Mastodon => ['write:statuses'],
+            self::Telegram => [],
         };
     }
 
@@ -199,6 +210,7 @@ public function supportsTextOnly(): bool
             self::Pinterest => false,
             self::Bluesky => true,
             self::Mastodon => true,
+            self::Telegram => true,
         };
     }
 
diff --git a/app/Exceptions/Social/TelegramPublishException.php b/app/Exceptions/Social/TelegramPublishException.php
new file mode 100644
index 00000000..26943e1a
--- /dev/null
+++ b/app/Exceptions/Social/TelegramPublishException.php
@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Social;
+
+use Illuminate\Http\Client\Response;
+
+class TelegramPublishException extends SocialPublishException
+{
+    public static function fromApiResponse(mixed $response): static
+    {
+        /** @var Response $response */
+        $status = $response->status();
+        $rawResponse = $response->body();
+        $description = (string) data_get($response->json(), 'description', 'An unknown Telegram error occurred.');
+
+        // 403: the bot was removed or isn't an admin of the channel anymore.
+        if ($status === 403) {
+            return new static(
+                userMessage: 'The bot is not an admin of this channel. Re-add it as an administrator and try again.',
+                category: ErrorCategory::Permission,
+                platformErrorCode: (string) $status,
+                rawResponse: $rawResponse,
+            );
+        }
+
+        // 401: the configured bot token is invalid (operator-level misconfiguration).
+        if ($status === 401) {
+            return new static(
+                userMessage: 'Telegram rejected the bot token. Check the TELEGRAM_BOT_TOKEN configuration.',
+                category: ErrorCategory::Permission,
+                platformErrorCode: (string) $status,
+                rawResponse: $rawResponse,
+            );
+        }
+
+        if ($status === 429) {
+            return new static(
+                userMessage: 'Telegram rate limit reached. Please try again shortly.',
+                category: ErrorCategory::RateLimit,
+                platformErrorCode: (string) $status,
+                rawResponse: $rawResponse,
+            );
+        }
+
+        if ($status >= 500) {
+            return new static(
+                userMessage: 'Telegram is temporarily unavailable. Please try again later.',
+                category: ErrorCategory::ServerError,
+                platformErrorCode: (string) $status,
+                rawResponse: $rawResponse,
+            );
+        }
+
+        return new static(
+            userMessage: $description,
+            category: ErrorCategory::ContentPolicy,
+            platformErrorCode: (string) $status,
+            rawResponse: $rawResponse,
+        );
+    }
+
+    public function platform(): string
+    {
+        return 'telegram';
+    }
+}
diff --git a/app/Jobs/PublishToSocialPlatform.php b/app/Jobs/PublishToSocialPlatform.php
index c040f6f0..e163a90d 100644
--- a/app/Jobs/PublishToSocialPlatform.php
+++ b/app/Jobs/PublishToSocialPlatform.php
@@ -25,6 +25,7 @@
 use App\Services\Social\LinkedInPublisher;
 use App\Services\Social\MastodonPublisher;
 use App\Services\Social\PinterestPublisher;
+use App\Services\Social\TelegramPublisher;
 use App\Services\Social\ThreadsPublisher;
 use App\Services\Social\TikTokPublisher;
 use App\Services\Social\XPublisher;
@@ -221,7 +222,7 @@ private function broadcastStatus(): void
         PostPlatformStatusUpdated::dispatch($this->postPlatform->fresh());
     }
 
-    private function getPublisher(): LinkedInPublisher|LinkedInPagePublisher|XPublisher|TikTokPublisher|YouTubePublisher|FacebookPublisher|InstagramPublisher|ThreadsPublisher|PinterestPublisher|BlueskyPublisher|MastodonPublisher
+    private function getPublisher(): LinkedInPublisher|LinkedInPagePublisher|XPublisher|TikTokPublisher|YouTubePublisher|FacebookPublisher|InstagramPublisher|ThreadsPublisher|PinterestPublisher|BlueskyPublisher|MastodonPublisher|TelegramPublisher
     {
         return match ($this->postPlatform->platform) {
             SocialPlatform::LinkedIn => app(LinkedInPublisher::class),
@@ -235,6 +236,7 @@ private function getPublisher(): LinkedInPublisher|LinkedInPagePublisher|XPublis
             SocialPlatform::Pinterest => app(PinterestPublisher::class),
             SocialPlatform::Bluesky => app(BlueskyPublisher::class),
             SocialPlatform::Mastodon => app(MastodonPublisher::class),
+            SocialPlatform::Telegram => app(TelegramPublisher::class),
         };
     }
 
diff --git a/app/Models/SocialAccount.php b/app/Models/SocialAccount.php
index a49801c4..d1fed6b6 100644
--- a/app/Models/SocialAccount.php
+++ b/app/Models/SocialAccount.php
@@ -125,6 +125,7 @@ protected function profileUrl(): Attribute
                     SocialPlatform::Mastodon => ($username && data_get($this->meta, 'instance'))
                         ? rtrim((string) data_get($this->meta, 'instance'), '/')."/@{$username}"
                         : null,
+                    SocialPlatform::Telegram => $username ? "https://t.me/{$username}" : null,
                     default => null,
                 };
             },
diff --git a/app/Services/Media/MediaOptimizer.php b/app/Services/Media/MediaOptimizer.php
index d473f65f..c17e9469 100644
--- a/app/Services/Media/MediaOptimizer.php
+++ b/app/Services/Media/MediaOptimizer.php
@@ -196,6 +196,12 @@ private function getImageConfig(Platform $platform): array
                 'format' => 'image/jpeg',
                 'quality' => 100,
             ],
+            Platform::Telegram => [
+                'max_width' => 2048,
+                'max_size' => 10 * 1024 * 1024,
+                'format' => 'image/jpeg',
+                'quality' => 100,
+            ],
         };
     }
 }
diff --git a/app/Services/Social/ContentSanitizer.php b/app/Services/Social/ContentSanitizer.php
index f5f73e50..79a3ba0b 100644
--- a/app/Services/Social/ContentSanitizer.php
+++ b/app/Services/Social/ContentSanitizer.php
@@ -13,10 +13,36 @@ public function sanitize(string $content, Platform $platform): string
         return match ($platform) {
             Platform::LinkedIn, Platform::LinkedInPage => $this->convertBoldAndStrip($content),
             Platform::Mastodon => $this->stripUnsafeHtml($content),
+            Platform::Telegram => $this->toTelegramHtml($content),
             default => $this->stripHtml($content),
         };
     }
 
+    /**
+     * Telegram's `parse_mode=HTML` accepts a small tag allowlist and rejects
+     * the rest; bare ampersands must be escaped or the parser errors.
+     */
+    private function toTelegramHtml(string $content): string
+    {
+        // Block elements → newlines (Telegram HTML has no <p>/<br>/<li>).
+        $content = preg_replace('/<p[^>]*>/i', '', $content);
+        $content = str_replace('</p>', "\n", $content);
+        $content = preg_replace('/<br\s*\/?>/i', "\n", $content);
+        $content = preg_replace('/<li[^>]*>/i', '- ', $content);
+        $content = str_replace('</li>', "\n", $content);
+
+        // Normalize to Telegram's tag names, then keep only its allowlist.
+        $content = preg_replace(['/<(\/?)strong>/i', '/<(\/?)em>/i'], ['<$1b>', '<$1i>'], $content);
+        $content = strip_tags($content, ['b', 'i', 'u', 's', 'a', 'code', 'pre']);
+
+        // Escape bare ampersands while leaving existing entities intact.
+        $content = preg_replace('/&(?!(?:amp|lt|gt|quot|#\d+);)/', '&amp;', $content);
+
+        $content = preg_replace("/\n{3,}/", "\n\n", $content);
+
+        return trim($content);
+    }
+
     private function stripHtml(string $content): string
     {
         // Convert <p> tags to newlines
diff --git a/app/Services/Social/TelegramPublisher.php b/app/Services/Social/TelegramPublisher.php
new file mode 100644
index 00000000..24e79e24
--- /dev/null
+++ b/app/Services/Social/TelegramPublisher.php
@@ -0,0 +1,186 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Social;
+
+use App\DataTransferObjects\MediaItem;
+use App\Exceptions\Social\TelegramPublishException;
+use App\Models\PostPlatform;
+use App\Models\SocialAccount;
+use App\Services\Social\Concerns\HasSocialHttpClient;
+use Illuminate\Http\Client\Response;
+use Illuminate\Support\Collection;
+
+class TelegramPublisher
+{
+    use HasSocialHttpClient;
+
+    /**
+     * Telegram caps media captions at 1024 chars (a text-only message allows
+     * 4096). When the post is longer than a caption, the media is sent first and
+     * the full text follows as its own message.
+     */
+    private const CAPTION_LIMIT = 1024;
+
+    private const ALBUM_CHUNK = 10;
+
+    public function publish(PostPlatform $postPlatform): array
+    {
+        $this->validateContentLength($postPlatform);
+
+        $account = $postPlatform->socialAccount;
+        $chatId = (string) data_get($account->meta, 'chat_id');
+
+        $content = $postPlatform->post->content
+            ? app(ContentSanitizer::class)->sanitize($postPlatform->post->content, $postPlatform->platform)
+            : '';
+
+        $media = $postPlatform->post->mediaItems->take(self::ALBUM_CHUNK);
+
+        $messageId = $media->isEmpty()
+            ? $this->sendText($chatId, $content)
+            : $this->sendWithMedia($chatId, $content, $media);
+
+        return [
+            'id' => (string) $messageId,
+            'url' => $this->buildPostUrl($account, $messageId),
+        ];
+    }
+
+    private function sendText(string $chatId, string $text): int
+    {
+        $response = $this->call('sendMessage', [
+            'chat_id' => $chatId,
+            'text' => $text,
+            'parse_mode' => 'HTML',
+        ]);
+
+        return (int) data_get($response->json(), 'result.message_id');
+    }
+
+    private function sendWithMedia(string $chatId, string $content, Collection $media): int
+    {
+        $fitsCaption = mb_strlen($content) <= self::CAPTION_LIMIT;
+        $caption = $fitsCaption ? $content : '';
+
+        $items = $media->map(fn (MediaItem $item) => $this->telegramMedia($item))->values()->all();
+
+        $messageId = count($items) === 1
+            ? $this->sendSingleMedia($chatId, $items[0], $caption)
+            : $this->sendMediaGroup($chatId, $items, $caption);
+
+        // Long text can't ride along as a caption — send it as a follow-up message.
+        if (! $fitsCaption) {
+            $this->sendText($chatId, $content);
+        }
+
+        return $messageId;
+    }
+
+    /**
+     * @param  array{type: string, url: string}  $item
+     */
+    private function sendSingleMedia(string $chatId, array $item, string $caption): int
+    {
+        $method = match ($item['type']) {
+            'photo' => 'sendPhoto',
+            'video' => 'sendVideo',
+            default => 'sendDocument',
+        };
+
+        $response = $this->call($method, [
+            'chat_id' => $chatId,
+            $item['type'] => $item['url'],
+            'caption' => $caption,
+            'parse_mode' => 'HTML',
+        ]);
+
+        return (int) data_get($response->json(), 'result.message_id');
+    }
+
+    /**
+     * @param  array<int, array{type: string, url: string}>  $items
+     */
+    private function sendMediaGroup(string $chatId, array $items, string $caption): int
+    {
+        $firstMessageId = 0;
+
+        foreach (array_chunk($items, self::ALBUM_CHUNK) as $chunkIndex => $chunk) {
+            $group = [];
+
+            foreach ($chunk as $itemIndex => $item) {
+                $entry = [
+                    // Documents can't be mixed into an album; send them as photos/videos only.
+                    'type' => $item['type'] === 'document' ? 'document' : $item['type'],
+                    'media' => $item['url'],
+                ];
+
+                if ($chunkIndex === 0 && $itemIndex === 0 && $caption !== '') {
+                    $entry['caption'] = $caption;
+                    $entry['parse_mode'] = 'HTML';
+                }
+
+                $group[] = $entry;
+            }
+
+            $response = $this->call('sendMediaGroup', [
+                'chat_id' => $chatId,
+                'media' => json_encode($group),
+            ]);
+
+            if ($chunkIndex === 0) {
+                $firstMessageId = (int) data_get($response->json(), 'result.0.message_id');
+            }
+        }
+
+        return $firstMessageId;
+    }
+
+    /**
+     * @return array{type: string, url: string}
+     */
+    private function telegramMedia(MediaItem $media): array
+    {
+        $type = match (true) {
+            $media->isImage() => 'photo',
+            $media->isVideo() => 'video',
+            default => 'document',
+        };
+
+        return ['type' => $type, 'url' => $media->url];
+    }
+
+    private function call(string $method, array $payload): Response
+    {
+        $token = (string) config('trypost.platforms.telegram.bot_token');
+        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
+
+        $response = $this->socialHttp()->post("{$api}/bot{$token}/{$method}", $payload);
+
+        if ($response->failed() || data_get($response->json(), 'ok') !== true) {
+            $this->handleApiError($response);
+        }
+
+        return $response;
+    }
+
+    private function buildPostUrl(SocialAccount $account, int $messageId): string
+    {
+        $username = (string) data_get($account->meta, 'username');
+
+        if ($username !== '') {
+            return "https://t.me/{$username}/{$messageId}";
+        }
+
+        // Private channels: t.me/c/<id without the -100 prefix>/<message_id>.
+        $internalId = preg_replace('/^-100/', '', (string) data_get($account->meta, 'chat_id'));
+
+        return "https://t.me/c/{$internalId}/{$messageId}";
+    }
+
+    private function handleApiError(Response $response): never
+    {
+        throw TelegramPublishException::fromApiResponse($response);
+    }
+}
diff --git a/config/trypost.php b/config/trypost.php
index 2ebdf592..e69f375a 100644
--- a/config/trypost.php
+++ b/config/trypost.php
@@ -153,6 +153,15 @@
             // Default instance used when the account has no `meta.instance` override.
             'default_instance' => env('MASTODON_DEFAULT_INSTANCE', 'https://mastodon.social'),
         ],
+        'telegram' => [
+            'enabled' => env('TELEGRAM_ENABLED', true),
+            // Single shared bot (BotFather). Users add it as admin to their channel.
+            'bot_token' => env('TELEGRAM_BOT_TOKEN'),
+            'bot_username' => env('TELEGRAM_BOT_USERNAME'),
+            'api' => env('TELEGRAM_API', 'https://api.telegram.org'),
+            // Secret-token header Telegram echoes on every webhook call.
+            'webhook_secret' => env('TELEGRAM_WEBHOOK_SECRET'),
+        ],
     ],
 
 ];
diff --git a/database/factories/SocialAccountFactory.php b/database/factories/SocialAccountFactory.php
index c98f924f..e18e27fc 100644
--- a/database/factories/SocialAccountFactory.php
+++ b/database/factories/SocialAccountFactory.php
@@ -137,6 +137,23 @@ public function mastodon(): static
         ]);
     }
 
+    public function telegram(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'platform' => Platform::Telegram,
+            'scopes' => Platform::Telegram->requiredPublishScopes(),
+            'token_expires_at' => null, // the shared bot token never expires
+            'access_token' => '',
+            'refresh_token' => '',
+            'username' => 'mychannel',
+            'meta' => [
+                'chat_id' => '-1001234567890',
+                'username' => 'mychannel',
+                'type' => 'channel',
+            ],
+        ]);
+    }
+
     public function disconnected(): static
     {
         return $this->state(fn (array $attributes) => [
diff --git a/tests/Feature/Services/Social/ContentSanitizerTest.php b/tests/Feature/Services/Social/ContentSanitizerTest.php
index dd508444..4bd97ae4 100644
--- a/tests/Feature/Services/Social/ContentSanitizerTest.php
+++ b/tests/Feature/Services/Social/ContentSanitizerTest.php
@@ -76,3 +76,21 @@
     $result = $sanitizer->sanitize('<p>Check <a href="https://example.com">this</a></p>', Platform::Mastodon);
     expect($result)->toContain('<a href="https://example.com">this</a>');
 });
+
+test('it keeps telegram-allowed html and converts strong/em', function () {
+    $sanitizer = new ContentSanitizer;
+    $result = $sanitizer->sanitize('<p>Hello <strong>world</strong> and <em>you</em></p>', Platform::Telegram);
+    expect($result)->toBe('Hello <b>world</b> and <i>you</i>');
+});
+
+test('it strips disallowed tags but keeps links for telegram', function () {
+    $sanitizer = new ContentSanitizer;
+    $result = $sanitizer->sanitize('<div>see <a href="https://example.com">link</a></div><script>x</script>', Platform::Telegram);
+    expect($result)->toBe('see <a href="https://example.com">link</a>x');
+});
+
+test('it escapes bare ampersands for telegram', function () {
+    $sanitizer = new ContentSanitizer;
+    $result = $sanitizer->sanitize('Tom &amp; Jerry & friends', Platform::Telegram);
+    expect($result)->toBe('Tom &amp; Jerry &amp; friends');
+});
diff --git a/tests/Feature/Services/Social/TelegramPublisherTest.php b/tests/Feature/Services/Social/TelegramPublisherTest.php
new file mode 100644
index 00000000..a1f6094a
--- /dev/null
+++ b/tests/Feature/Services/Social/TelegramPublisherTest.php
@@ -0,0 +1,171 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Enums\PostPlatform\ContentType;
+use App\Enums\SocialAccount\Platform;
+use App\Exceptions\Social\TelegramPublishException;
+use App\Models\Post;
+use App\Models\PostPlatform;
+use App\Models\SocialAccount;
+use App\Models\User;
+use App\Models\Workspace;
+use App\Services\Social\TelegramPublisher;
+use Illuminate\Support\Facades\Http;
+
+beforeEach(function () {
+    config(['trypost.platforms.telegram.bot_token' => 'TESTTOKEN']);
+
+    $this->user = User::factory()->create();
+    $this->workspace = Workspace::factory()->create(['user_id' => $this->user->id]);
+
+    $this->socialAccount = SocialAccount::factory()->telegram()->create([
+        'workspace_id' => $this->workspace->id,
+    ]);
+
+    $this->post = Post::factory()->create([
+        'workspace_id' => $this->workspace->id,
+        'user_id' => $this->user->id,
+        'content' => 'Hello world',
+    ]);
+
+    $this->postPlatform = PostPlatform::factory()->create([
+        'post_id' => $this->post->id,
+        'social_account_id' => $this->socialAccount->id,
+        'platform' => Platform::Telegram,
+        'content_type' => ContentType::TelegramPost,
+    ]);
+
+    $this->publisher = new TelegramPublisher;
+});
+
+function telegramOk(array $result): array
+{
+    return ['ok' => true, 'result' => $result];
+}
+
+test('telegram publisher sends a text-only message', function () {
+    Http::fake([
+        '*/botTESTTOKEN/sendMessage' => Http::response(telegramOk(['message_id' => 42]), 200),
+    ]);
+
+    $result = $this->publisher->publish($this->postPlatform);
+
+    expect($result['id'])->toBe('42');
+    expect($result['url'])->toBe('https://t.me/mychannel/42');
+
+    Http::assertSent(function ($request) {
+        return str_contains($request->url(), '/sendMessage')
+            && $request['chat_id'] === '-1001234567890'
+            && $request['text'] === 'Hello world'
+            && $request['parse_mode'] === 'HTML';
+    });
+});
+
+test('telegram publisher sends a single image with caption', function () {
+    $this->post->update([
+        'content' => 'A photo',
+        'media' => [[
+            'id' => 'm1',
+            'path' => 'media/2026-01/pic.jpg',
+            'url' => 'https://cdn.test/pic.jpg',
+            'mime_type' => 'image/jpeg',
+            'original_filename' => 'pic.jpg',
+        ]],
+    ]);
+
+    Http::fake([
+        '*/botTESTTOKEN/sendPhoto' => Http::response(telegramOk(['message_id' => 7]), 200),
+    ]);
+
+    $this->publisher->publish($this->postPlatform);
+
+    Http::assertSent(function ($request) {
+        return str_contains($request->url(), '/sendPhoto')
+            && str_contains($request['photo'], 'pic.jpg')
+            && $request['caption'] === 'A photo'
+            && $request['parse_mode'] === 'HTML';
+    });
+});
+
+test('telegram publisher sends multiple media as an album', function () {
+    $this->post->update([
+        'content' => 'Album',
+        'media' => [
+            ['id' => 'm1', 'path' => 'media/a.jpg', 'url' => 'https://cdn.test/a.jpg', 'mime_type' => 'image/jpeg', 'original_filename' => 'a.jpg'],
+            ['id' => 'm2', 'path' => 'media/b.jpg', 'url' => 'https://cdn.test/b.jpg', 'mime_type' => 'image/jpeg', 'original_filename' => 'b.jpg'],
+        ],
+    ]);
+
+    Http::fake([
+        '*/botTESTTOKEN/sendMediaGroup' => Http::response(telegramOk([['message_id' => 11], ['message_id' => 12]]), 200),
+    ]);
+
+    $result = $this->publisher->publish($this->postPlatform);
+
+    expect($result['id'])->toBe('11');
+
+    Http::assertSent(function ($request) {
+        if (! str_contains($request->url(), '/sendMediaGroup')) {
+            return false;
+        }
+        $media = json_decode($request['media'], true);
+
+        return count($media) === 2
+            && $media[0]['type'] === 'photo'
+            && $media[0]['caption'] === 'Album'
+            && ! isset($media[1]['caption']);
+    });
+});
+
+test('telegram publisher sends long text as its own message after media', function () {
+    $longText = str_repeat('x', 1500); // over the 1024 caption limit
+
+    $this->post->update([
+        'content' => $longText,
+        'media' => [[
+            'id' => 'm1', 'path' => 'media/p.jpg', 'url' => 'https://cdn.test/p.jpg', 'mime_type' => 'image/jpeg', 'original_filename' => 'p.jpg',
+        ]],
+    ]);
+
+    Http::fake([
+        '*/botTESTTOKEN/sendPhoto' => Http::response(telegramOk(['message_id' => 5]), 200),
+        '*/botTESTTOKEN/sendMessage' => Http::response(telegramOk(['message_id' => 6]), 200),
+    ]);
+
+    $this->publisher->publish($this->postPlatform);
+
+    // Photo carries no caption (too long); the text follows as a separate message.
+    Http::assertSent(fn ($request) => str_contains($request->url(), '/sendPhoto') && $request['caption'] === '');
+    Http::assertSent(fn ($request) => str_contains($request->url(), '/sendMessage') && $request['text'] === $longText);
+});
+
+test('telegram publisher rejects content over the 4096 limit', function () {
+    $this->post->update(['content' => str_repeat('x', 4097)]);
+
+    Http::fake();
+
+    expect(fn () => $this->publisher->publish($this->postPlatform))->toThrow(Exception::class);
+
+    Http::assertNothingSent();
+});
+
+test('telegram publisher throws on a non-ok response', function () {
+    Http::fake([
+        '*/botTESTTOKEN/sendMessage' => Http::response(['ok' => false, 'error_code' => 403, 'description' => 'Forbidden: bot is not a member of the channel chat'], 403),
+    ]);
+
+    expect(fn () => $this->publisher->publish($this->postPlatform))->toThrow(TelegramPublishException::class);
+});
+
+test('telegram publisher builds a private-channel url when there is no username', function () {
+    $this->socialAccount->update(['username' => null, 'meta' => ['chat_id' => '-1009876543210', 'type' => 'channel']]);
+
+    Http::fake([
+        '*/botTESTTOKEN/sendMessage' => Http::response(telegramOk(['message_id' => 99]), 200),
+    ]);
+
+    $result = $this->publisher->publish($this->postPlatform);
+
+    expect($result['url'])->toBe('https://t.me/c/9876543210/99');
+});

From a4cf8aa4cef7eb1260ddfb27bf6e6ab9a0df3898 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 21:39:03 -0300
Subject: [PATCH 02/35] Add Telegram connection flow (controller + webhook)

Connect a channel by issuing a one-time code the user posts as /connect <code>
in their channel. A secret-token-guarded webhook matches the code, links the
channel as a SocialAccount (chat_id in meta), and records it on the request so
the connect endpoint can poll for completion. Adds the TelegramConnectRequest
model + migration, the connect/status endpoints, the public webhook route (CSRF
exempt), a ConnectionVerifier branch (getChat liveness), and a telegram:set-webhook
command. Tests cover the code issue, webhook link, secret rejection, expired/
unknown codes, status polling, and the command.
---
 app/Console/Commands/Telegram/SetWebhook.php  |  46 ++++++
 .../Controllers/Auth/TelegramController.php   |  68 +++++++++
 .../Webhooks/TelegramWebhookController.php    |  79 ++++++++++
 app/Models/TelegramConnectRequest.php         |  40 +++++
 app/Services/Social/ConnectionVerifier.php    |  14 ++
 bootstrap/app.php                             |   1 +
 ...create_telegram_connect_requests_table.php |  29 ++++
 routes/app.php                                |   4 +
 routes/web.php                                |   5 +
 .../Feature/Social/TelegramConnectionTest.php | 143 ++++++++++++++++++
 10 files changed, 429 insertions(+)
 create mode 100644 app/Console/Commands/Telegram/SetWebhook.php
 create mode 100644 app/Http/Controllers/Auth/TelegramController.php
 create mode 100644 app/Http/Controllers/Webhooks/TelegramWebhookController.php
 create mode 100644 app/Models/TelegramConnectRequest.php
 create mode 100644 database/migrations/2026_06_14_002757_create_telegram_connect_requests_table.php
 create mode 100644 tests/Feature/Social/TelegramConnectionTest.php

diff --git a/app/Console/Commands/Telegram/SetWebhook.php b/app/Console/Commands/Telegram/SetWebhook.php
new file mode 100644
index 00000000..33a77dea
--- /dev/null
+++ b/app/Console/Commands/Telegram/SetWebhook.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands\Telegram;
+
+use Illuminate\Console\Attributes\Description;
+use Illuminate\Console\Attributes\Signature;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Http;
+
+#[Signature('telegram:set-webhook')]
+#[Description('Register the Telegram bot webhook with the configured URL and secret token')]
+class SetWebhook extends Command
+{
+    public function handle(): int
+    {
+        $token = (string) config('trypost.platforms.telegram.bot_token');
+        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
+        $secret = (string) config('trypost.platforms.telegram.webhook_secret');
+
+        if ($token === '' || $secret === '') {
+            $this->error('TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must both be set.');
+
+            return self::FAILURE;
+        }
+
+        $url = route('telegram.webhook');
+
+        $response = Http::post("{$api}/bot{$token}/setWebhook", [
+            'url' => $url,
+            'secret_token' => $secret,
+            'allowed_updates' => ['message', 'channel_post'],
+        ]);
+
+        if (! $response->successful() || data_get($response->json(), 'ok') !== true) {
+            $this->error('Failed to set webhook: '.$response->body());
+
+            return self::FAILURE;
+        }
+
+        $this->info("Telegram webhook registered at {$url}");
+
+        return self::SUCCESS;
+    }
+}
diff --git a/app/Http/Controllers/Auth/TelegramController.php b/app/Http/Controllers/Auth/TelegramController.php
new file mode 100644
index 00000000..fb146860
--- /dev/null
+++ b/app/Http/Controllers/Auth/TelegramController.php
@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Auth;
+
+use App\Enums\SocialAccount\Platform as SocialPlatform;
+use App\Models\TelegramConnectRequest;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
+
+class TelegramController extends SocialController
+{
+    protected SocialPlatform $platform = SocialPlatform::Telegram;
+
+    /**
+     * Start a connection: issue a one-time code the user posts in their channel
+     * (`/connect <code>`) so the webhook can tie the channel to this workspace.
+     */
+    public function connect(Request $request): JsonResponse
+    {
+        $this->ensurePlatformEnabled();
+
+        $workspace = $request->user()->currentWorkspace;
+        abort_if($workspace === null, SymfonyResponse::HTTP_CONFLICT, 'No active workspace.');
+
+        $this->authorize('manageAccounts', $workspace);
+        $this->ensureSocialAccountLimit($workspace);
+
+        $connectRequest = TelegramConnectRequest::create([
+            'workspace_id' => $workspace->id,
+            'user_id' => $request->user()->id,
+            'code' => Str::lower(Str::random(12)),
+            'expires_at' => now()->addMinutes(15),
+        ]);
+
+        return response()->json([
+            'code' => $connectRequest->code,
+            'bot_username' => config('trypost.platforms.telegram.bot_username'),
+            'expires_at' => $connectRequest->expires_at->toIso8601String(),
+        ]);
+    }
+
+    /**
+     * Poll whether the channel has been linked yet.
+     */
+    public function status(Request $request): JsonResponse
+    {
+        $workspace = $request->user()->currentWorkspace;
+        abort_if($workspace === null, SymfonyResponse::HTTP_CONFLICT, 'No active workspace.');
+
+        $connectRequest = TelegramConnectRequest::query()
+            ->where('workspace_id', $workspace->id)
+            ->where('code', (string) $request->query('code'))
+            ->first();
+
+        $status = match (true) {
+            $connectRequest === null => 'unknown',
+            $connectRequest->social_account_id !== null => 'connected',
+            $connectRequest->isExpired() => 'expired',
+            default => 'pending',
+        };
+
+        return response()->json(['status' => $status]);
+    }
+}
diff --git a/app/Http/Controllers/Webhooks/TelegramWebhookController.php b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
new file mode 100644
index 00000000..c394dade
--- /dev/null
+++ b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Webhooks;
+
+use App\Enums\SocialAccount\Platform as SocialPlatform;
+use App\Enums\SocialAccount\Status;
+use App\Http\Controllers\Controller;
+use App\Models\TelegramConnectRequest;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
+
+class TelegramWebhookController extends Controller
+{
+    /**
+     * Receives Bot API updates. The only update we act on is a `/connect <code>`
+     * message/channel_post: it ties the originating channel to the workspace that
+     * generated the code. Everything else is acknowledged and ignored.
+     */
+    public function handle(Request $request): Response
+    {
+        $secret = (string) config('trypost.platforms.telegram.webhook_secret');
+
+        abort_if(
+            $secret === '' || ! hash_equals($secret, (string) $request->header('X-Telegram-Bot-Api-Secret-Token')),
+            SymfonyResponse::HTTP_FORBIDDEN,
+        );
+
+        $update = $request->all();
+        $chat = data_get($update, 'message.chat') ?? data_get($update, 'channel_post.chat');
+        $text = data_get($update, 'message.text') ?? data_get($update, 'channel_post.text');
+
+        if (! is_array($chat) || ! is_string($text) || ! preg_match('/^\/connect(?:@\S+)?\s+(\S+)/', $text, $matches)) {
+            return response()->noContent();
+        }
+
+        $connectRequest = TelegramConnectRequest::query()
+            ->whereNull('social_account_id')
+            ->where('code', $matches[1])
+            ->where('expires_at', '>', now())
+            ->first();
+
+        if ($connectRequest === null) {
+            return response()->noContent();
+        }
+
+        $chatId = (string) data_get($chat, 'id');
+        $username = data_get($chat, 'username');
+
+        $account = $connectRequest->workspace->socialAccounts()->updateOrCreate(
+            [
+                'platform' => SocialPlatform::Telegram->value,
+                'platform_user_id' => $chatId,
+            ],
+            [
+                'username' => $username,
+                'display_name' => data_get($chat, 'title') ?? $username,
+                'access_token' => '',
+                'refresh_token' => '',
+                'token_expires_at' => null,
+                'scopes' => [],
+                'status' => Status::Connected,
+                'error_message' => null,
+                'disconnected_at' => null,
+                'meta' => [
+                    'chat_id' => $chatId,
+                    'username' => $username,
+                    'type' => data_get($chat, 'type'),
+                ],
+            ],
+        );
+
+        $connectRequest->update(['social_account_id' => $account->id]);
+
+        return response()->noContent();
+    }
+}
diff --git a/app/Models/TelegramConnectRequest.php b/app/Models/TelegramConnectRequest.php
new file mode 100644
index 00000000..5f44a283
--- /dev/null
+++ b/app/Models/TelegramConnectRequest.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class TelegramConnectRequest extends Model
+{
+    use HasFactory;
+    use HasUuids;
+
+    protected $guarded = [];
+
+    protected function casts(): array
+    {
+        return [
+            'expires_at' => 'datetime',
+        ];
+    }
+
+    public function isExpired(): bool
+    {
+        return $this->expires_at->isPast();
+    }
+
+    public function workspace(): BelongsTo
+    {
+        return $this->belongsTo(Workspace::class);
+    }
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+}
diff --git a/app/Services/Social/ConnectionVerifier.php b/app/Services/Social/ConnectionVerifier.php
index 74cd90e8..4fb3da56 100644
--- a/app/Services/Social/ConnectionVerifier.php
+++ b/app/Services/Social/ConnectionVerifier.php
@@ -66,6 +66,7 @@ private function callVerifyEndpoint(SocialAccount $account): bool
             Platform::Pinterest => $this->verifyPinterest($account),
             Platform::Bluesky => $this->verifyBluesky($account),
             Platform::Mastodon => $this->verifyMastodon($account),
+            Platform::Telegram => $this->verifyTelegram($account),
         };
     }
 
@@ -504,6 +505,19 @@ private function verifyBluesky(SocialAccount $account): bool
         return $response->successful();
     }
 
+    private function verifyTelegram(SocialAccount $account): bool
+    {
+        $token = (string) config('trypost.platforms.telegram.bot_token');
+        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
+
+        // getChat succeeds only while the bot can still reach the chat.
+        $response = Http::get("{$api}/bot{$token}/getChat", [
+            'chat_id' => data_get($account->meta, 'chat_id'),
+        ]);
+
+        return $response->successful() && data_get($response->json(), 'ok') === true;
+    }
+
     private function verifyMastodon(SocialAccount $account): bool
     {
         $instance = $account->meta['instance'] ?? config('trypost.platforms.mastodon.default_instance');
diff --git a/bootstrap/app.php b/bootstrap/app.php
index 996308de..abff5dd7 100644
--- a/bootstrap/app.php
+++ b/bootstrap/app.php
@@ -40,6 +40,7 @@
 
         $middleware->preventRequestForgery(except: [
             'stripe/*',
+            'telegram/webhook',
         ]);
     })
     ->withExceptions(function (Exceptions $exceptions): void {
diff --git a/database/migrations/2026_06_14_002757_create_telegram_connect_requests_table.php b/database/migrations/2026_06_14_002757_create_telegram_connect_requests_table.php
new file mode 100644
index 00000000..ed34310a
--- /dev/null
+++ b/database/migrations/2026_06_14_002757_create_telegram_connect_requests_table.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('telegram_connect_requests', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->foreignUuid('workspace_id')->constrained('workspaces')->cascadeOnDelete();
+            $table->foreignUuid('user_id')->nullable()->constrained('users')->nullOnDelete();
+            $table->string('code')->unique();
+            // Set by the webhook once the channel is linked; null while pending.
+            $table->foreignUuid('social_account_id')->nullable()->constrained('social_accounts')->nullOnDelete();
+            $table->timestamp('expires_at');
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('telegram_connect_requests');
+    }
+};
diff --git a/routes/app.php b/routes/app.php
index fe17fe82..f20c6a33 100644
--- a/routes/app.php
+++ b/routes/app.php
@@ -37,6 +37,7 @@
 use App\Http\Controllers\Auth\MastodonController;
 use App\Http\Controllers\Auth\PinterestController;
 use App\Http\Controllers\Auth\SocialController;
+use App\Http\Controllers\Auth\TelegramController;
 use App\Http\Controllers\Auth\ThreadsController;
 use App\Http\Controllers\Auth\TikTokController;
 use App\Http\Controllers\Auth\XController;
@@ -117,6 +118,9 @@
     Route::get('connect/mastodon', [MastodonController::class, 'connect'])->name('app.social.mastodon.connect');
     Route::post('connect/mastodon', [MastodonController::class, 'authorizeInstance'])->name('app.social.mastodon.authorize');
     Route::get('accounts/mastodon/callback', [MastodonController::class, 'callback'])->name('app.social.mastodon.callback');
+
+    Route::post('connect/telegram', [TelegramController::class, 'connect'])->name('app.social.telegram.connect');
+    Route::get('connect/telegram/status', [TelegramController::class, 'status'])->name('app.social.telegram.status');
 });
 
 // Routes that require active subscription and completed onboarding
diff --git a/routes/web.php b/routes/web.php
index b2f144b6..77575c38 100644
--- a/routes/web.php
+++ b/routes/web.php
@@ -2,5 +2,10 @@
 
 declare(strict_types=1);
 
+use App\Http\Controllers\Webhooks\TelegramWebhookController;
+use Illuminate\Support\Facades\Route;
+
+Route::post('telegram/webhook', [TelegramWebhookController::class, 'handle'])->name('telegram.webhook');
+
 require __DIR__.'/auth.php';
 require __DIR__.'/app.php';
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
new file mode 100644
index 00000000..489d6b76
--- /dev/null
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Enums\SocialAccount\Platform;
+use App\Enums\UserWorkspace\Role;
+use App\Models\SocialAccount;
+use App\Models\TelegramConnectRequest;
+use App\Models\User;
+use App\Models\Workspace;
+use Illuminate\Support\Facades\Http;
+
+beforeEach(function () {
+    config([
+        'trypost.platforms.telegram.bot_token' => 'TESTTOKEN',
+        'trypost.platforms.telegram.bot_username' => 'TryPostBot',
+        'trypost.platforms.telegram.webhook_secret' => 'shh-secret',
+    ]);
+
+    $this->workspace = Workspace::factory()->create();
+    $this->user = User::factory()->create([
+        'current_workspace_id' => $this->workspace->id,
+        'account_id' => $this->workspace->account_id,
+    ]);
+    $this->workspace->members()->attach($this->user->id, ['role' => Role::Admin->value]);
+    $this->user->refresh();
+});
+
+function telegramUpdate(string $code, array $chat = []): array
+{
+    return [
+        'channel_post' => [
+            'message_id' => 5,
+            'chat' => array_merge([
+                'id' => -1001234567890,
+                'title' => 'My Channel',
+                'username' => 'mychannel',
+                'type' => 'channel',
+            ], $chat),
+            'text' => "/connect {$code}",
+        ],
+    ];
+}
+
+it('issues a connect code', function () {
+    $response = $this->actingAs($this->user)
+        ->postJson(route('app.social.telegram.connect'))
+        ->assertOk()
+        ->assertJsonStructure(['code', 'bot_username', 'expires_at']);
+
+    expect($response->json('bot_username'))->toBe('TryPostBot');
+
+    $this->assertDatabaseHas('telegram_connect_requests', [
+        'workspace_id' => $this->workspace->id,
+        'code' => $response->json('code'),
+        'social_account_id' => null,
+    ]);
+});
+
+it('links the channel when the webhook receives a matching /connect', function () {
+    $request = TelegramConnectRequest::create([
+        'workspace_id' => $this->workspace->id,
+        'user_id' => $this->user->id,
+        'code' => 'abc123code',
+        'expires_at' => now()->addMinutes(15),
+    ]);
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate('abc123code'))
+        ->assertNoContent();
+
+    $account = SocialAccount::where('workspace_id', $this->workspace->id)
+        ->where('platform', Platform::Telegram)
+        ->first();
+
+    expect($account)->not->toBeNull();
+    expect($account->platform_user_id)->toBe('-1001234567890');
+    expect($account->display_name)->toBe('My Channel');
+    expect($account->username)->toBe('mychannel');
+    expect(data_get($account->meta, 'chat_id'))->toBe('-1001234567890');
+
+    expect($request->fresh()->social_account_id)->toBe($account->id);
+});
+
+it('rejects the webhook without the secret token', function () {
+    $this->postJson(route('telegram.webhook'), telegramUpdate('whatever'))
+        ->assertForbidden();
+});
+
+it('ignores the webhook for an unknown or expired code', function () {
+    TelegramConnectRequest::create([
+        'workspace_id' => $this->workspace->id,
+        'user_id' => $this->user->id,
+        'code' => 'expiredcode',
+        'expires_at' => now()->subMinute(),
+    ]);
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate('expiredcode'))
+        ->assertNoContent();
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate('does-not-exist'))
+        ->assertNoContent();
+
+    expect(SocialAccount::where('platform', Platform::Telegram)->count())->toBe(0);
+});
+
+it('reports connection status while pending and once connected', function () {
+    $request = TelegramConnectRequest::create([
+        'workspace_id' => $this->workspace->id,
+        'user_id' => $this->user->id,
+        'code' => 'statuscode',
+        'expires_at' => now()->addMinutes(15),
+    ]);
+
+    $this->actingAs($this->user)
+        ->getJson(route('app.social.telegram.status', ['code' => 'statuscode']))
+        ->assertOk()
+        ->assertJson(['status' => 'pending']);
+
+    $account = SocialAccount::factory()->telegram()->create(['workspace_id' => $this->workspace->id]);
+    $request->update(['social_account_id' => $account->id]);
+
+    $this->actingAs($this->user)
+        ->getJson(route('app.social.telegram.status', ['code' => 'statuscode']))
+        ->assertOk()
+        ->assertJson(['status' => 'connected']);
+});
+
+it('registers the webhook via the artisan command', function () {
+    Http::fake([
+        '*/botTESTTOKEN/setWebhook' => Http::response(['ok' => true, 'result' => true], 200),
+    ]);
+
+    $this->artisan('telegram:set-webhook')->assertSuccessful();
+
+    Http::assertSent(function ($request) {
+        return str_contains($request->url(), '/setWebhook')
+            && $request['secret_token'] === 'shh-secret'
+            && str_contains($request['url'], 'telegram/webhook');
+    });
+});

From 79acdccc45ba920d61fb88e83b56a37f31143e20 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 21:58:49 -0300
Subject: [PATCH 03/35] Add Telegram connection UI (connect dialog + code
 polling)

---
 lang/en/accounts.php                          |  17 ++
 lang/es/accounts.php                          |  17 ++
 lang/pt-BR/accounts.php                       |  17 ++
 public/images/accounts/telegram.svg           |  10 +
 .../components/accounts/AddSocialDialog.vue   | 215 +++++++++++------
 .../accounts/TelegramConnectDialog.vue        | 225 ++++++++++++++++++
 6 files changed, 434 insertions(+), 67 deletions(-)
 create mode 100644 public/images/accounts/telegram.svg
 create mode 100644 resources/js/components/accounts/TelegramConnectDialog.vue

diff --git a/lang/en/accounts.php b/lang/en/accounts.php
index ef6a4e93..9a58a9ad 100644
--- a/lang/en/accounts.php
+++ b/lang/en/accounts.php
@@ -51,6 +51,7 @@
         'pinterest' => 'Connect your Pinterest account',
         'bluesky' => 'Connect your Bluesky account',
         'mastodon' => 'Connect your Mastodon account',
+        'telegram' => 'Connect a Telegram channel or group',
     ],
 
     'disconnect_modal' => [
@@ -82,6 +83,22 @@
         'submitting' => 'Connecting...',
     ],
 
+    'telegram' => [
+        'title' => 'Connect Telegram',
+        'description' => 'Link a channel or group',
+        'step_admin' => 'Add :bot as an administrator to your Telegram channel or group.',
+        'step_command' => 'Post this command in the channel or group:',
+        'waiting' => 'Waiting for the channel to connect…',
+        'connected' => 'Channel connected!',
+        'connected_toast' => 'Telegram channel connected successfully!',
+        'copied_toast' => 'Command copied to clipboard',
+        'expired' => 'This code has expired. Generate a new one to try again.',
+        'new_code' => 'Generate a new code',
+        'retry' => 'Try again',
+        'error_generic' => 'Could not start the connection. Please try again.',
+        'close' => 'Close',
+    ],
+
     'facebook' => [
         'title' => 'Select Facebook Page',
         'description' => 'Choose which page you want to connect',
diff --git a/lang/es/accounts.php b/lang/es/accounts.php
index 7970b605..48842e10 100644
--- a/lang/es/accounts.php
+++ b/lang/es/accounts.php
@@ -51,6 +51,7 @@
         'pinterest' => 'Conecta tu cuenta de Pinterest',
         'bluesky' => 'Conecta tu cuenta de Bluesky',
         'mastodon' => 'Conecta tu cuenta de Mastodon',
+        'telegram' => 'Conecta un canal o grupo de Telegram',
     ],
 
     'disconnect_modal' => [
@@ -82,6 +83,22 @@
         'submitting' => 'Conectando...',
     ],
 
+    'telegram' => [
+        'title' => 'Conectar Telegram',
+        'description' => 'Vincula un canal o grupo',
+        'step_admin' => 'Añade :bot como administrador de tu canal o grupo de Telegram.',
+        'step_command' => 'Publica este comando en el canal o grupo:',
+        'waiting' => 'Esperando a que el canal se conecte…',
+        'connected' => '¡Canal conectado!',
+        'connected_toast' => '¡Canal de Telegram conectado correctamente!',
+        'copied_toast' => 'Comando copiado al portapapeles',
+        'expired' => 'Este código ha caducado. Genera uno nuevo para volver a intentarlo.',
+        'new_code' => 'Generar un nuevo código',
+        'retry' => 'Reintentar',
+        'error_generic' => 'No se pudo iniciar la conexión. Inténtalo de nuevo.',
+        'close' => 'Cerrar',
+    ],
+
     'facebook' => [
         'title' => 'Seleccionar página de Facebook',
         'description' => 'Elige qué página deseas conectar',
diff --git a/lang/pt-BR/accounts.php b/lang/pt-BR/accounts.php
index 1b20f80c..7c238aa9 100644
--- a/lang/pt-BR/accounts.php
+++ b/lang/pt-BR/accounts.php
@@ -51,6 +51,7 @@
         'pinterest' => 'Conecte sua conta do Pinterest',
         'bluesky' => 'Conecte sua conta do Bluesky',
         'mastodon' => 'Conecte sua conta do Mastodon',
+        'telegram' => 'Conecte um canal ou grupo do Telegram',
     ],
 
     'disconnect_modal' => [
@@ -82,6 +83,22 @@
         'submitting' => 'Conectando...',
     ],
 
+    'telegram' => [
+        'title' => 'Conectar Telegram',
+        'description' => 'Vincule um canal ou grupo',
+        'step_admin' => 'Adicione :bot como administrador do seu canal ou grupo do Telegram.',
+        'step_command' => 'Publique este comando no canal ou grupo:',
+        'waiting' => 'Aguardando o canal conectar…',
+        'connected' => 'Canal conectado!',
+        'connected_toast' => 'Canal do Telegram conectado com sucesso!',
+        'copied_toast' => 'Comando copiado para a área de transferência',
+        'expired' => 'Este código expirou. Gere um novo para tentar de novo.',
+        'new_code' => 'Gerar um novo código',
+        'retry' => 'Tentar novamente',
+        'error_generic' => 'Não foi possível iniciar a conexão. Tente novamente.',
+        'close' => 'Fechar',
+    ],
+
     'facebook' => [
         'title' => 'Selecionar Página do Facebook',
         'description' => 'Escolha qual página você deseja conectar',
diff --git a/public/images/accounts/telegram.svg b/public/images/accounts/telegram.svg
new file mode 100644
index 00000000..8e5fccef
--- /dev/null
+++ b/public/images/accounts/telegram.svg
@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 240 240" fill="none">
+    <defs>
+        <linearGradient id="tg" x1="120" y1="0" x2="120" y2="240" gradientUnits="userSpaceOnUse">
+            <stop stop-color="#2AABEE" />
+            <stop offset="1" stop-color="#229ED9" />
+        </linearGradient>
+    </defs>
+    <circle cx="120" cy="120" r="120" fill="url(#tg)" />
+    <path fill="#fff" d="M54 118.7c35-15.2 58.3-25.3 70-30.2 33.3-13.9 40.2-16.3 44.7-16.4 1 0 3.2.2 4.7 1.4.8.7 1.2 1.6 1.4 2.6.2 1 .4 3.2.2 4.9-1.8 19-9.7 65.1-13.7 86.4-1.7 9-5 12.1-8.2 12.4-7 .6-12.3-4.6-19-9-10.6-7-16.6-11.3-26.9-18.1-11.9-7.8-4.2-12.1 2.6-19.1 1.8-1.8 32.5-29.8 33.1-32.3.1-.3.1-1.5-.6-2.1-.7-.6-1.7-.4-2.5-.2-1.1.2-17.9 11.4-50.6 33.4-4.8 3.3-9.1 4.9-13 4.8-4.3-.1-12.5-2.4-18.6-4.4-7.5-2.4-13.5-3.7-13-7.9.3-2.2 3.3-4.4 9.1-6.6z" />
+</svg>
diff --git a/resources/js/components/accounts/AddSocialDialog.vue b/resources/js/components/accounts/AddSocialDialog.vue
index 1aee18a1..46eaac40 100644
--- a/resources/js/components/accounts/AddSocialDialog.vue
+++ b/resources/js/components/accounts/AddSocialDialog.vue
@@ -2,8 +2,9 @@
 import { router } from '@inertiajs/vue3';
 import { IconPlus } from '@tabler/icons-vue';
 import { trans } from 'laravel-vue-i18n';
-import { onMounted, onUnmounted } from 'vue';
+import { onMounted, onUnmounted, ref } from 'vue';
 
+import TelegramConnectDialog from '@/components/accounts/TelegramConnectDialog.vue';
 import { Button } from '@/components/ui/button';
 import {
     Dialog,
@@ -32,24 +33,92 @@ const getPlatformDescription = (platform: string): string =>
 // + ink 2px border + slight rotation per platform, real PNG logo inside.
 // `linkedin-page` / `instagram-facebook` fall back to the base brand
 // image and same color since they're variants of the same network.
-const platformTheme: Record<string, { bg: string; rotate: string; image: string }> = {
-    instagram: { bg: 'bg-pink-200', rotate: '-rotate-2', image: '/images/accounts/instagram.png' },
-    'instagram-facebook': { bg: 'bg-pink-200', rotate: '-rotate-2', image: '/images/accounts/instagram.png' },
-    facebook: { bg: 'bg-sky-200', rotate: 'rotate-1', image: '/images/accounts/facebook.png' },
-    linkedin: { bg: 'bg-blue-200', rotate: '-rotate-1', image: '/images/accounts/linkedin.png' },
-    'linkedin-page': { bg: 'bg-blue-200', rotate: '-rotate-1', image: '/images/accounts/linkedin.png' },
-    x: { bg: 'bg-amber-200', rotate: 'rotate-2', image: '/images/accounts/x.png' },
-    tiktok: { bg: 'bg-fuchsia-200', rotate: '-rotate-1', image: '/images/accounts/tiktok.png' },
-    youtube: { bg: 'bg-red-200', rotate: 'rotate-1', image: '/images/accounts/youtube.png' },
-    pinterest: { bg: 'bg-rose-200', rotate: '-rotate-2', image: '/images/accounts/pinterest.png' },
-    threads: { bg: 'bg-emerald-200', rotate: 'rotate-2', image: '/images/accounts/threads.png' },
-    bluesky: { bg: 'bg-cyan-200', rotate: '-rotate-1', image: '/images/accounts/bluesky.png' },
-    mastodon: { bg: 'bg-violet-200', rotate: 'rotate-1', image: '/images/accounts/mastodon.png' },
+const platformTheme: Record<
+    string,
+    { bg: string; rotate: string; image: string }
+> = {
+    instagram: {
+        bg: 'bg-pink-200',
+        rotate: '-rotate-2',
+        image: '/images/accounts/instagram.png',
+    },
+    'instagram-facebook': {
+        bg: 'bg-pink-200',
+        rotate: '-rotate-2',
+        image: '/images/accounts/instagram.png',
+    },
+    facebook: {
+        bg: 'bg-sky-200',
+        rotate: 'rotate-1',
+        image: '/images/accounts/facebook.png',
+    },
+    linkedin: {
+        bg: 'bg-blue-200',
+        rotate: '-rotate-1',
+        image: '/images/accounts/linkedin.png',
+    },
+    'linkedin-page': {
+        bg: 'bg-blue-200',
+        rotate: '-rotate-1',
+        image: '/images/accounts/linkedin.png',
+    },
+    x: {
+        bg: 'bg-amber-200',
+        rotate: 'rotate-2',
+        image: '/images/accounts/x.png',
+    },
+    tiktok: {
+        bg: 'bg-fuchsia-200',
+        rotate: '-rotate-1',
+        image: '/images/accounts/tiktok.png',
+    },
+    youtube: {
+        bg: 'bg-red-200',
+        rotate: 'rotate-1',
+        image: '/images/accounts/youtube.png',
+    },
+    pinterest: {
+        bg: 'bg-rose-200',
+        rotate: '-rotate-2',
+        image: '/images/accounts/pinterest.png',
+    },
+    threads: {
+        bg: 'bg-emerald-200',
+        rotate: 'rotate-2',
+        image: '/images/accounts/threads.png',
+    },
+    bluesky: {
+        bg: 'bg-cyan-200',
+        rotate: '-rotate-1',
+        image: '/images/accounts/bluesky.png',
+    },
+    mastodon: {
+        bg: 'bg-violet-200',
+        rotate: 'rotate-1',
+        image: '/images/accounts/mastodon.png',
+    },
+    telegram: {
+        bg: 'bg-sky-200',
+        rotate: '-rotate-2',
+        image: '/images/accounts/telegram.svg',
+    },
 };
 
 const themeFor = (value: string) =>
     platformTheme[value] ?? { bg: 'bg-muted', rotate: '', image: '' };
 
+const telegramOpen = ref(false);
+
+const connectPlatform = (platformValue: string) => {
+    if (platformValue === 'telegram') {
+        open.value = false;
+        telegramOpen.value = true;
+        return;
+    }
+
+    openOAuthPopup(platformValue);
+};
+
 const openOAuthPopup = (platformValue: string) => {
     const url = `/connect/${platformValue}`;
     const width = 600;
@@ -84,64 +153,76 @@ onUnmounted(() => {
 </script>
 
 <template>
-    <Dialog v-model:open="open">
-        <DialogContent class="sm:max-w-3xl">
-            <DialogHeader>
-                <DialogTitle>{{ $t('accounts.add_social_title') }}</DialogTitle>
-                <DialogDescription>
-                    {{ $t('accounts.add_social_description') }}
-                </DialogDescription>
-            </DialogHeader>
-            <div class="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4">
+    <div>
+        <Dialog v-model:open="open">
+            <DialogContent class="sm:max-w-3xl">
+                <DialogHeader>
+                    <DialogTitle>{{
+                        $t('accounts.add_social_title')
+                    }}</DialogTitle>
+                    <DialogDescription>
+                        {{ $t('accounts.add_social_description') }}
+                    </DialogDescription>
+                </DialogHeader>
                 <div
-                    v-for="platform in platforms"
-                    :key="platform.value"
-                    class="group relative flex flex-col items-center gap-3 rounded-xl border-2 border-foreground bg-card p-4 text-center shadow-xs transition-shadow hover:shadow-md"
+                    class="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4"
                 >
-                    <!-- "+" sticker badge appears only on hover so the grid doesn't feel cluttered. -->
-                    <span
-                        class="pointer-events-none absolute -top-2 -right-2 inline-flex size-6 items-center justify-center rounded-full border-2 border-foreground bg-violet-200 text-foreground opacity-0 shadow-2xs transition-all group-hover:rotate-90 group-hover:scale-110 group-hover:opacity-100"
-                        aria-hidden="true"
-                    >
-                        <IconPlus class="size-3.5" stroke-width="3" />
-                    </span>
-
                     <div
-                        :class="[
-                            themeFor(platform.value).bg,
-                            themeFor(platform.value).rotate,
-                            'inline-flex size-16 items-center justify-center rounded-2xl border-2 border-foreground shadow-sm transition-transform group-hover:!rotate-0',
-                        ]"
+                        v-for="platform in platforms"
+                        :key="platform.value"
+                        class="group relative flex flex-col items-center gap-3 rounded-xl border-2 border-foreground bg-card p-4 text-center shadow-xs transition-shadow hover:shadow-md"
                     >
-                        <img
-                            :src="themeFor(platform.value).image"
-                            :alt="platform.label"
-                            class="size-9 rounded-lg"
-                            loading="lazy"
-                        />
-                    </div>
-
-                    <div class="flex-1">
-                        <span class="block text-sm font-semibold text-foreground">
-                            <template v-if="platform.label.includes('(')">
-                                {{ platform.label.split('(')[0].trim() }}
-                            </template>
-                            <template v-else>{{ platform.label }}</template>
+                        <!-- "+" sticker badge appears only on hover so the grid doesn't feel cluttered. -->
+                        <span
+                            class="pointer-events-none absolute -top-2 -right-2 inline-flex size-6 items-center justify-center rounded-full border-2 border-foreground bg-violet-200 text-foreground opacity-0 shadow-2xs transition-all group-hover:scale-110 group-hover:rotate-90 group-hover:opacity-100"
+                            aria-hidden="true"
+                        >
+                            <IconPlus class="size-3.5" stroke-width="3" />
                         </span>
-                        <p class="mt-0.5 line-clamp-2 text-xs leading-tight text-foreground/60">
-                            {{ getPlatformDescription(platform.value) }}
-                        </p>
-                    </div>
 
-                    <Button
-                        size="sm"
-                        class="mt-auto w-full"
-                        @click="openOAuthPopup(platform.value)"
-                    >
-                        {{ $t('accounts.connect_cta') }}
-                    </Button>
+                        <div
+                            :class="[
+                                themeFor(platform.value).bg,
+                                themeFor(platform.value).rotate,
+                                'inline-flex size-16 items-center justify-center rounded-2xl border-2 border-foreground shadow-sm transition-transform group-hover:!rotate-0',
+                            ]"
+                        >
+                            <img
+                                :src="themeFor(platform.value).image"
+                                :alt="platform.label"
+                                class="size-9 rounded-lg"
+                                loading="lazy"
+                            />
+                        </div>
+
+                        <div class="flex-1">
+                            <span
+                                class="block text-sm font-semibold text-foreground"
+                            >
+                                <template v-if="platform.label.includes('(')">
+                                    {{ platform.label.split('(')[0].trim() }}
+                                </template>
+                                <template v-else>{{ platform.label }}</template>
+                            </span>
+                            <p
+                                class="mt-0.5 line-clamp-2 text-xs leading-tight text-foreground/60"
+                            >
+                                {{ getPlatformDescription(platform.value) }}
+                            </p>
+                        </div>
+
+                        <Button
+                            size="sm"
+                            class="mt-auto w-full"
+                            @click="connectPlatform(platform.value)"
+                        >
+                            {{ $t('accounts.connect_cta') }}
+                        </Button>
+                    </div>
                 </div>
-            </div>
-        </DialogContent>
-    </Dialog>
+            </DialogContent>
+        </Dialog>
+
+        <TelegramConnectDialog v-model:open="telegramOpen" />
+    </div>
 </template>
diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
new file mode 100644
index 00000000..2ff715b6
--- /dev/null
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -0,0 +1,225 @@
+<script setup lang="ts">
+import { router, useHttp } from '@inertiajs/vue3';
+import { IconCheck, IconCopy, IconLoader2 } from '@tabler/icons-vue';
+import { trans } from 'laravel-vue-i18n';
+import { onUnmounted, ref, watch } from 'vue';
+import { toast } from 'vue-sonner';
+
+import { Button } from '@/components/ui/button';
+import {
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+} from '@/components/ui/dialog';
+import { copyToClipboard } from '@/lib/utils';
+import {
+    connect as connectTelegram,
+    status as telegramStatus,
+} from '@/routes/app/social/telegram';
+
+const open = defineModel<boolean>('open', { required: true });
+
+type Phase = 'loading' | 'ready' | 'connected' | 'expired' | 'error';
+
+const phase = ref<Phase>('loading');
+const code = ref('');
+const botUsername = ref('');
+const errorMessage = ref('');
+
+const httpConnect = useHttp<
+    Record<string, never>,
+    { code: string; bot_username: string; expires_at: string }
+>({});
+const httpStatus = useHttp<Record<string, never>, { status: string }>({});
+
+let pollTimer: ReturnType<typeof setTimeout> | null = null;
+
+const stopPolling = () => {
+    if (pollTimer !== null) {
+        clearTimeout(pollTimer);
+        pollTimer = null;
+    }
+};
+
+const poll = async () => {
+    if (phase.value !== 'ready') return;
+
+    try {
+        const response = await httpStatus.get(
+            telegramStatus.url({ query: { code: code.value } }),
+        );
+
+        if (response?.status === 'connected') {
+            phase.value = 'connected';
+            stopPolling();
+            toast.success(trans('accounts.telegram.connected_toast'));
+            setTimeout(() => {
+                open.value = false;
+                router.reload();
+            }, 1200);
+            return;
+        }
+
+        if (response?.status === 'expired' || response?.status === 'unknown') {
+            phase.value = 'expired';
+            stopPolling();
+            return;
+        }
+    } catch {
+        // Transient polling failures are ignored; the next tick retries.
+    }
+
+    pollTimer = setTimeout(poll, 3000);
+};
+
+const start = async () => {
+    phase.value = 'loading';
+    errorMessage.value = '';
+
+    try {
+        const response = await httpConnect.post(connectTelegram.url());
+        code.value = response.code;
+        botUsername.value = response.bot_username;
+        phase.value = 'ready';
+        poll();
+    } catch (error) {
+        phase.value = 'error';
+        errorMessage.value =
+            (error as { response?: { data?: { message?: string } } })?.response
+                ?.data?.message ?? trans('accounts.telegram.error_generic');
+    }
+};
+
+const copyCommand = () => {
+    copyToClipboard(`/connect ${code.value}`);
+    toast.success(trans('accounts.telegram.copied_toast'));
+};
+
+watch(open, (isOpen) => {
+    if (isOpen) {
+        start();
+    } else {
+        stopPolling();
+    }
+});
+
+onUnmounted(stopPolling);
+</script>
+
+<template>
+    <Dialog v-model:open="open">
+        <DialogContent class="sm:max-w-lg">
+            <DialogHeader>
+                <div class="flex items-center gap-3">
+                    <img
+                        src="/images/accounts/telegram.svg"
+                        alt="Telegram"
+                        class="size-10"
+                    />
+                    <div class="text-left">
+                        <DialogTitle>{{
+                            $t('accounts.telegram.title')
+                        }}</DialogTitle>
+                        <DialogDescription>{{
+                            $t('accounts.telegram.description')
+                        }}</DialogDescription>
+                    </div>
+                </div>
+            </DialogHeader>
+
+            <div
+                v-if="phase === 'loading'"
+                class="flex items-center justify-center py-10"
+            >
+                <IconLoader2
+                    class="size-6 animate-spin text-muted-foreground"
+                />
+            </div>
+
+            <div v-else-if="phase === 'error'" class="space-y-4 py-2">
+                <p class="text-sm text-destructive">{{ errorMessage }}</p>
+                <Button class="w-full" @click="start">{{
+                    $t('accounts.telegram.retry')
+                }}</Button>
+            </div>
+
+            <div v-else-if="phase === 'expired'" class="space-y-4 py-2">
+                <p class="text-sm text-muted-foreground">
+                    {{ $t('accounts.telegram.expired') }}
+                </p>
+                <Button class="w-full" @click="start">{{
+                    $t('accounts.telegram.new_code')
+                }}</Button>
+            </div>
+
+            <div
+                v-else-if="phase === 'connected'"
+                class="flex flex-col items-center gap-3 py-8 text-center"
+            >
+                <span
+                    class="inline-flex size-12 items-center justify-center rounded-full bg-emerald-100 text-emerald-600"
+                >
+                    <IconCheck class="size-6" stroke-width="3" />
+                </span>
+                <p class="text-sm font-medium">
+                    {{ $t('accounts.telegram.connected') }}
+                </p>
+            </div>
+
+            <div v-else class="space-y-5 py-2">
+                <ol class="space-y-4 text-sm">
+                    <li class="flex gap-3">
+                        <span
+                            class="flex size-6 shrink-0 items-center justify-center rounded-full border-2 border-foreground text-xs font-semibold"
+                            >1</span
+                        >
+                        <span
+                            v-html="
+                                trans('accounts.telegram.step_admin', {
+                                    bot: `@${botUsername}`,
+                                })
+                            "
+                        />
+                    </li>
+                    <li class="flex gap-3">
+                        <span
+                            class="flex size-6 shrink-0 items-center justify-center rounded-full border-2 border-foreground text-xs font-semibold"
+                            >2</span
+                        >
+                        <div class="flex-1 space-y-2">
+                            <span>{{
+                                $t('accounts.telegram.step_command')
+                            }}</span>
+                            <button
+                                type="button"
+                                class="group flex w-full items-center justify-between gap-2 rounded-lg border bg-muted px-3 py-2 text-left font-mono text-sm transition-colors hover:bg-muted/70"
+                                @click="copyCommand"
+                            >
+                                <span>/connect {{ code }}</span>
+                                <IconCopy
+                                    class="size-4 shrink-0 text-muted-foreground group-hover:text-foreground"
+                                />
+                            </button>
+                        </div>
+                    </li>
+                </ol>
+
+                <div
+                    class="flex items-center gap-2 text-sm text-muted-foreground"
+                >
+                    <IconLoader2 class="size-4 animate-spin" />
+                    {{ $t('accounts.telegram.waiting') }}
+                </div>
+            </div>
+
+            <DialogFooter>
+                <Button variant="outline" @click="open = false">{{
+                    $t('accounts.telegram.close')
+                }}</Button>
+            </DialogFooter>
+        </DialogContent>
+    </Dialog>
+</template>

From b6605ea2287993581201ec24f2bd97ce5691056e Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 22:01:37 -0300
Subject: [PATCH 04/35] Document Telegram env vars in .env.example

---
 .env.example | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/.env.example b/.env.example
index fc3ed8b5..dd9e2b17 100644
--- a/.env.example
+++ b/.env.example
@@ -152,6 +152,12 @@ PINTEREST_CLIENT_ID=
 PINTEREST_CLIENT_SECRET=
 PINTEREST_CLIENT_REDIRECT="${APP_URL}/accounts/pinterest/callback"
 
+# Telegram (single shared bot — create one via https://t.me/BotFather)
+# After setting these, run: php artisan telegram:set-webhook
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_BOT_USERNAME=
+TELEGRAM_WEBHOOK_SECRET=
+
 # AI Services
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
@@ -196,6 +202,7 @@ NIGHTWATCH_TOKEN=
 # PINTEREST_ENABLED=true
 # MASTODON_ENABLED=true
 # BLUESKY_ENABLED=true
+# TELEGRAM_ENABLED=true
 
 # Media Services
 UNSPLASH_ACCESS_KEY=

From b50424321296dcd9b1c93aabcda3c7e5e8af79a0 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 22:02:02 -0300
Subject: [PATCH 05/35] Document Telegram env vars in docker .env example

---
 docker/.env.docker.example | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docker/.env.docker.example b/docker/.env.docker.example
index 5d8e48b6..706b63df 100644
--- a/docker/.env.docker.example
+++ b/docker/.env.docker.example
@@ -128,6 +128,12 @@ PINTEREST_CLIENT_ID=
 PINTEREST_CLIENT_SECRET=
 PINTEREST_CLIENT_REDIRECT="${APP_URL}/accounts/pinterest/callback"
 
+# Telegram (single shared bot — create one via https://t.me/BotFather)
+# After setting these, run: php artisan telegram:set-webhook
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_BOT_USERNAME=
+TELEGRAM_WEBHOOK_SECRET=
+
 # AI Services
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=

From f37846984207b41e2ccfafb52ed11db2ed3fc10f Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 22:10:12 -0300
Subject: [PATCH 06/35] Wire Telegram into the post composer (preview, content
 type, logo)

---
 lang/en/posts.php                             |   5 +
 lang/es/posts.php                             |   5 +
 lang/pt-BR/posts.php                          |   5 +
 .../js/components/SocialAccountsGrid.vue      |   1 +
 .../posts/previews/PlatformPreview.vue        |   3 +
 .../posts/previews/TelegramPreview.vue        | 130 ++++++++++++++++++
 resources/js/composables/usePlatformLogo.ts   |   3 +
 resources/js/types/content-type.ts            |   1 +
 resources/js/types/platform.ts                |   1 +
 9 files changed, 154 insertions(+)
 create mode 100644 resources/js/components/posts/previews/TelegramPreview.vue

diff --git a/lang/en/posts.php b/lang/en/posts.php
index b078650f..b38b845d 100644
--- a/lang/en/posts.php
+++ b/lang/en/posts.php
@@ -484,6 +484,10 @@
             'label' => 'Post',
             'description' => 'Text post with optional media',
         ],
+        'telegram_post' => [
+            'label' => 'Post',
+            'description' => 'Text post with optional media',
+        ],
     ],
 
     'platforms' => [
@@ -586,6 +590,7 @@
                 'bluesky_post' => 'Bluesky Post',
                 'threads_post' => 'Threads Post',
                 'mastodon_post' => 'Mastodon Post',
+                'telegram_post' => 'Telegram Post',
                 'facebook_post' => 'Facebook Post',
                 'pinterest_pin' => 'Pinterest Pin',
                 'instagram_story' => 'Instagram Story',
diff --git a/lang/es/posts.php b/lang/es/posts.php
index e04c19e0..220880f2 100644
--- a/lang/es/posts.php
+++ b/lang/es/posts.php
@@ -484,6 +484,10 @@
             'label' => 'Post',
             'description' => 'Post de texto con multimedia opcional',
         ],
+        'telegram_post' => [
+            'label' => 'Post',
+            'description' => 'Post de texto con multimedia opcional',
+        ],
     ],
 
     'platforms' => [
@@ -587,6 +591,7 @@
                 'bluesky_post' => 'Post en Bluesky',
                 'threads_post' => 'Post en Threads',
                 'mastodon_post' => 'Post en Mastodon',
+                'telegram_post' => 'Post en Telegram',
                 'facebook_post' => 'Post en Facebook',
                 'pinterest_pin' => 'Pin de Pinterest',
                 'instagram_story' => 'Story de Instagram',
diff --git a/lang/pt-BR/posts.php b/lang/pt-BR/posts.php
index 299bcfcc..e3311e02 100644
--- a/lang/pt-BR/posts.php
+++ b/lang/pt-BR/posts.php
@@ -484,6 +484,10 @@
             'label' => 'Post',
             'description' => 'Post de texto com mídia opcional',
         ],
+        'telegram_post' => [
+            'label' => 'Post',
+            'description' => 'Post de texto com mídia opcional',
+        ],
     ],
 
     'platforms' => [
@@ -586,6 +590,7 @@
                 'bluesky_post' => 'Post no Bluesky',
                 'threads_post' => 'Post no Threads',
                 'mastodon_post' => 'Post no Mastodon',
+                'telegram_post' => 'Post no Telegram',
                 'facebook_post' => 'Post no Facebook',
                 'pinterest_pin' => 'Pin no Pinterest',
                 'instagram_story' => 'Story do Instagram',
diff --git a/resources/js/components/SocialAccountsGrid.vue b/resources/js/components/SocialAccountsGrid.vue
index cc3be23f..40b54a9e 100644
--- a/resources/js/components/SocialAccountsGrid.vue
+++ b/resources/js/components/SocialAccountsGrid.vue
@@ -121,6 +121,7 @@ const getProfileUrl = (platform: string, username: string | null, platformUserId
         'threads': `https://threads.net/@${username}`,
         'bluesky': `https://bsky.app/profile/${username}`,
         'pinterest': `https://pinterest.com/${username}`,
+        'telegram': `https://t.me/${username}`,
     };
     return urls[platform] || null;
 };
diff --git a/resources/js/components/posts/previews/PlatformPreview.vue b/resources/js/components/posts/previews/PlatformPreview.vue
index 42cacc39..565521ac 100644
--- a/resources/js/components/posts/previews/PlatformPreview.vue
+++ b/resources/js/components/posts/previews/PlatformPreview.vue
@@ -9,6 +9,7 @@ import InstagramPreview from './InstagramPreview.vue';
 import LinkedInPreview from './LinkedInPreview.vue';
 import MastodonPreview from './MastodonPreview.vue';
 import PinterestPreview from './PinterestPreview.vue';
+import TelegramPreview from './TelegramPreview.vue';
 import ThreadsPreview from './ThreadsPreview.vue';
 import TikTokPreview from './TikTokPreview.vue';
 import XPreview from './XPreview.vue';
@@ -65,6 +66,8 @@ const previewComponent = computed(() => {
             return BlueskyPreview;
         case 'mastodon':
             return MastodonPreview;
+        case 'telegram':
+            return TelegramPreview;
         default:
             return LinkedInPreview;
     }
diff --git a/resources/js/components/posts/previews/TelegramPreview.vue b/resources/js/components/posts/previews/TelegramPreview.vue
new file mode 100644
index 00000000..96ea9e6a
--- /dev/null
+++ b/resources/js/components/posts/previews/TelegramPreview.vue
@@ -0,0 +1,130 @@
+<script setup lang="ts">
+import VideoPreview from '@/components/posts/previews/VideoPreview.vue';
+import { isVideoMedia } from '@/composables/useMedia';
+import type { MediaItem } from '@/types/media';
+
+interface SocialAccount {
+    id: string;
+    platform: string;
+    display_name: string;
+    username: string;
+    avatar_url: string | null;
+}
+
+interface Props {
+    socialAccount: SocialAccount;
+    content: string;
+    media: MediaItem[];
+}
+
+defineProps<Props>();
+</script>
+
+<template>
+    <div
+        class="flex h-full w-full flex-col overflow-hidden bg-[#a4bce0] dark:bg-[#0e1621]"
+    >
+        <!-- Header -->
+        <div
+            class="flex items-center gap-3 bg-white px-4 py-2.5 dark:bg-[#17212b]"
+        >
+            <img
+                v-if="socialAccount.avatar_url"
+                :src="socialAccount.avatar_url"
+                :alt="socialAccount.display_name"
+                class="h-9 w-9 rounded-full object-cover"
+            />
+            <div
+                v-else
+                class="flex h-9 w-9 items-center justify-center rounded-full bg-gradient-to-br from-[#2aabee] to-[#229ed9] font-semibold text-white"
+            >
+                {{ socialAccount.display_name?.charAt(0) }}
+            </div>
+            <div class="min-w-0 flex-1">
+                <div
+                    class="truncate text-[15px] font-semibold text-[#1f232b] dark:text-white"
+                >
+                    {{ socialAccount.display_name || 'Channel' }}
+                </div>
+                <div class="text-[13px] text-[#707991] dark:text-[#708499]">
+                    channel
+                </div>
+            </div>
+        </div>
+
+        <!-- Chat area -->
+        <div class="flex-1 overflow-y-auto px-3 py-4">
+            <div
+                class="max-w-[85%] overflow-hidden rounded-2xl rounded-bl-md bg-white shadow-sm dark:bg-[#182533]"
+            >
+                <!-- Media -->
+                <div v-if="media.length > 0">
+                    <div
+                        class="overflow-hidden"
+                        :class="{
+                            'grid grid-cols-2 gap-0.5': media.length >= 2,
+                        }"
+                    >
+                        <div
+                            v-for="(item, index) in media.slice(0, 4)"
+                            :key="item.id"
+                            class="relative overflow-hidden"
+                            :class="{
+                                'aspect-[4/3]': media.length === 1,
+                                'aspect-square': media.length > 1,
+                            }"
+                        >
+                            <img
+                                v-if="!isVideoMedia(item)"
+                                :src="item.url"
+                                :alt="item.original_filename"
+                                class="h-full w-full object-cover"
+                            />
+                            <VideoPreview
+                                v-else
+                                :src="item.url"
+                                video-class="w-full h-full object-cover bg-black"
+                            />
+                            <div
+                                v-if="media.length > 4 && index === 3"
+                                class="absolute inset-0 flex items-center justify-center bg-black/60"
+                            >
+                                <span class="text-xl font-semibold text-white"
+                                    >+{{ media.length - 4 }}</span
+                                >
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Text + meta -->
+                <div class="px-3 py-2">
+                    <div
+                        v-if="content"
+                        class="text-[15px] leading-[20px] whitespace-pre-wrap text-[#1f232b] dark:text-white"
+                    >
+                        {{ content }}
+                    </div>
+                    <div
+                        class="mt-1 flex items-center justify-end gap-1 text-[12px] text-[#707991] dark:text-[#708499]"
+                    >
+                        <svg
+                            class="h-3.5 w-3.5"
+                            viewBox="0 0 24 24"
+                            fill="none"
+                            stroke="currentColor"
+                            stroke-width="2"
+                        >
+                            <path
+                                d="M1 12s4-7 11-7 11 7 11 7-4 7-11 7-11-7-11-7z"
+                            />
+                            <circle cx="12" cy="12" r="3" />
+                        </svg>
+                        <span>0</span>
+                        <span class="ml-1">4:30 PM</span>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>
diff --git a/resources/js/composables/usePlatformLogo.ts b/resources/js/composables/usePlatformLogo.ts
index dc46ee93..317278f0 100644
--- a/resources/js/composables/usePlatformLogo.ts
+++ b/resources/js/composables/usePlatformLogo.ts
@@ -11,6 +11,7 @@ const PLATFORM_LOGOS: Record<string, string> = {
     bluesky: '/images/accounts/bluesky.png',
     pinterest: '/images/accounts/pinterest.png',
     mastodon: '/images/accounts/mastodon.png',
+    telegram: '/images/accounts/telegram.svg',
 };
 
 const PLATFORM_LABELS: Record<string, string> = {
@@ -26,6 +27,7 @@ const PLATFORM_LABELS: Record<string, string> = {
     bluesky: 'Bluesky',
     pinterest: 'Pinterest',
     mastodon: 'Mastodon',
+    telegram: 'Telegram',
 };
 
 const PLATFORM_CONTENT_TYPES: Record<string, string[]> = {
@@ -41,6 +43,7 @@ const PLATFORM_CONTENT_TYPES: Record<string, string[]> = {
     pinterest: ['pinterest_pin', 'pinterest_video_pin', 'pinterest_carousel'],
     bluesky: ['bluesky_post'],
     mastodon: ['mastodon_post'],
+    telegram: ['telegram_post'],
 };
 
 export interface ContentTypeOption {
diff --git a/resources/js/types/content-type.ts b/resources/js/types/content-type.ts
index 3d8a22bb..8db617ca 100644
--- a/resources/js/types/content-type.ts
+++ b/resources/js/types/content-type.ts
@@ -19,6 +19,7 @@ export const ContentType = {
     PinterestCarousel: 'pinterest_carousel',
     BlueskyPost: 'bluesky_post',
     MastodonPost: 'mastodon_post',
+    TelegramPost: 'telegram_post',
 } as const;
 
 export type ContentTypeValue = (typeof ContentType)[keyof typeof ContentType];
diff --git a/resources/js/types/platform.ts b/resources/js/types/platform.ts
index ec785f19..56d29781 100644
--- a/resources/js/types/platform.ts
+++ b/resources/js/types/platform.ts
@@ -11,6 +11,7 @@ export const Platform = {
     Pinterest: 'pinterest',
     Bluesky: 'bluesky',
     Mastodon: 'mastodon',
+    Telegram: 'telegram',
 } as const;
 
 export type PlatformValue = (typeof Platform)[keyof typeof Platform];

From deb1c6fa69b4b69db3ba414aef67ce193c5a6aec Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 22:20:52 -0300
Subject: [PATCH 07/35] Extract Telegram webhook registration into an action

---
 .../SocialAccount/RegisterTelegramWebhook.php | 45 +++++++++++++++++
 app/Console/Commands/Telegram/SetWebhook.php  | 27 +++--------
 .../RegisterTelegramWebhookTest.php           | 48 +++++++++++++++++++
 3 files changed, 99 insertions(+), 21 deletions(-)
 create mode 100644 app/Actions/SocialAccount/RegisterTelegramWebhook.php
 create mode 100644 tests/Feature/Actions/SocialAccount/RegisterTelegramWebhookTest.php

diff --git a/app/Actions/SocialAccount/RegisterTelegramWebhook.php b/app/Actions/SocialAccount/RegisterTelegramWebhook.php
new file mode 100644
index 00000000..4b0757e0
--- /dev/null
+++ b/app/Actions/SocialAccount/RegisterTelegramWebhook.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\SocialAccount;
+
+use Illuminate\Support\Facades\Http;
+use InvalidArgumentException;
+use RuntimeException;
+
+class RegisterTelegramWebhook
+{
+    /**
+     * Register the bot webhook (URL + secret token) with the Telegram Bot API.
+     *
+     * @return string the webhook URL that was registered
+     *
+     * @throws InvalidArgumentException when the bot token or secret is missing
+     * @throws RuntimeException when Telegram rejects the request
+     */
+    public static function execute(): string
+    {
+        $token = (string) config('trypost.platforms.telegram.bot_token');
+        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
+        $secret = (string) config('trypost.platforms.telegram.webhook_secret');
+
+        if ($token === '' || $secret === '') {
+            throw new InvalidArgumentException('TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must both be set.');
+        }
+
+        $url = route('telegram.webhook');
+
+        $response = Http::post("{$api}/bot{$token}/setWebhook", [
+            'url' => $url,
+            'secret_token' => $secret,
+            'allowed_updates' => ['message', 'channel_post'],
+        ]);
+
+        if (! $response->successful() || data_get($response->json(), 'ok') !== true) {
+            throw new RuntimeException("Failed to set Telegram webhook: {$response->body()}");
+        }
+
+        return $url;
+    }
+}
diff --git a/app/Console/Commands/Telegram/SetWebhook.php b/app/Console/Commands/Telegram/SetWebhook.php
index 33a77dea..28a473c9 100644
--- a/app/Console/Commands/Telegram/SetWebhook.php
+++ b/app/Console/Commands/Telegram/SetWebhook.php
@@ -4,10 +4,11 @@
 
 namespace App\Console\Commands\Telegram;
 
+use App\Actions\SocialAccount\RegisterTelegramWebhook;
 use Illuminate\Console\Attributes\Description;
 use Illuminate\Console\Attributes\Signature;
 use Illuminate\Console\Command;
-use Illuminate\Support\Facades\Http;
+use Throwable;
 
 #[Signature('telegram:set-webhook')]
 #[Description('Register the Telegram bot webhook with the configured URL and secret token')]
@@ -15,26 +16,10 @@ class SetWebhook extends Command
 {
     public function handle(): int
     {
-        $token = (string) config('trypost.platforms.telegram.bot_token');
-        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
-        $secret = (string) config('trypost.platforms.telegram.webhook_secret');
-
-        if ($token === '' || $secret === '') {
-            $this->error('TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must both be set.');
-
-            return self::FAILURE;
-        }
-
-        $url = route('telegram.webhook');
-
-        $response = Http::post("{$api}/bot{$token}/setWebhook", [
-            'url' => $url,
-            'secret_token' => $secret,
-            'allowed_updates' => ['message', 'channel_post'],
-        ]);
-
-        if (! $response->successful() || data_get($response->json(), 'ok') !== true) {
-            $this->error('Failed to set webhook: '.$response->body());
+        try {
+            $url = RegisterTelegramWebhook::execute();
+        } catch (Throwable $e) {
+            $this->error($e->getMessage());
 
             return self::FAILURE;
         }
diff --git a/tests/Feature/Actions/SocialAccount/RegisterTelegramWebhookTest.php b/tests/Feature/Actions/SocialAccount/RegisterTelegramWebhookTest.php
new file mode 100644
index 00000000..4bfea510
--- /dev/null
+++ b/tests/Feature/Actions/SocialAccount/RegisterTelegramWebhookTest.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Actions\SocialAccount\RegisterTelegramWebhook;
+use Illuminate\Support\Facades\Http;
+
+beforeEach(function () {
+    config([
+        'trypost.platforms.telegram.bot_token' => 'TESTTOKEN',
+        'trypost.platforms.telegram.webhook_secret' => 'shh-secret',
+    ]);
+});
+
+test('it registers the webhook with the url, secret and allowed updates', function () {
+    Http::fake([
+        '*/botTESTTOKEN/setWebhook' => Http::response(['ok' => true, 'result' => true], 200),
+    ]);
+
+    $url = RegisterTelegramWebhook::execute();
+
+    expect($url)->toBe(route('telegram.webhook'));
+
+    Http::assertSent(function ($request) {
+        return str_contains($request->url(), '/botTESTTOKEN/setWebhook')
+            && $request['url'] === route('telegram.webhook')
+            && $request['secret_token'] === 'shh-secret'
+            && $request['allowed_updates'] === ['message', 'channel_post'];
+    });
+});
+
+test('it throws when the bot token or secret is missing', function () {
+    config(['trypost.platforms.telegram.webhook_secret' => '']);
+
+    Http::fake();
+
+    expect(fn () => RegisterTelegramWebhook::execute())->toThrow(InvalidArgumentException::class);
+
+    Http::assertNothingSent();
+});
+
+test('it throws when telegram rejects the request', function () {
+    Http::fake([
+        '*/botTESTTOKEN/setWebhook' => Http::response(['ok' => false, 'description' => 'Unauthorized'], 401),
+    ]);
+
+    expect(fn () => RegisterTelegramWebhook::execute())->toThrow(RuntimeException::class);
+});

From 2585d89cb445a4ba7df625e1dbd1448a46f564bc Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 22:38:23 -0300
Subject: [PATCH 08/35] Address PR review: connect-status enum, publisher
 cleanup, fill test gaps

---
 .../SocialAccount/TelegramConnectStatus.php   | 28 +++++++++
 .../Social/TelegramPublishException.php       |  2 +-
 .../Controllers/Auth/TelegramController.php   | 12 ++--
 .../Webhooks/TelegramWebhookController.php    |  2 +-
 app/Services/Social/TelegramPublisher.php     | 38 ++++-------
 .../accounts/TelegramConnectDialog.vue        | 35 ++++++-----
 .../Services/Social/TelegramPublisherTest.php | 49 +++++++++++++++
 .../Feature/Social/TelegramConnectionTest.php | 44 +++++++++++++
 .../Social/TelegramPublishExceptionTest.php   | 63 +++++++++++++++++++
 9 files changed, 224 insertions(+), 49 deletions(-)
 create mode 100644 app/Enums/SocialAccount/TelegramConnectStatus.php
 create mode 100644 tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php

diff --git a/app/Enums/SocialAccount/TelegramConnectStatus.php b/app/Enums/SocialAccount/TelegramConnectStatus.php
new file mode 100644
index 00000000..3afeb0bc
--- /dev/null
+++ b/app/Enums/SocialAccount/TelegramConnectStatus.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\SocialAccount;
+
+use App\Models\TelegramConnectRequest;
+
+enum TelegramConnectStatus: string
+{
+    case Unknown = 'unknown';
+    case Pending = 'pending';
+    case Connected = 'connected';
+    case Expired = 'expired';
+
+    /**
+     * Derive the connection status the frontend polls for from a connect request.
+     */
+    public static function for(?TelegramConnectRequest $request): self
+    {
+        return match (true) {
+            $request === null => self::Unknown,
+            $request->social_account_id !== null => self::Connected,
+            $request->isExpired() => self::Expired,
+            default => self::Pending,
+        };
+    }
+}
diff --git a/app/Exceptions/Social/TelegramPublishException.php b/app/Exceptions/Social/TelegramPublishException.php
index 26943e1a..56675239 100644
--- a/app/Exceptions/Social/TelegramPublishException.php
+++ b/app/Exceptions/Social/TelegramPublishException.php
@@ -55,7 +55,7 @@ public static function fromApiResponse(mixed $response): static
 
         return new static(
             userMessage: $description,
-            category: ErrorCategory::ContentPolicy,
+            category: ErrorCategory::Unknown,
             platformErrorCode: (string) $status,
             rawResponse: $rawResponse,
         );
diff --git a/app/Http/Controllers/Auth/TelegramController.php b/app/Http/Controllers/Auth/TelegramController.php
index fb146860..9e7d7530 100644
--- a/app/Http/Controllers/Auth/TelegramController.php
+++ b/app/Http/Controllers/Auth/TelegramController.php
@@ -5,6 +5,7 @@
 namespace App\Http\Controllers\Auth;
 
 use App\Enums\SocialAccount\Platform as SocialPlatform;
+use App\Enums\SocialAccount\TelegramConnectStatus;
 use App\Models\TelegramConnectRequest;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -56,13 +57,8 @@ public function status(Request $request): JsonResponse
             ->where('code', (string) $request->query('code'))
             ->first();
 
-        $status = match (true) {
-            $connectRequest === null => 'unknown',
-            $connectRequest->social_account_id !== null => 'connected',
-            $connectRequest->isExpired() => 'expired',
-            default => 'pending',
-        };
-
-        return response()->json(['status' => $status]);
+        return response()->json([
+            'status' => TelegramConnectStatus::for($connectRequest)->value,
+        ]);
     }
 }
diff --git a/app/Http/Controllers/Webhooks/TelegramWebhookController.php b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
index c394dade..1ebbb066 100644
--- a/app/Http/Controllers/Webhooks/TelegramWebhookController.php
+++ b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
@@ -56,7 +56,7 @@ public function handle(Request $request): Response
             ],
             [
                 'username' => $username,
-                'display_name' => data_get($chat, 'title') ?? $username,
+                'display_name' => data_get($chat, 'title') ?? $username ?? "Telegram {$chatId}",
                 'access_token' => '',
                 'refresh_token' => '',
                 'token_expires_at' => null,
diff --git a/app/Services/Social/TelegramPublisher.php b/app/Services/Social/TelegramPublisher.php
index 24e79e24..8772fda5 100644
--- a/app/Services/Social/TelegramPublisher.php
+++ b/app/Services/Social/TelegramPublisher.php
@@ -104,37 +104,25 @@ private function sendSingleMedia(string $chatId, array $item, string $caption):
      */
     private function sendMediaGroup(string $chatId, array $items, string $caption): int
     {
-        $firstMessageId = 0;
+        $group = [];
 
-        foreach (array_chunk($items, self::ALBUM_CHUNK) as $chunkIndex => $chunk) {
-            $group = [];
+        foreach ($items as $index => $item) {
+            $entry = ['type' => $item['type'], 'media' => $item['url']];
 
-            foreach ($chunk as $itemIndex => $item) {
-                $entry = [
-                    // Documents can't be mixed into an album; send them as photos/videos only.
-                    'type' => $item['type'] === 'document' ? 'document' : $item['type'],
-                    'media' => $item['url'],
-                ];
-
-                if ($chunkIndex === 0 && $itemIndex === 0 && $caption !== '') {
-                    $entry['caption'] = $caption;
-                    $entry['parse_mode'] = 'HTML';
-                }
-
-                $group[] = $entry;
+            if ($index === 0 && $caption !== '') {
+                $entry['caption'] = $caption;
+                $entry['parse_mode'] = 'HTML';
             }
 
-            $response = $this->call('sendMediaGroup', [
-                'chat_id' => $chatId,
-                'media' => json_encode($group),
-            ]);
-
-            if ($chunkIndex === 0) {
-                $firstMessageId = (int) data_get($response->json(), 'result.0.message_id');
-            }
+            $group[] = $entry;
         }
 
-        return $firstMessageId;
+        $response = $this->call('sendMediaGroup', [
+            'chat_id' => $chatId,
+            'media' => json_encode($group),
+        ]);
+
+        return (int) data_get($response->json(), 'result.0.message_id');
     }
 
     /**
diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index 2ff715b6..d295a372 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -23,17 +23,26 @@ import {
 const open = defineModel<boolean>('open', { required: true });
 
 type Phase = 'loading' | 'ready' | 'connected' | 'expired' | 'error';
+type ConnectStatus = 'unknown' | 'pending' | 'connected' | 'expired';
+
+interface ConnectResponse {
+    code: string;
+    bot_username: string;
+    expires_at: string;
+}
+
+const POLL_INTERVAL_MS = 3000;
+const SUCCESS_CLOSE_DELAY_MS = 1200;
 
 const phase = ref<Phase>('loading');
 const code = ref('');
 const botUsername = ref('');
 const errorMessage = ref('');
 
-const httpConnect = useHttp<
-    Record<string, never>,
-    { code: string; bot_username: string; expires_at: string }
->({});
-const httpStatus = useHttp<Record<string, never>, { status: string }>({});
+const httpConnect = useHttp<Record<string, never>, ConnectResponse>({});
+const httpStatus = useHttp<Record<string, never>, { status: ConnectStatus }>(
+    {},
+);
 
 let pollTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -59,7 +68,7 @@ const poll = async () => {
             setTimeout(() => {
                 open.value = false;
                 router.reload();
-            }, 1200);
+            }, SUCCESS_CLOSE_DELAY_MS);
             return;
         }
 
@@ -72,7 +81,7 @@ const poll = async () => {
         // Transient polling failures are ignored; the next tick retries.
     }
 
-    pollTimer = setTimeout(poll, 3000);
+    pollTimer = setTimeout(poll, POLL_INTERVAL_MS);
 };
 
 const start = async () => {
@@ -176,13 +185,11 @@ onUnmounted(stopPolling);
                             class="flex size-6 shrink-0 items-center justify-center rounded-full border-2 border-foreground text-xs font-semibold"
                             >1</span
                         >
-                        <span
-                            v-html="
-                                trans('accounts.telegram.step_admin', {
-                                    bot: `@${botUsername}`,
-                                })
-                            "
-                        />
+                        <span>{{
+                            trans('accounts.telegram.step_admin', {
+                                bot: `@${botUsername}`,
+                            })
+                        }}</span>
                     </li>
                     <li class="flex gap-3">
                         <span
diff --git a/tests/Feature/Services/Social/TelegramPublisherTest.php b/tests/Feature/Services/Social/TelegramPublisherTest.php
index a1f6094a..43be60be 100644
--- a/tests/Feature/Services/Social/TelegramPublisherTest.php
+++ b/tests/Feature/Services/Social/TelegramPublisherTest.php
@@ -88,6 +88,55 @@ function telegramOk(array $result): array
     });
 });
 
+test('telegram publisher sends a single video', function () {
+    $this->post->update([
+        'content' => 'A clip',
+        'media' => [[
+            'id' => 'm1',
+            'path' => 'media/clip.mp4',
+            'url' => 'https://cdn.test/clip.mp4',
+            'mime_type' => 'video/mp4',
+            'original_filename' => 'clip.mp4',
+        ]],
+    ]);
+
+    Http::fake([
+        '*/botTESTTOKEN/sendVideo' => Http::response(telegramOk(['message_id' => 8]), 200),
+    ]);
+
+    $this->publisher->publish($this->postPlatform);
+
+    Http::assertSent(function ($request) {
+        return str_contains($request->url(), '/sendVideo')
+            && str_contains($request['video'], 'clip.mp4')
+            && $request['caption'] === 'A clip';
+    });
+});
+
+test('telegram publisher sends a non-image, non-video file as a document', function () {
+    $this->post->update([
+        'content' => 'A file',
+        'media' => [[
+            'id' => 'm1',
+            'path' => 'media/report.pdf',
+            'url' => 'https://cdn.test/report.pdf',
+            'mime_type' => 'application/pdf',
+            'original_filename' => 'report.pdf',
+        ]],
+    ]);
+
+    Http::fake([
+        '*/botTESTTOKEN/sendDocument' => Http::response(telegramOk(['message_id' => 9]), 200),
+    ]);
+
+    $this->publisher->publish($this->postPlatform);
+
+    Http::assertSent(function ($request) {
+        return str_contains($request->url(), '/sendDocument')
+            && str_contains($request['document'], 'report.pdf');
+    });
+});
+
 test('telegram publisher sends multiple media as an album', function () {
     $this->post->update([
         'content' => 'Album',
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index 489d6b76..e930537f 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -8,6 +8,7 @@
 use App\Models\TelegramConnectRequest;
 use App\Models\User;
 use App\Models\Workspace;
+use App\Services\Social\ConnectionVerifier;
 use Illuminate\Support\Facades\Http;
 
 beforeEach(function () {
@@ -82,6 +83,25 @@ function telegramUpdate(string $code, array $chat = []): array
     expect($request->fresh()->social_account_id)->toBe($account->id);
 });
 
+it('links a private channel that has no username', function () {
+    TelegramConnectRequest::create([
+        'workspace_id' => $this->workspace->id,
+        'user_id' => $this->user->id,
+        'code' => 'privatecode',
+        'expires_at' => now()->addMinutes(15),
+    ]);
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate('privatecode', ['username' => null]))
+        ->assertNoContent();
+
+    $account = SocialAccount::where('platform', Platform::Telegram)->first();
+
+    expect($account->username)->toBeNull();
+    expect($account->display_name)->toBe('My Channel');
+    expect(data_get($account->meta, 'username'))->toBeNull();
+});
+
 it('rejects the webhook without the secret token', function () {
     $this->postJson(route('telegram.webhook'), telegramUpdate('whatever'))
         ->assertForbidden();
@@ -128,6 +148,30 @@ function telegramUpdate(string $code, array $chat = []): array
         ->assertJson(['status' => 'connected']);
 });
 
+it('verifies a connected telegram account via getChat', function () {
+    config(['trypost.platforms.telegram.bot_token' => 'TESTTOKEN']);
+
+    $account = SocialAccount::factory()->telegram()->create(['workspace_id' => $this->workspace->id]);
+
+    Http::fake([
+        '*/botTESTTOKEN/getChat*' => Http::response(['ok' => true, 'result' => ['id' => -1001234567890]], 200),
+    ]);
+
+    expect(app(ConnectionVerifier::class)->verify($account))->toBeTrue();
+});
+
+it('reports a telegram account as invalid when getChat fails', function () {
+    config(['trypost.platforms.telegram.bot_token' => 'TESTTOKEN']);
+
+    $account = SocialAccount::factory()->telegram()->create(['workspace_id' => $this->workspace->id]);
+
+    Http::fake([
+        '*/botTESTTOKEN/getChat*' => Http::response(['ok' => false, 'description' => 'chat not found'], 400),
+    ]);
+
+    expect(app(ConnectionVerifier::class)->verify($account))->toBeFalse();
+});
+
 it('registers the webhook via the artisan command', function () {
     Http::fake([
         '*/botTESTTOKEN/setWebhook' => Http::response(['ok' => true, 'result' => true], 200),
diff --git a/tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php b/tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php
new file mode 100644
index 00000000..1e577d7d
--- /dev/null
+++ b/tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php
@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Exceptions\Social\ErrorCategory;
+use App\Exceptions\Social\TelegramPublishException;
+use Illuminate\Support\Facades\Http;
+
+function telegramErrorResponse(array $body, int $status)
+{
+    return Http::fake(['*' => Http::response($body, $status)])->post('https://api.telegram.org/botX/sendMessage');
+}
+
+test('HTTP 403 maps to Permission category', function () {
+    $exception = TelegramPublishException::fromApiResponse(
+        telegramErrorResponse(['ok' => false, 'description' => 'Forbidden'], 403),
+    );
+
+    expect($exception->category)->toBe(ErrorCategory::Permission)
+        ->and($exception->platformErrorCode)->toBe('403');
+});
+
+test('HTTP 401 maps to Permission category', function () {
+    $exception = TelegramPublishException::fromApiResponse(
+        telegramErrorResponse(['ok' => false, 'description' => 'Unauthorized'], 401),
+    );
+
+    expect($exception->category)->toBe(ErrorCategory::Permission)
+        ->and($exception->platformErrorCode)->toBe('401');
+});
+
+test('HTTP 429 maps to RateLimit category', function () {
+    $exception = TelegramPublishException::fromApiResponse(
+        telegramErrorResponse(['ok' => false, 'description' => 'Too Many Requests'], 429),
+    );
+
+    expect($exception->category)->toBe(ErrorCategory::RateLimit);
+});
+
+test('HTTP 500 maps to ServerError category', function () {
+    $exception = TelegramPublishException::fromApiResponse(
+        telegramErrorResponse(['ok' => false, 'description' => 'Internal'], 500),
+    );
+
+    expect($exception->category)->toBe(ErrorCategory::ServerError);
+});
+
+test('other errors map to Unknown category with the api description', function () {
+    $exception = TelegramPublishException::fromApiResponse(
+        telegramErrorResponse(['ok' => false, 'description' => 'Bad Request: chat not found'], 400),
+    );
+
+    expect($exception->category)->toBe(ErrorCategory::Unknown)
+        ->and($exception->userMessage)->toBe('Bad Request: chat not found');
+});
+
+test('platform returns telegram', function () {
+    $exception = TelegramPublishException::fromApiResponse(
+        telegramErrorResponse(['ok' => false, 'description' => 'Error'], 400),
+    );
+
+    expect($exception->platform())->toBe('telegram');
+});

From c096092c7b8e3edd7cab15d777c6724874f31dcf Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 22:48:21 -0300
Subject: [PATCH 09/35] Polish PR: status FormRequest, sanitizer anchor guard,
 webhook limit, dedupe OAuth popup

---
 .../Controllers/Auth/TelegramController.php   |   5 +-
 .../Webhooks/TelegramWebhookController.php    |  28 +-
 .../App/Auth/TelegramStatusRequest.php        |  25 ++
 app/Services/Social/ContentSanitizer.php      |   3 +
 .../js/components/SocialAccountsGrid.vue      | 277 ++++++++++++------
 .../components/accounts/AddSocialDialog.vue   |  43 +--
 resources/js/composables/useOAuthPopup.ts     |  34 +++
 .../Services/Social/ContentSanitizerTest.php  |   6 +
 .../Feature/Social/TelegramConnectionTest.php |  54 ++++
 9 files changed, 348 insertions(+), 127 deletions(-)
 create mode 100644 app/Http/Requests/App/Auth/TelegramStatusRequest.php
 create mode 100644 resources/js/composables/useOAuthPopup.ts

diff --git a/app/Http/Controllers/Auth/TelegramController.php b/app/Http/Controllers/Auth/TelegramController.php
index 9e7d7530..a6367822 100644
--- a/app/Http/Controllers/Auth/TelegramController.php
+++ b/app/Http/Controllers/Auth/TelegramController.php
@@ -6,6 +6,7 @@
 
 use App\Enums\SocialAccount\Platform as SocialPlatform;
 use App\Enums\SocialAccount\TelegramConnectStatus;
+use App\Http\Requests\App\Auth\TelegramStatusRequest;
 use App\Models\TelegramConnectRequest;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -47,14 +48,14 @@ public function connect(Request $request): JsonResponse
     /**
      * Poll whether the channel has been linked yet.
      */
-    public function status(Request $request): JsonResponse
+    public function status(TelegramStatusRequest $request): JsonResponse
     {
         $workspace = $request->user()->currentWorkspace;
         abort_if($workspace === null, SymfonyResponse::HTTP_CONFLICT, 'No active workspace.');
 
         $connectRequest = TelegramConnectRequest::query()
             ->where('workspace_id', $workspace->id)
-            ->where('code', (string) $request->query('code'))
+            ->where('code', $request->validated('code'))
             ->first();
 
         return response()->json([
diff --git a/app/Http/Controllers/Webhooks/TelegramWebhookController.php b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
index 1ebbb066..6b281df4 100644
--- a/app/Http/Controllers/Webhooks/TelegramWebhookController.php
+++ b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
@@ -6,10 +6,13 @@
 
 use App\Enums\SocialAccount\Platform as SocialPlatform;
 use App\Enums\SocialAccount\Status;
+use App\Features\SocialAccountLimit;
 use App\Http\Controllers\Controller;
 use App\Models\TelegramConnectRequest;
+use App\Models\Workspace;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
+use Laravel\Pennant\Feature;
 use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
 
 class TelegramWebhookController extends Controller
@@ -49,7 +52,19 @@ public function handle(Request $request): Response
         $chatId = (string) data_get($chat, 'id');
         $username = data_get($chat, 'username');
 
-        $account = $connectRequest->workspace->socialAccounts()->updateOrCreate(
+        $workspace = $connectRequest->workspace;
+
+        // Mirror the controller's limit gate: block only brand-new accounts, never reconnects.
+        $isNewAccount = ! $workspace->socialAccounts()
+            ->where('platform', SocialPlatform::Telegram->value)
+            ->where('platform_user_id', $chatId)
+            ->exists();
+
+        if ($isNewAccount && $this->workspaceAtAccountLimit($workspace)) {
+            return response()->noContent();
+        }
+
+        $account = $workspace->socialAccounts()->updateOrCreate(
             [
                 'platform' => SocialPlatform::Telegram->value,
                 'platform_user_id' => $chatId,
@@ -76,4 +91,15 @@ public function handle(Request $request): Response
 
         return response()->noContent();
     }
+
+    private function workspaceAtAccountLimit(Workspace $workspace): bool
+    {
+        if (config('trypost.self_hosted')) {
+            return false;
+        }
+
+        $limit = Feature::for($workspace->account)->value(SocialAccountLimit::class);
+
+        return $workspace->socialAccounts()->count() >= $limit;
+    }
 }
diff --git a/app/Http/Requests/App/Auth/TelegramStatusRequest.php b/app/Http/Requests/App/Auth/TelegramStatusRequest.php
new file mode 100644
index 00000000..3810e203
--- /dev/null
+++ b/app/Http/Requests/App/Auth/TelegramStatusRequest.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\App\Auth;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class TelegramStatusRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'code' => ['required', 'string'],
+        ];
+    }
+}
diff --git a/app/Services/Social/ContentSanitizer.php b/app/Services/Social/ContentSanitizer.php
index 79a3ba0b..d9fa3df0 100644
--- a/app/Services/Social/ContentSanitizer.php
+++ b/app/Services/Social/ContentSanitizer.php
@@ -35,6 +35,9 @@ private function toTelegramHtml(string $content): string
         $content = preg_replace(['/<(\/?)strong>/i', '/<(\/?)em>/i'], ['<$1b>', '<$1i>'], $content);
         $content = strip_tags($content, ['b', 'i', 'u', 's', 'a', 'code', 'pre']);
 
+        // Telegram requires every <a> to carry an href; drop bare anchors so the parser doesn't reject the whole message.
+        $content = preg_replace('/<a(?![^>]*\shref=)[^>]*>(.*?)<\/a>/is', '$1', $content);
+
         // Escape bare ampersands while leaving existing entities intact.
         $content = preg_replace('/&(?!(?:amp|lt|gt|quot|#\d+);)/', '&amp;', $content);
 
diff --git a/resources/js/components/SocialAccountsGrid.vue b/resources/js/components/SocialAccountsGrid.vue
index 40b54a9e..6e2bcc63 100644
--- a/resources/js/components/SocialAccountsGrid.vue
+++ b/resources/js/components/SocialAccountsGrid.vue
@@ -1,13 +1,25 @@
 <script setup lang="ts">
 import { router } from '@inertiajs/vue3';
-import { IconAlertCircle, IconCheck, IconExternalLink, IconRefresh, IconTrash } from '@tabler/icons-vue';
+import {
+    IconAlertCircle,
+    IconCheck,
+    IconExternalLink,
+    IconRefresh,
+    IconTrash,
+} from '@tabler/icons-vue';
 import { trans } from 'laravel-vue-i18n';
-import { computed, onMounted, onUnmounted } from 'vue';
+import { computed } from 'vue';
 
 import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
 import { Button } from '@/components/ui/button';
 import { Switch } from '@/components/ui/switch';
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
+import {
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
+} from '@/components/ui/tooltip';
+import { useOAuthPopup } from '@/composables/useOAuthPopup';
 import { getPlatformLogo } from '@/composables/usePlatformLogo';
 import { toggle as toggleAccount } from '@/routes/app/accounts';
 
@@ -47,44 +59,16 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const handleToggle = (accountId: string) => {
-    router.put(toggleAccount.url(accountId), {}, {
-        preserveScroll: true,
-    });
-};
-
-const getConnectUrl = (platformValue: string): string => {
-    return `/connect/${platformValue}`;
-};
-
-const openOAuthPopup = (platformValue: string) => {
-    const url = getConnectUrl(platformValue);
-    const width = 600;
-    const height = 700;
-    const left = window.screenX + (window.outerWidth - width) / 2;
-    const top = window.screenY + (window.outerHeight - height) / 2;
-
-    window.open(
-        url,
-        'oauth-popup',
-        `width=${width},height=${height},left=${left},top=${top},scrollbars=yes,resizable=yes`
+    router.put(
+        toggleAccount.url(accountId),
+        {},
+        {
+            preserveScroll: true,
+        },
     );
 };
 
-const handleOAuthMessage = (event: MessageEvent) => {
-    if (event.origin !== window.location.origin) return;
-    if (event.data?.type !== 'social-oauth-callback') return;
-
-    // Reload the page to get fresh data
-    router.reload();
-};
-
-onMounted(() => {
-    window.addEventListener('message', handleOAuthMessage);
-});
-
-onUnmounted(() => {
-    window.removeEventListener('message', handleOAuthMessage);
-});
+const { openOAuthPopup } = useOAuthPopup(() => router.reload());
 
 const gridClass = computed(() => {
     switch (props.columns) {
@@ -102,7 +86,11 @@ const emit = defineEmits<{
     disconnect: [accountId: string];
 }>();
 
-const getProfileUrl = (platform: string, username: string | null, platformUserId: string | null = null): string | null => {
+const getProfileUrl = (
+    platform: string,
+    username: string | null,
+    platformUserId: string | null = null,
+): string | null => {
     if (platform === 'facebook') {
         const identifier = username || platformUserId;
         return identifier ? `https://facebook.com/${identifier}` : null;
@@ -111,66 +99,112 @@ const getProfileUrl = (platform: string, username: string | null, platformUserId
     if (!username) return null;
 
     const urls: Record<string, string> = {
-        'linkedin': `https://linkedin.com/in/${username}`,
+        linkedin: `https://linkedin.com/in/${username}`,
         'linkedin-page': `https://linkedin.com/company/${username}`,
-        'x': `https://x.com/${username}`,
-        'tiktok': `https://tiktok.com/@${username}`,
-        'instagram': `https://instagram.com/${username}`,
+        x: `https://x.com/${username}`,
+        tiktok: `https://tiktok.com/@${username}`,
+        instagram: `https://instagram.com/${username}`,
         'instagram-facebook': `https://instagram.com/${username}`,
-        'youtube': `https://youtube.com/@${username}`,
-        'threads': `https://threads.net/@${username}`,
-        'bluesky': `https://bsky.app/profile/${username}`,
-        'pinterest': `https://pinterest.com/${username}`,
-        'telegram': `https://t.me/${username}`,
+        youtube: `https://youtube.com/@${username}`,
+        threads: `https://threads.net/@${username}`,
+        bluesky: `https://bsky.app/profile/${username}`,
+        pinterest: `https://pinterest.com/${username}`,
+        telegram: `https://t.me/${username}`,
     };
     return urls[platform] || null;
 };
 
 const isDisconnected = (account: SocialAccount | null): boolean => {
     if (!account) return false;
-    return account.status === 'disconnected' || account.status === 'token_expired';
+    return (
+        account.status === 'disconnected' || account.status === 'token_expired'
+    );
 };
 </script>
 
 <template>
     <div class="grid gap-4" :class="gridClass">
-        <div v-for="platform in platforms" :key="platform.value"
-            class="group relative overflow-hidden rounded-xl border bg-card transition-all hover:shadow-md" :class="{
-                'border-green-500/30 bg-green-50/50 dark:bg-green-950/20': platform.connected && !isDisconnected(platform.account) && platform.account?.is_active,
-                'border-red-500/30 bg-red-50/50 dark:bg-red-950/20': platform.connected && (isDisconnected(platform.account) || !platform.account?.is_active),
-            }">
+        <div
+            v-for="platform in platforms"
+            :key="platform.value"
+            class="group relative overflow-hidden rounded-xl border bg-card transition-all hover:shadow-md"
+            :class="{
+                'border-green-500/30 bg-green-50/50 dark:bg-green-950/20':
+                    platform.connected &&
+                    !isDisconnected(platform.account) &&
+                    platform.account?.is_active,
+                'border-red-500/30 bg-red-50/50 dark:bg-red-950/20':
+                    platform.connected &&
+                    (isDisconnected(platform.account) ||
+                        !platform.account?.is_active),
+            }"
+        >
             <!-- Platform Header -->
             <div class="flex items-center gap-3 p-4">
                 <div class="relative">
-                    <img :src="getPlatformLogo(platform.value)" :alt="platform.label"
+                    <img
+                        :src="getPlatformLogo(platform.value)"
+                        :alt="platform.label"
                         class="h-10 w-10 rounded-full object-contain"
-                        :class="{ 'opacity-40': platform.connected && platform.account && !platform.account.is_active }" />
-                    <div v-if="platform.connected && !isDisconnected(platform.account)"
-                        class="absolute -bottom-0.5 -right-0.5 flex h-4 w-4 items-center justify-center rounded-full bg-green-500 text-white ring-2 ring-white dark:ring-neutral-900">
+                        :class="{
+                            'opacity-40':
+                                platform.connected &&
+                                platform.account &&
+                                !platform.account.is_active,
+                        }"
+                    />
+                    <div
+                        v-if="
+                            platform.connected &&
+                            !isDisconnected(platform.account)
+                        "
+                        class="absolute -right-0.5 -bottom-0.5 flex h-4 w-4 items-center justify-center rounded-full bg-green-500 text-white ring-2 ring-white dark:ring-neutral-900"
+                    >
                         <IconCheck class="h-2 w-2" />
                     </div>
-                    <div v-else-if="platform.connected && isDisconnected(platform.account)"
-                        class="absolute -bottom-0.5 -right-0.5 flex h-4 w-4 items-center justify-center rounded-full bg-red-500 text-white ring-2 ring-white dark:ring-neutral-900">
+                    <div
+                        v-else-if="
+                            platform.connected &&
+                            isDisconnected(platform.account)
+                        "
+                        class="absolute -right-0.5 -bottom-0.5 flex h-4 w-4 items-center justify-center rounded-full bg-red-500 text-white ring-2 ring-white dark:ring-neutral-900"
+                    >
                         <IconAlertCircle class="h-2 w-2" />
                     </div>
                 </div>
-                <div class="flex-1 min-w-0">
+                <div class="min-w-0 flex-1">
                     <div class="flex items-center justify-between gap-2">
-                        <div class="flex items-center gap-1 min-w-0">
-                            <h3 class="font-semibold leading-tight">
+                        <div class="flex min-w-0 items-center gap-1">
+                            <h3 class="leading-tight font-semibold">
                                 <template v-if="platform.label.includes('(')">
-                                    {{ platform.label.split('(')[0].trim() }}<br />
-                                    <span class="text-xs font-normal text-muted-foreground">({{
-                                        platform.label.split('(')[1] }}</span>
+                                    {{ platform.label.split('(')[0].trim()
+                                    }}<br />
+                                    <span
+                                        class="text-xs font-normal text-muted-foreground"
+                                        >({{
+                                            platform.label.split('(')[1]
+                                        }}</span
+                                    >
                                 </template>
                                 <template v-else>{{ platform.label }}</template>
                             </h3>
                         </div>
-                        <Switch v-if="platform.connected && platform.account" :model-value="platform.account.is_active"
-                            @update:model-value="handleToggle(platform.account.id)" />
+                        <Switch
+                            v-if="platform.connected && platform.account"
+                            :model-value="platform.account.is_active"
+                            @update:model-value="
+                                handleToggle(platform.account.id)
+                            "
+                        />
                     </div>
-                    <p v-if="platform.connected && platform.account" class="text-sm text-muted-foreground truncate">
-                        @{{ platform.account.username || platform.account.display_name }}
+                    <p
+                        v-if="platform.connected && platform.account"
+                        class="truncate text-sm text-muted-foreground"
+                    >
+                        @{{
+                            platform.account.username ||
+                            platform.account.display_name
+                        }}
                     </p>
                     <p v-else class="text-sm text-muted-foreground">
                         {{ trans('accounts.not_connected') }}
@@ -179,14 +213,24 @@ const isDisconnected = (account: SocialAccount | null): boolean => {
             </div>
 
             <!-- Connected State -->
-            <div v-if="platform.connected && platform.account" class="border-t px-4 py-3">
+            <div
+                v-if="platform.connected && platform.account"
+                class="border-t px-4 py-3"
+            >
                 <!-- Disconnected Warning -->
-                <div v-if="isDisconnected(platform.account)"
-                    class="mb-3 flex items-start gap-2 rounded-lg bg-red-100 p-2 text-sm text-red-700 dark:bg-red-900/30 dark:text-red-400">
-                    <IconAlertCircle class="h-4 w-4 mt-0.5 shrink-0" />
-                    <div class="flex-1 min-w-0">
-                        <p class="font-medium">{{ trans('accounts.connection_lost') }}</p>
-                        <p v-if="platform.account.error_message" class="text-xs truncate opacity-80">
+                <div
+                    v-if="isDisconnected(platform.account)"
+                    class="mb-3 flex items-start gap-2 rounded-lg bg-red-100 p-2 text-sm text-red-700 dark:bg-red-900/30 dark:text-red-400"
+                >
+                    <IconAlertCircle class="mt-0.5 h-4 w-4 shrink-0" />
+                    <div class="min-w-0 flex-1">
+                        <p class="font-medium">
+                            {{ trans('accounts.connection_lost') }}
+                        </p>
+                        <p
+                            v-if="platform.account.error_message"
+                            class="truncate text-xs opacity-80"
+                        >
                             {{ platform.account.error_message }}
                         </p>
                     </div>
@@ -195,38 +239,77 @@ const isDisconnected = (account: SocialAccount | null): boolean => {
                 <div class="flex items-center justify-between">
                     <div class="flex items-center gap-2">
                         <Avatar class="h-8 w-8">
-                            <AvatarImage v-if="platform.account.avatar_url" :src="platform.account.avatar_url" />
+                            <AvatarImage
+                                v-if="platform.account.avatar_url"
+                                :src="platform.account.avatar_url"
+                            />
                             <AvatarFallback class="text-xs">
                                 {{ platform.account.display_name?.charAt(0) }}
                             </AvatarFallback>
                         </Avatar>
-                        <span class="text-sm font-medium truncate max-w-[120px]">
+                        <span
+                            class="max-w-[120px] truncate text-sm font-medium"
+                        >
                             {{ platform.account.display_name }}
                         </span>
                     </div>
                     <div class="flex items-center gap-1">
                         <!-- Reconnect button for disconnected accounts -->
-                        <TooltipProvider v-if="showReconnect && isDisconnected(platform.account)">
+                        <TooltipProvider
+                            v-if="
+                                showReconnect &&
+                                isDisconnected(platform.account)
+                            "
+                        >
                             <Tooltip>
                                 <TooltipTrigger as-child>
-                                    <Button variant="ghost" size="icon"
+                                    <Button
+                                        variant="ghost"
+                                        size="icon"
                                         class="size-8 text-amber-600 hover:text-amber-700"
-                                        @click="openOAuthPopup(platform.value)">
+                                        @click="openOAuthPopup(platform.value)"
+                                    >
                                         <IconRefresh class="size-4" />
                                     </Button>
                                 </TooltipTrigger>
                                 <TooltipContent>
-                                    <p>{{ trans('accounts.reconnect_account') }}</p>
+                                    <p>
+                                        {{
+                                            trans('accounts.reconnect_account')
+                                        }}
+                                    </p>
                                 </TooltipContent>
                             </Tooltip>
                         </TooltipProvider>
                         <TooltipProvider
-                            v-if="showViewProfile && getProfileUrl(platform.value, platform.account.username, platform.account.platform_user_id)">
+                            v-if="
+                                showViewProfile &&
+                                getProfileUrl(
+                                    platform.value,
+                                    platform.account.username,
+                                    platform.account.platform_user_id,
+                                )
+                            "
+                        >
                             <Tooltip>
                                 <TooltipTrigger as-child>
-                                    <Button variant="ghost" size="icon" class="size-8" as-child>
-                                        <a :href="getProfileUrl(platform.value, platform.account.username, platform.account.platform_user_id)!"
-                                            target="_blank">
+                                    <Button
+                                        variant="ghost"
+                                        size="icon"
+                                        class="size-8"
+                                        as-child
+                                    >
+                                        <a
+                                            :href="
+                                                getProfileUrl(
+                                                    platform.value,
+                                                    platform.account.username,
+                                                    platform.account
+                                                        .platform_user_id,
+                                                )!
+                                            "
+                                            target="_blank"
+                                        >
                                             <IconExternalLink class="size-4" />
                                         </a>
                                     </Button>
@@ -239,8 +322,17 @@ const isDisconnected = (account: SocialAccount | null): boolean => {
                         <TooltipProvider v-if="showDisconnect">
                             <Tooltip>
                                 <TooltipTrigger as-child>
-                                    <Button variant="ghost" size="icon" class="size-8"
-                                        @click="emit('disconnect', platform.account.id)">
+                                    <Button
+                                        variant="ghost"
+                                        size="icon"
+                                        class="size-8"
+                                        @click="
+                                            emit(
+                                                'disconnect',
+                                                platform.account.id,
+                                            )
+                                        "
+                                    >
                                         <IconTrash class="size-4" />
                                     </Button>
                                 </TooltipTrigger>
@@ -255,7 +347,12 @@ const isDisconnected = (account: SocialAccount | null): boolean => {
 
             <!-- Not Connected State -->
             <div v-else class="border-t px-4 py-3">
-                <Button variant="outline" class="w-full" size="sm" @click="openOAuthPopup(platform.value)">
+                <Button
+                    variant="outline"
+                    class="w-full"
+                    size="sm"
+                    @click="openOAuthPopup(platform.value)"
+                >
                     {{ trans('accounts.connect') }}
                 </Button>
             </div>
diff --git a/resources/js/components/accounts/AddSocialDialog.vue b/resources/js/components/accounts/AddSocialDialog.vue
index 46eaac40..bb754109 100644
--- a/resources/js/components/accounts/AddSocialDialog.vue
+++ b/resources/js/components/accounts/AddSocialDialog.vue
@@ -2,7 +2,7 @@
 import { router } from '@inertiajs/vue3';
 import { IconPlus } from '@tabler/icons-vue';
 import { trans } from 'laravel-vue-i18n';
-import { onMounted, onUnmounted, ref } from 'vue';
+import { ref } from 'vue';
 
 import TelegramConnectDialog from '@/components/accounts/TelegramConnectDialog.vue';
 import { Button } from '@/components/ui/button';
@@ -13,6 +13,7 @@ import {
     DialogHeader,
     DialogTitle,
 } from '@/components/ui/dialog';
+import { useOAuthPopup } from '@/composables/useOAuthPopup';
 
 export interface AvailablePlatform {
     value: string;
@@ -109,47 +110,21 @@ const themeFor = (value: string) =>
 
 const telegramOpen = ref(false);
 
+const { openOAuthPopup } = useOAuthPopup(() => {
+    open.value = false;
+    router.reload();
+});
+
 const connectPlatform = (platformValue: string) => {
+    open.value = false;
+
     if (platformValue === 'telegram') {
-        open.value = false;
         telegramOpen.value = true;
         return;
     }
 
     openOAuthPopup(platformValue);
 };
-
-const openOAuthPopup = (platformValue: string) => {
-    const url = `/connect/${platformValue}`;
-    const width = 600;
-    const height = 700;
-    const left = window.screenX + (window.outerWidth - width) / 2;
-    const top = window.screenY + (window.outerHeight - height) / 2;
-
-    open.value = false;
-
-    window.open(
-        url,
-        'oauth-popup',
-        `width=${width},height=${height},left=${left},top=${top},scrollbars=yes,resizable=yes`,
-    );
-};
-
-const handleOAuthMessage = (event: MessageEvent) => {
-    if (event.origin !== window.location.origin) return;
-    if (event.data?.type !== 'social-oauth-callback') return;
-
-    open.value = false;
-    router.reload();
-};
-
-onMounted(() => {
-    window.addEventListener('message', handleOAuthMessage);
-});
-
-onUnmounted(() => {
-    window.removeEventListener('message', handleOAuthMessage);
-});
 </script>
 
 <template>
diff --git a/resources/js/composables/useOAuthPopup.ts b/resources/js/composables/useOAuthPopup.ts
new file mode 100644
index 00000000..9f6e24f3
--- /dev/null
+++ b/resources/js/composables/useOAuthPopup.ts
@@ -0,0 +1,34 @@
+import { onMounted, onUnmounted } from 'vue';
+
+const POPUP_WIDTH = 600;
+const POPUP_HEIGHT = 700;
+
+/**
+ * Opens a platform's `/connect/{platform}` OAuth flow in a centered popup and
+ * invokes `onSuccess` when the popup posts back the `social-oauth-callback`
+ * message. The listener is wired to the calling component's lifecycle.
+ */
+export const useOAuthPopup = (onSuccess: () => void) => {
+    const openOAuthPopup = (platform: string) => {
+        const left = window.screenX + (window.outerWidth - POPUP_WIDTH) / 2;
+        const top = window.screenY + (window.outerHeight - POPUP_HEIGHT) / 2;
+
+        window.open(
+            `/connect/${platform}`,
+            'oauth-popup',
+            `width=${POPUP_WIDTH},height=${POPUP_HEIGHT},left=${left},top=${top},scrollbars=yes,resizable=yes`,
+        );
+    };
+
+    const handleMessage = (event: MessageEvent) => {
+        if (event.origin !== window.location.origin) return;
+        if (event.data?.type !== 'social-oauth-callback') return;
+
+        onSuccess();
+    };
+
+    onMounted(() => window.addEventListener('message', handleMessage));
+    onUnmounted(() => window.removeEventListener('message', handleMessage));
+
+    return { openOAuthPopup };
+};
diff --git a/tests/Feature/Services/Social/ContentSanitizerTest.php b/tests/Feature/Services/Social/ContentSanitizerTest.php
index 4bd97ae4..4acbc3fb 100644
--- a/tests/Feature/Services/Social/ContentSanitizerTest.php
+++ b/tests/Feature/Services/Social/ContentSanitizerTest.php
@@ -94,3 +94,9 @@
     $result = $sanitizer->sanitize('Tom &amp; Jerry & friends', Platform::Telegram);
     expect($result)->toBe('Tom &amp; Jerry &amp; friends');
 });
+
+test('it drops anchors without an href for telegram', function () {
+    $sanitizer = new ContentSanitizer;
+    $result = $sanitizer->sanitize('<p>see <a>bare</a> and <a href="https://x.com">link</a></p>', Platform::Telegram);
+    expect($result)->toBe('see bare and <a href="https://x.com">link</a>');
+});
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index e930537f..81bbefee 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -102,6 +102,60 @@ function telegramUpdate(string $code, array $chat = []): array
     expect(data_get($account->meta, 'username'))->toBeNull();
 });
 
+it('does not create a new telegram account when the workspace is at its limit', function () {
+    config(['trypost.self_hosted' => false]);
+
+    SocialAccount::factory()->count(5)->create(['workspace_id' => $this->workspace->id]);
+
+    TelegramConnectRequest::create([
+        'workspace_id' => $this->workspace->id,
+        'user_id' => $this->user->id,
+        'code' => 'limitcode',
+        'expires_at' => now()->addMinutes(15),
+    ]);
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate('limitcode'))
+        ->assertNoContent();
+
+    expect($this->workspace->socialAccounts()->count())->toBe(5);
+    expect(
+        SocialAccount::where('platform', Platform::Telegram)->where('platform_user_id', '-1001234567890')->exists()
+    )->toBeFalse();
+});
+
+it('still reconnects an existing telegram channel even at the account limit', function () {
+    config(['trypost.self_hosted' => false]);
+
+    SocialAccount::factory()->count(4)->create(['workspace_id' => $this->workspace->id]);
+    SocialAccount::factory()->telegram()->create([
+        'workspace_id' => $this->workspace->id,
+        'platform_user_id' => '-1001234567890',
+    ]);
+
+    TelegramConnectRequest::create([
+        'workspace_id' => $this->workspace->id,
+        'user_id' => $this->user->id,
+        'code' => 'reconnectcode',
+        'expires_at' => now()->addMinutes(15),
+    ]);
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate('reconnectcode'))
+        ->assertNoContent();
+
+    expect($this->workspace->socialAccounts()->count())->toBe(5);
+    expect(
+        SocialAccount::where('platform', Platform::Telegram)->where('platform_user_id', '-1001234567890')->count()
+    )->toBe(1);
+});
+
+it('requires a code to check connection status', function () {
+    $this->actingAs($this->user)
+        ->getJson(route('app.social.telegram.status'))
+        ->assertStatus(422);
+});
+
 it('rejects the webhook without the secret token', function () {
     $this->postJson(route('telegram.webhook'), telegramUpdate('whatever'))
         ->assertForbidden();

From 816d367dbe83b24d541dbfe6c5c444515d1e6d74 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sat, 13 Jun 2026 22:58:04 -0300
Subject: [PATCH 10/35] Add return type to telegram exception test helper

---
 tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php b/tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php
index 1e577d7d..3be8f1d8 100644
--- a/tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php
+++ b/tests/Unit/Exceptions/Social/TelegramPublishExceptionTest.php
@@ -4,9 +4,10 @@
 
 use App\Exceptions\Social\ErrorCategory;
 use App\Exceptions\Social\TelegramPublishException;
+use Illuminate\Http\Client\Response;
 use Illuminate\Support\Facades\Http;
 
-function telegramErrorResponse(array $body, int $status)
+function telegramErrorResponse(array $body, int $status): Response
 {
     return Http::fake(['*' => Http::response($body, $status)])->post('https://api.telegram.org/botX/sendMessage');
 }

From 2284596f9d77fd0dd78a9bc583739a0f5f5bed7c Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 08:57:38 -0300
Subject: [PATCH 11/35] Make Telegram connect codes stateless: drop the
 model/table, use a signed code + session

---
 .../SocialAccount/TelegramConnectStatus.php   |  14 +--
 .../Controllers/Auth/TelegramController.php   |  43 +++----
 .../Webhooks/TelegramWebhookController.php    |  22 ++--
 .../App/Auth/TelegramStatusRequest.php        |  25 ----
 app/Models/TelegramConnectRequest.php         |  40 -------
 app/Services/Social/TelegramConnectCode.php   |  53 +++++++++
 ...create_telegram_connect_requests_table.php |  29 -----
 .../accounts/TelegramConnectDialog.vue        |   9 +-
 .../Feature/Social/TelegramConnectionTest.php | 107 +++++++-----------
 9 files changed, 134 insertions(+), 208 deletions(-)
 delete mode 100644 app/Http/Requests/App/Auth/TelegramStatusRequest.php
 delete mode 100644 app/Models/TelegramConnectRequest.php
 create mode 100644 app/Services/Social/TelegramConnectCode.php
 delete mode 100644 database/migrations/2026_06_14_002757_create_telegram_connect_requests_table.php

diff --git a/app/Enums/SocialAccount/TelegramConnectStatus.php b/app/Enums/SocialAccount/TelegramConnectStatus.php
index 3afeb0bc..56c006f9 100644
--- a/app/Enums/SocialAccount/TelegramConnectStatus.php
+++ b/app/Enums/SocialAccount/TelegramConnectStatus.php
@@ -4,25 +4,19 @@
 
 namespace App\Enums\SocialAccount;
 
-use App\Models\TelegramConnectRequest;
+use App\Models\SocialAccount;
 
 enum TelegramConnectStatus: string
 {
     case Unknown = 'unknown';
     case Pending = 'pending';
     case Connected = 'connected';
-    case Expired = 'expired';
 
     /**
-     * Derive the connection status the frontend polls for from a connect request.
+     * Connected once the channel has been linked to an account; otherwise still pending.
      */
-    public static function for(?TelegramConnectRequest $request): self
+    public static function for(?SocialAccount $account): self
     {
-        return match (true) {
-            $request === null => self::Unknown,
-            $request->social_account_id !== null => self::Connected,
-            $request->isExpired() => self::Expired,
-            default => self::Pending,
-        };
+        return $account === null ? self::Pending : self::Connected;
     }
 }
diff --git a/app/Http/Controllers/Auth/TelegramController.php b/app/Http/Controllers/Auth/TelegramController.php
index a6367822..e7fd8202 100644
--- a/app/Http/Controllers/Auth/TelegramController.php
+++ b/app/Http/Controllers/Auth/TelegramController.php
@@ -6,20 +6,21 @@
 
 use App\Enums\SocialAccount\Platform as SocialPlatform;
 use App\Enums\SocialAccount\TelegramConnectStatus;
-use App\Http\Requests\App\Auth\TelegramStatusRequest;
-use App\Models\TelegramConnectRequest;
+use App\Services\Social\TelegramConnectCode;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
-use Illuminate\Support\Str;
 use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
 
 class TelegramController extends SocialController
 {
     protected SocialPlatform $platform = SocialPlatform::Telegram;
 
+    private const SESSION_KEY = 'telegram_connect_code';
+
     /**
-     * Start a connection: issue a one-time code the user posts in their channel
-     * (`/connect <code>`) so the webhook can tie the channel to this workspace.
+     * Start a connection: issue a signed one-off code the user posts in their
+     * channel (`/connect <code>`). The code carries the workspace, so the webhook
+     * can link the channel without any persisted state.
      */
     public function connect(Request $request): JsonResponse
     {
@@ -31,35 +32,39 @@ public function connect(Request $request): JsonResponse
         $this->authorize('manageAccounts', $workspace);
         $this->ensureSocialAccountLimit($workspace);
 
-        $connectRequest = TelegramConnectRequest::create([
-            'workspace_id' => $workspace->id,
-            'user_id' => $request->user()->id,
-            'code' => Str::lower(Str::random(12)),
-            'expires_at' => now()->addMinutes(15),
-        ]);
+        $expiresAt = now()->addMinutes(15);
+        $code = TelegramConnectCode::issue($workspace->id, $expiresAt);
+
+        $request->session()->put(self::SESSION_KEY, $code);
 
         return response()->json([
-            'code' => $connectRequest->code,
+            'code' => $code,
             'bot_username' => config('trypost.platforms.telegram.bot_username'),
-            'expires_at' => $connectRequest->expires_at->toIso8601String(),
+            'expires_at' => $expiresAt->toIso8601String(),
         ]);
     }
 
     /**
-     * Poll whether the channel has been linked yet.
+     * Poll whether the channel issued in this session has been linked yet.
      */
-    public function status(TelegramStatusRequest $request): JsonResponse
+    public function status(Request $request): JsonResponse
     {
         $workspace = $request->user()->currentWorkspace;
         abort_if($workspace === null, SymfonyResponse::HTTP_CONFLICT, 'No active workspace.');
 
-        $connectRequest = TelegramConnectRequest::query()
-            ->where('workspace_id', $workspace->id)
-            ->where('code', $request->validated('code'))
+        $payload = TelegramConnectCode::decode($request->session()->get(self::SESSION_KEY));
+
+        if ($payload === null) {
+            return response()->json(['status' => TelegramConnectStatus::Unknown->value]);
+        }
+
+        $account = $workspace->socialAccounts()
+            ->where('platform', SocialPlatform::Telegram->value)
+            ->where('meta->connect_nonce', data_get($payload, 'nonce'))
             ->first();
 
         return response()->json([
-            'status' => TelegramConnectStatus::for($connectRequest)->value,
+            'status' => TelegramConnectStatus::for($account)->value,
         ]);
     }
 }
diff --git a/app/Http/Controllers/Webhooks/TelegramWebhookController.php b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
index 6b281df4..4d673c45 100644
--- a/app/Http/Controllers/Webhooks/TelegramWebhookController.php
+++ b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
@@ -8,8 +8,8 @@
 use App\Enums\SocialAccount\Status;
 use App\Features\SocialAccountLimit;
 use App\Http\Controllers\Controller;
-use App\Models\TelegramConnectRequest;
 use App\Models\Workspace;
+use App\Services\Social\TelegramConnectCode;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
 use Laravel\Pennant\Feature;
@@ -19,8 +19,8 @@ class TelegramWebhookController extends Controller
 {
     /**
      * Receives Bot API updates. The only update we act on is a `/connect <code>`
-     * message/channel_post: it ties the originating channel to the workspace that
-     * generated the code. Everything else is acknowledged and ignored.
+     * message/channel_post: the signed code carries the workspace, so we link the
+     * originating channel to it. Everything else is acknowledged and ignored.
      */
     public function handle(Request $request): Response
     {
@@ -39,21 +39,16 @@ public function handle(Request $request): Response
             return response()->noContent();
         }
 
-        $connectRequest = TelegramConnectRequest::query()
-            ->whereNull('social_account_id')
-            ->where('code', $matches[1])
-            ->where('expires_at', '>', now())
-            ->first();
+        $payload = TelegramConnectCode::decode($matches[1]);
+        $workspace = $payload === null ? null : Workspace::find(data_get($payload, 'workspace_id'));
 
-        if ($connectRequest === null) {
+        if ($workspace === null) {
             return response()->noContent();
         }
 
         $chatId = (string) data_get($chat, 'id');
         $username = data_get($chat, 'username');
 
-        $workspace = $connectRequest->workspace;
-
         // Mirror the controller's limit gate: block only brand-new accounts, never reconnects.
         $isNewAccount = ! $workspace->socialAccounts()
             ->where('platform', SocialPlatform::Telegram->value)
@@ -64,7 +59,7 @@ public function handle(Request $request): Response
             return response()->noContent();
         }
 
-        $account = $workspace->socialAccounts()->updateOrCreate(
+        $workspace->socialAccounts()->updateOrCreate(
             [
                 'platform' => SocialPlatform::Telegram->value,
                 'platform_user_id' => $chatId,
@@ -83,12 +78,11 @@ public function handle(Request $request): Response
                     'chat_id' => $chatId,
                     'username' => $username,
                     'type' => data_get($chat, 'type'),
+                    'connect_nonce' => data_get($payload, 'nonce'),
                 ],
             ],
         );
 
-        $connectRequest->update(['social_account_id' => $account->id]);
-
         return response()->noContent();
     }
 
diff --git a/app/Http/Requests/App/Auth/TelegramStatusRequest.php b/app/Http/Requests/App/Auth/TelegramStatusRequest.php
deleted file mode 100644
index 3810e203..00000000
--- a/app/Http/Requests/App/Auth/TelegramStatusRequest.php
+++ /dev/null
@@ -1,25 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace App\Http\Requests\App\Auth;
-
-use Illuminate\Foundation\Http\FormRequest;
-
-class TelegramStatusRequest extends FormRequest
-{
-    public function authorize(): bool
-    {
-        return true;
-    }
-
-    /**
-     * @return array<string, mixed>
-     */
-    public function rules(): array
-    {
-        return [
-            'code' => ['required', 'string'],
-        ];
-    }
-}
diff --git a/app/Models/TelegramConnectRequest.php b/app/Models/TelegramConnectRequest.php
deleted file mode 100644
index 5f44a283..00000000
--- a/app/Models/TelegramConnectRequest.php
+++ /dev/null
@@ -1,40 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace App\Models;
-
-use Illuminate\Database\Eloquent\Concerns\HasUuids;
-use Illuminate\Database\Eloquent\Factories\HasFactory;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
-
-class TelegramConnectRequest extends Model
-{
-    use HasFactory;
-    use HasUuids;
-
-    protected $guarded = [];
-
-    protected function casts(): array
-    {
-        return [
-            'expires_at' => 'datetime',
-        ];
-    }
-
-    public function isExpired(): bool
-    {
-        return $this->expires_at->isPast();
-    }
-
-    public function workspace(): BelongsTo
-    {
-        return $this->belongsTo(Workspace::class);
-    }
-
-    public function user(): BelongsTo
-    {
-        return $this->belongsTo(User::class);
-    }
-}
diff --git a/app/Services/Social/TelegramConnectCode.php b/app/Services/Social/TelegramConnectCode.php
new file mode 100644
index 00000000..97cb45f5
--- /dev/null
+++ b/app/Services/Social/TelegramConnectCode.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Social;
+
+use Carbon\CarbonInterface;
+use Illuminate\Contracts\Encryption\DecryptException;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Str;
+
+/**
+ * A stateless, signed `/connect` code. It carries the workspace it belongs to,
+ * a one-off nonce (so the polling UI can recognise its own connection) and an
+ * expiry — encrypted with the app key, so the webhook can trust it without any
+ * database lookup.
+ */
+class TelegramConnectCode
+{
+    public static function issue(string $workspaceId, CarbonInterface $expiresAt): string
+    {
+        return Crypt::encryptString((string) json_encode([
+            'workspace_id' => $workspaceId,
+            'nonce' => Str::lower(Str::random(16)),
+            'expires_at' => $expiresAt->getTimestamp(),
+        ]));
+    }
+
+    /**
+     * Decode and validate a code, returning its payload or null when the code is
+     * missing, tampered with, or expired.
+     *
+     * @return array{workspace_id: string, nonce: string, expires_at: int}|null
+     */
+    public static function decode(?string $code): ?array
+    {
+        if (! is_string($code) || $code === '') {
+            return null;
+        }
+
+        try {
+            $payload = json_decode(Crypt::decryptString($code), true);
+        } catch (DecryptException) {
+            return null;
+        }
+
+        if (! is_array($payload) || now()->getTimestamp() > (int) data_get($payload, 'expires_at')) {
+            return null;
+        }
+
+        return $payload;
+    }
+}
diff --git a/database/migrations/2026_06_14_002757_create_telegram_connect_requests_table.php b/database/migrations/2026_06_14_002757_create_telegram_connect_requests_table.php
deleted file mode 100644
index ed34310a..00000000
--- a/database/migrations/2026_06_14_002757_create_telegram_connect_requests_table.php
+++ /dev/null
@@ -1,29 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-use Illuminate\Database\Migrations\Migration;
-use Illuminate\Database\Schema\Blueprint;
-use Illuminate\Support\Facades\Schema;
-
-return new class extends Migration
-{
-    public function up(): void
-    {
-        Schema::create('telegram_connect_requests', function (Blueprint $table) {
-            $table->uuid('id')->primary();
-            $table->foreignUuid('workspace_id')->constrained('workspaces')->cascadeOnDelete();
-            $table->foreignUuid('user_id')->nullable()->constrained('users')->nullOnDelete();
-            $table->string('code')->unique();
-            // Set by the webhook once the channel is linked; null while pending.
-            $table->foreignUuid('social_account_id')->nullable()->constrained('social_accounts')->nullOnDelete();
-            $table->timestamp('expires_at');
-            $table->timestamps();
-        });
-    }
-
-    public function down(): void
-    {
-        Schema::dropIfExists('telegram_connect_requests');
-    }
-};
diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index d295a372..57c701e3 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -23,7 +23,7 @@ import {
 const open = defineModel<boolean>('open', { required: true });
 
 type Phase = 'loading' | 'ready' | 'connected' | 'expired' | 'error';
-type ConnectStatus = 'unknown' | 'pending' | 'connected' | 'expired';
+type ConnectStatus = 'unknown' | 'pending' | 'connected';
 
 interface ConnectResponse {
     code: string;
@@ -57,9 +57,7 @@ const poll = async () => {
     if (phase.value !== 'ready') return;
 
     try {
-        const response = await httpStatus.get(
-            telegramStatus.url({ query: { code: code.value } }),
-        );
+        const response = await httpStatus.get(telegramStatus.url());
 
         if (response?.status === 'connected') {
             phase.value = 'connected';
@@ -72,7 +70,8 @@ const poll = async () => {
             return;
         }
 
-        if (response?.status === 'expired' || response?.status === 'unknown') {
+        // The signed code expired (or the session was lost): prompt a fresh one.
+        if (response?.status === 'unknown') {
             phase.value = 'expired';
             stopPolling();
             return;
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index 81bbefee..4bd19bb2 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -5,10 +5,10 @@
 use App\Enums\SocialAccount\Platform;
 use App\Enums\UserWorkspace\Role;
 use App\Models\SocialAccount;
-use App\Models\TelegramConnectRequest;
 use App\Models\User;
 use App\Models\Workspace;
 use App\Services\Social\ConnectionVerifier;
+use App\Services\Social\TelegramConnectCode;
 use Illuminate\Support\Facades\Http;
 
 beforeEach(function () {
@@ -43,31 +43,23 @@ function telegramUpdate(string $code, array $chat = []): array
     ];
 }
 
-it('issues a connect code', function () {
+it('issues a signed connect code and stores it in the session', function () {
     $response = $this->actingAs($this->user)
         ->postJson(route('app.social.telegram.connect'))
         ->assertOk()
-        ->assertJsonStructure(['code', 'bot_username', 'expires_at']);
+        ->assertJsonStructure(['code', 'bot_username', 'expires_at'])
+        ->assertSessionHas('telegram_connect_code');
 
     expect($response->json('bot_username'))->toBe('TryPostBot');
-
-    $this->assertDatabaseHas('telegram_connect_requests', [
-        'workspace_id' => $this->workspace->id,
-        'code' => $response->json('code'),
-        'social_account_id' => null,
-    ]);
+    expect(data_get(TelegramConnectCode::decode($response->json('code')), 'workspace_id'))
+        ->toBe($this->workspace->id);
 });
 
 it('links the channel when the webhook receives a matching /connect', function () {
-    $request = TelegramConnectRequest::create([
-        'workspace_id' => $this->workspace->id,
-        'user_id' => $this->user->id,
-        'code' => 'abc123code',
-        'expires_at' => now()->addMinutes(15),
-    ]);
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
-        ->postJson(route('telegram.webhook'), telegramUpdate('abc123code'))
+        ->postJson(route('telegram.webhook'), telegramUpdate($code))
         ->assertNoContent();
 
     $account = SocialAccount::where('workspace_id', $this->workspace->id)
@@ -79,20 +71,15 @@ function telegramUpdate(string $code, array $chat = []): array
     expect($account->display_name)->toBe('My Channel');
     expect($account->username)->toBe('mychannel');
     expect(data_get($account->meta, 'chat_id'))->toBe('-1001234567890');
-
-    expect($request->fresh()->social_account_id)->toBe($account->id);
+    expect(data_get($account->meta, 'connect_nonce'))
+        ->toBe(data_get(TelegramConnectCode::decode($code), 'nonce'));
 });
 
 it('links a private channel that has no username', function () {
-    TelegramConnectRequest::create([
-        'workspace_id' => $this->workspace->id,
-        'user_id' => $this->user->id,
-        'code' => 'privatecode',
-        'expires_at' => now()->addMinutes(15),
-    ]);
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
-        ->postJson(route('telegram.webhook'), telegramUpdate('privatecode', ['username' => null]))
+        ->postJson(route('telegram.webhook'), telegramUpdate($code, ['username' => null]))
         ->assertNoContent();
 
     $account = SocialAccount::where('platform', Platform::Telegram)->first();
@@ -107,15 +94,10 @@ function telegramUpdate(string $code, array $chat = []): array
 
     SocialAccount::factory()->count(5)->create(['workspace_id' => $this->workspace->id]);
 
-    TelegramConnectRequest::create([
-        'workspace_id' => $this->workspace->id,
-        'user_id' => $this->user->id,
-        'code' => 'limitcode',
-        'expires_at' => now()->addMinutes(15),
-    ]);
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
-        ->postJson(route('telegram.webhook'), telegramUpdate('limitcode'))
+        ->postJson(route('telegram.webhook'), telegramUpdate($code))
         ->assertNoContent();
 
     expect($this->workspace->socialAccounts()->count())->toBe(5);
@@ -133,15 +115,10 @@ function telegramUpdate(string $code, array $chat = []): array
         'platform_user_id' => '-1001234567890',
     ]);
 
-    TelegramConnectRequest::create([
-        'workspace_id' => $this->workspace->id,
-        'user_id' => $this->user->id,
-        'code' => 'reconnectcode',
-        'expires_at' => now()->addMinutes(15),
-    ]);
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
-        ->postJson(route('telegram.webhook'), telegramUpdate('reconnectcode'))
+        ->postJson(route('telegram.webhook'), telegramUpdate($code))
         ->assertNoContent();
 
     expect($this->workspace->socialAccounts()->count())->toBe(5);
@@ -150,58 +127,56 @@ function telegramUpdate(string $code, array $chat = []): array
     )->toBe(1);
 });
 
-it('requires a code to check connection status', function () {
-    $this->actingAs($this->user)
-        ->getJson(route('app.social.telegram.status'))
-        ->assertStatus(422);
-});
-
 it('rejects the webhook without the secret token', function () {
-    $this->postJson(route('telegram.webhook'), telegramUpdate('whatever'))
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
+
+    $this->postJson(route('telegram.webhook'), telegramUpdate($code))
         ->assertForbidden();
 });
 
-it('ignores the webhook for an unknown or expired code', function () {
-    TelegramConnectRequest::create([
-        'workspace_id' => $this->workspace->id,
-        'user_id' => $this->user->id,
-        'code' => 'expiredcode',
-        'expires_at' => now()->subMinute(),
-    ]);
+it('ignores the webhook for a tampered or expired code', function () {
+    $expired = TelegramConnectCode::issue($this->workspace->id, now()->subMinute());
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
-        ->postJson(route('telegram.webhook'), telegramUpdate('expiredcode'))
+        ->postJson(route('telegram.webhook'), telegramUpdate($expired))
         ->assertNoContent();
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
-        ->postJson(route('telegram.webhook'), telegramUpdate('does-not-exist'))
+        ->postJson(route('telegram.webhook'), telegramUpdate('not-a-valid-code'))
         ->assertNoContent();
 
     expect(SocialAccount::where('platform', Platform::Telegram)->count())->toBe(0);
 });
 
-it('reports connection status while pending and once connected', function () {
-    $request = TelegramConnectRequest::create([
-        'workspace_id' => $this->workspace->id,
-        'user_id' => $this->user->id,
-        'code' => 'statuscode',
-        'expires_at' => now()->addMinutes(15),
-    ]);
+it('reports the session connection status while pending and once connected', function () {
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
+    $nonce = data_get(TelegramConnectCode::decode($code), 'nonce');
 
     $this->actingAs($this->user)
-        ->getJson(route('app.social.telegram.status', ['code' => 'statuscode']))
+        ->withSession(['telegram_connect_code' => $code])
+        ->getJson(route('app.social.telegram.status'))
         ->assertOk()
         ->assertJson(['status' => 'pending']);
 
-    $account = SocialAccount::factory()->telegram()->create(['workspace_id' => $this->workspace->id]);
-    $request->update(['social_account_id' => $account->id]);
+    SocialAccount::factory()->telegram()->create([
+        'workspace_id' => $this->workspace->id,
+        'meta' => ['chat_id' => '-1001234567890', 'username' => 'mychannel', 'type' => 'channel', 'connect_nonce' => $nonce],
+    ]);
 
     $this->actingAs($this->user)
-        ->getJson(route('app.social.telegram.status', ['code' => 'statuscode']))
+        ->withSession(['telegram_connect_code' => $code])
+        ->getJson(route('app.social.telegram.status'))
         ->assertOk()
         ->assertJson(['status' => 'connected']);
 });
 
+it('reports unknown status without a session code', function () {
+    $this->actingAs($this->user)
+        ->getJson(route('app.social.telegram.status'))
+        ->assertOk()
+        ->assertJson(['status' => 'unknown']);
+});
+
 it('verifies a connected telegram account via getChat', function () {
     config(['trypost.platforms.telegram.bot_token' => 'TESTTOKEN']);
 

From d729c34c0e787b13b80f5580a4206a62021fc20c Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 09:18:24 -0300
Subject: [PATCH 12/35] Harden Telegram connect: one-time code, drop session,
 decode validation; switch icon to png; widen add-social dialog

---
 .../Controllers/Auth/TelegramController.php   |  11 ++----
 .../Webhooks/TelegramWebhookController.php    |   6 +++
 app/Services/Social/TelegramConnectCode.php   |  11 ++++--
 public/images/accounts/telegram.png           | Bin 0 -> 15821 bytes
 public/images/accounts/telegram.svg           |  10 -----
 .../components/accounts/AddSocialDialog.vue   |   6 +--
 .../accounts/TelegramConnectDialog.vue        |   6 ++-
 resources/js/composables/usePlatformLogo.ts   |   8 +++-
 .../Feature/Social/TelegramConnectionTest.php |  37 +++++++++++++-----
 9 files changed, 58 insertions(+), 37 deletions(-)
 create mode 100644 public/images/accounts/telegram.png
 delete mode 100644 public/images/accounts/telegram.svg

diff --git a/app/Http/Controllers/Auth/TelegramController.php b/app/Http/Controllers/Auth/TelegramController.php
index e7fd8202..bf84f7e3 100644
--- a/app/Http/Controllers/Auth/TelegramController.php
+++ b/app/Http/Controllers/Auth/TelegramController.php
@@ -15,8 +15,6 @@ class TelegramController extends SocialController
 {
     protected SocialPlatform $platform = SocialPlatform::Telegram;
 
-    private const SESSION_KEY = 'telegram_connect_code';
-
     /**
      * Start a connection: issue a signed one-off code the user posts in their
      * channel (`/connect <code>`). The code carries the workspace, so the webhook
@@ -33,26 +31,23 @@ public function connect(Request $request): JsonResponse
         $this->ensureSocialAccountLimit($workspace);
 
         $expiresAt = now()->addMinutes(15);
-        $code = TelegramConnectCode::issue($workspace->id, $expiresAt);
-
-        $request->session()->put(self::SESSION_KEY, $code);
 
         return response()->json([
-            'code' => $code,
+            'code' => TelegramConnectCode::issue($workspace->id, $expiresAt),
             'bot_username' => config('trypost.platforms.telegram.bot_username'),
             'expires_at' => $expiresAt->toIso8601String(),
         ]);
     }
 
     /**
-     * Poll whether the channel issued in this session has been linked yet.
+     * Poll whether the channel for the given code has been linked yet.
      */
     public function status(Request $request): JsonResponse
     {
         $workspace = $request->user()->currentWorkspace;
         abort_if($workspace === null, SymfonyResponse::HTTP_CONFLICT, 'No active workspace.');
 
-        $payload = TelegramConnectCode::decode($request->session()->get(self::SESSION_KEY));
+        $payload = TelegramConnectCode::decode($request->query('code'));
 
         if ($payload === null) {
             return response()->json(['status' => TelegramConnectStatus::Unknown->value]);
diff --git a/app/Http/Controllers/Webhooks/TelegramWebhookController.php b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
index 4d673c45..6aa0e05f 100644
--- a/app/Http/Controllers/Webhooks/TelegramWebhookController.php
+++ b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
@@ -12,6 +12,7 @@
 use App\Services\Social\TelegramConnectCode;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
+use Illuminate\Support\Facades\Cache;
 use Laravel\Pennant\Feature;
 use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
 
@@ -59,6 +60,11 @@ public function handle(Request $request): Response
             return response()->noContent();
         }
 
+        // Consume the code once so a leaked code can't be replayed to link another chat.
+        if (! Cache::add("telegram:connect:{$payload['nonce']}", true, now()->addMinutes(15))) {
+            return response()->noContent();
+        }
+
         $workspace->socialAccounts()->updateOrCreate(
             [
                 'platform' => SocialPlatform::Telegram->value,
diff --git a/app/Services/Social/TelegramConnectCode.php b/app/Services/Social/TelegramConnectCode.php
index 97cb45f5..fe34e23b 100644
--- a/app/Services/Social/TelegramConnectCode.php
+++ b/app/Services/Social/TelegramConnectCode.php
@@ -28,11 +28,11 @@ public static function issue(string $workspaceId, CarbonInterface $expiresAt): s
 
     /**
      * Decode and validate a code, returning its payload or null when the code is
-     * missing, tampered with, or expired.
+     * missing, tampered with, malformed, or expired.
      *
      * @return array{workspace_id: string, nonce: string, expires_at: int}|null
      */
-    public static function decode(?string $code): ?array
+    public static function decode(mixed $code): ?array
     {
         if (! is_string($code) || $code === '') {
             return null;
@@ -44,7 +44,12 @@ public static function decode(?string $code): ?array
             return null;
         }
 
-        if (! is_array($payload) || now()->getTimestamp() > (int) data_get($payload, 'expires_at')) {
+        if (
+            ! is_array($payload)
+            || ! is_string(data_get($payload, 'workspace_id'))
+            || ! is_string(data_get($payload, 'nonce'))
+            || now()->getTimestamp() > (int) data_get($payload, 'expires_at')
+        ) {
             return null;
         }
 
diff --git a/public/images/accounts/telegram.png b/public/images/accounts/telegram.png
new file mode 100644
index 0000000000000000000000000000000000000000..80ebeb22c6912b13fba089ecc68eb82975a6dbbe
GIT binary patch
literal 15821
zcmeHucT`hN*KZPv(mNsugx(~a&_Sj5Dpf#QNCJcwNJ3LONE5{dQUoc26dO&XNfA_(
zq6pHP3aE%uR74QI69gZh=Y8+}-nH(%-~Gp|6;5W(p1o)G?AgElJ7<w})J&g&mYWs=
zfiM^v=vabRS@L%;HTaiLJ+T4;ktd*0T6W~CSD>#Oxf{G<(6at02n&Qc3IZvEC}#&y
zY<GZCCOcB5Kc#&CE``G2-LR^G1V7clKpaL@9xW$}Q37P8-4(I&((+iOinKD|rXsC`
zR!~-uLn$lDD<MIP(5fA!5<iuqi2q_5fg%#I1QHJKM+65z26qOCZVzz76aLKr^e^dB
zG$@hpf%@4KUFiPvmp6G$2rLFi!eV@hcz04Tih$Mh!1|GVHOcFM>){Akcc0Jz49){b
zLit$X0|{uXb*Mi!#LAOI@>i9SK?fml{v<R4Pw<fO!v+)4cnp>(vm;O3mM4MoGHAT7
zKb{C0I))>8S`$z>KP*Pm#{*9Qo4z=-DL4rfxUBM>Wr_c<m*t5fdLl3=5?LH_lDx1Y
zFKh_fCy+??O>_a4NJ0@vTmtSsSU(Sv=YIJJj33Gu>qpk?4);a*;oLzHG|I=ro#=^@
zRZzr`HQK>z#<z4XTghjudB2z+Tx+RtaC^DO#Ob^H(Z|qqLdE7Mv_A@CK(_hw1C!sG
zs_^zyWzjzWx&vq*6wVhEhwUX#v&0jFRwdy`K3Kdy)(=ZSfnJ9j`l39rIPiu$p5Tij
z;c(=(jK80U7tRk{h#wkjs1tH9#MfUH2ZocP3Q9>uK?N&~LMmXS<&}|0X*XGvg0#FW
z)?G;%E32%CmcwsbbpdygYywXRQT(}=M?LW*Jkb;HFC(jfP(c9j?ND_ghky(KcF4iW
zKcxvouqB5?0HlBDal!ey<D;9mor(X4N{=8cf$V<wpQ`cTZX>qUBisUUK9~?5SwL1E
zPyiGWz6e=GBodBB$|=ciZwGn{N5pyfp-6!QY{-5h*2i6Fd#8?U$L6nFUVnvuOaVHO
z;1eSDPuagDWVXldMElP68sS=-wn`>6fsp&c3tiuks;$p4Y4WxKc?{mvRZ9K0e=3#u
z@09+Ez8$rTA?HzXcz^b0BhfS8f_#PFPD<zXDOqmtAHDTvS#ierw>X190Op;T`5E4_
z=znv}f2|md8<{C`-1NoS(|;;}DhqQ7#Mo0G0b;0CfEY@FJPH^T24m(pvn6&zsPCSL
zu^C#4k2e=!pr(<GH;7+lfI{i0AV46J4xpi?u%V=8gV|Uig#ZC^gO-i^=N4Lp5=mHJ
zBHYjqjVJiyw}TSN3-FMI=-AkQ3Rx2Zi6pocmJozPV~I#X08YM5!M1-V3<!8kAo?!>
zxV{{~w~s+q9tj{7fbEY1*i;}lW#tsW0CoVP%aLpV%eESN+MjB)Wshni#R1W6)Aan>
zcs~-DiQt-nBv0^)L*q!H;52b09C%EEu)D))cZY*3Kp<HFCi3t-^n0yPesCi^@t53Q
zdRlFi4-PzLemK<MeF6vge))_B%E^L8;iU2YL=6-<2O_{&24bLszxx$R1)+$6GC{z8
zT38Ge3VFcX8vQK%2;m))xHuc@>ZWN+zw!kqwvf<2d^pyu`i)3@4*nH?z8t45r^^0u
zR*U+$=v(a<Tsh++;9ZhZf}0O2?pZvca@o4<@M&D~^{s;%3IvfdWR5^ej_1Qu-kY9{
zj$7HO7p#sP2uOMVV7`yy(D_b*>%}yU+@6~TT8=VHiTtXUzSPK$jS6<3DM909Q^U*s
zw97&ueR4TwB{4?n(NOkd6<trS_oS&wdDE5cE75N?L|!9>VMjJ;&-d&Xq_p$5WbHK`
zRb2zF_nKQ{I*<82Z%(u<9M|qRs{B5|M4EGt+-TIirEU5N319IOh$pW4^^z<1(eclZ
zTON5IpaP?SLZF2)&=k-ki2yyg1-xuf=oTdmfB=l-78AKeNdemv1^OCni%{+ZICh*a
z1BKF4@0Fs4Qc>-ppai1Nk_F(D(eXfZED#;_OA1B-5P^VQNf->k(xdJ1fp8GB;C^@#
z+#gHu#gWKKm4t@}60vZSCyod=0YlagY-p3g(;bHfvo0Kj3#>m0jw1dx#w`?-$HIMf
z#8DmuEEYr!5(01{&xfDV7O(~^^N!}3#hdJ4pT9Rw8cpy)5JP=YV33j{MFx#>Q9>!8
z<xl`xNe+ork_Qw~7z|QH4k_z~M!KP8<=kaVz&Q{}+Lk5=a5SK_yCNu*QVNg&#CF>N
zG@j=-OL#QV|94XWKY3n4lw1I36#FrW6SAgVn{O1%TKI*DJw&VWNw41{7R&?`F)%2k
ztnLJRwHmQ+2=_xUR(OiF%J@rYanjq16NyF~^POXCC(q;dGda%rIx0B_uHB{Nmb@L6
z1TP|u*)f-0TH|g)G}Uu?icrDjs}?_un5Yfad6;<#LHrZOqy}{F=^Z#RQn~+n1ik1!
z>%Q|v*FKEtoN5Sfr4?lEq%+);GL3*WES!An*d8oX)uZu7*DKfH4dZ71U3(tS&1K0+
zO;}|4cg~kp!e_MXlJhBVd5TK1DpY=;u|#<_^#|P69z0$cns)D^XD@B%$}Qnp&LWqZ
z@i)UF{aTERn(YUimZJp+GHbgQu4-}RU+MIA48J^xcg&+{9Hl5!LomGWTT%D!YM|8G
zcseLFYL=_EReI5c>PCLvLYAIucHm~kYOhP+3SfV=EBY1ci;#Eb6Dju(Q=4DzN<|Ks
zcQE-lrC%8~dT&u8MBO{X7D_lQSQU!p-`w}4uM(qSG&C1OztwW+N^8rE$X(?htYu@|
zEvI8fGOG4Q(y9kmuFU{5@VS!*#Ac1CvxzompOw5Ct7*2$?EPZV=paJ9=5<ra>KvTf
zokKf4kVGwAq9$aO<#F_wu$+&m$XG1qp*(w>+F50o{@mxT4z3%~Gsfk>1OvZOk(Z};
zTuIuC+4V8IrO9xnAK#a#eU{#gXlSt+UFeF~m-5B9MfT;Hi<C*iA<*MYhZ`f80ve?3
zsf$4T$OrKwX$L>(OYT~qOq%VZP73Tkot^aRA5jDN{5@Cx-@uRkz&<c^LHuC;nfNX7
z;OW)YgzL+aVFL-)2eK-^U_%}WHkEf_<Np(y#lZeG|HH`n9|q=s@L1LIBbu6MsvHe`
zHtAz;`9R-Wgos>=QcJpCQJIJt`I;0Iy|%`?lC}|&aVFzz@0*VYY}6Qt4#7PYtR);F
zSd;YSJ^Mek^R`7lT%vFqwsPbH@tFUzc^`K~=ljotiw_9Cp9@wmpJUL@{PL~M>vk%o
zUEj>*2}Pe*Tfz~tE%GS^CH7@~Is&@v+}0daS7ESa#}5^%fzMRva#GpQ@4TyBw4j5L
ziTqBs{?|EKuwAdzgc3@OpW?NG1H`R;-*$93UulhGeoQek@cL1#wXdA!;I|{++D|Ak
zn#AW~HW@~$pCc)_eCr|i%}KFF>~SLNie+yLbTt=TNGO%InkuWLXf>aa-T)p%WCI7z
zAI2@^RzRQja`J%ba$s+ksj1=d=4>7pudHuopOgH!`xi8n%GkNSMlfFW=Ha*bV$Rec
zt#oZMFKXu8RNOR+nxMo+cG&8Pl4jfX*-DJp9*$Vuva|e06q&OqnK(Lmf(zF49t-9u
zI9-wnnwwqKtx!2sR$BVi{aUX}U!BcRd%|~_+l{)!teU_qHN#tkSM39GJt3QY{S$^}
z(OOmAB11>wYPp#mUC+O6YYtFgnNx@iXUZqVRu!BP<BV8GKjaO@9opj8WNVhlN=UiN
znC6r)NIMf3qgMJ+^*AEssO+f}8poN~rgZBeLr&{E(|H@=J-OY}yZ9#$;vWF8k`wbb
z{_O>*LEr-e1W@=1A_(9hAekqgCmJujOQ1ji`BiAhZ2uyF=fOjE8yx-yo=|FlovcQL
zk^!Lm1&h!<z%g<!obo7O2AKTn2jNm3II;^SFeoRIY>^0Zw&394-%R@Ah-euQ%4Gb(
zGR}n<gvPp{{fP)qlCKXSOjgW73D$$xz(b4V0NB6|@Zi#0*_&!h%L6Kk(sFVDFIkF_
zl9Te^!_e<IReWID*IL-5B-Mb>>{psH@a6-u{~sA=8>a$#X7;2Mk4cX`o;rkehFpkF
zn@@ua-@b}dcIpgUx;Ii}3c(%{Y2|Xvy>DMT#zTF`K33$rT!Y}UIle)_(U$W|U1u!E
z`lT9$seB}1|CNI;6+%BI#<2#WAFN>7ttG@lX?0oD7?>z43VWB&Z>aL~^T)rcda-x<
ztZs_4TP^A3F~M1mfX3?w8j}tIYE4+BJK-1m<Q6z{JCq{z+=K7A`f^)$dhqe+CvaZ2
z7Qa2r;i;dZpf&o0mzEf|lC7W9cKN=bw3ME;WonDykglYij&tYxFP1;TY^NGODY<{Q
z);ddAc2^=yUuUtn9K_X)&uI&j_M3kB&JCNTH0e`UBgfjoZP7H7S2by~@jx|0@#*O5
zM-8W^8wls7>YCX@RyQkBS6gDbj~azo-?d^3lgtj?i0f=i%P5c%)iSR9#%36k))+y>
zp28oTR#-CC^iko*axDjivWAesh4VK)*u9pKDXo@CdMZ*Du->CrVY7kG+moUF&CfON
z^4_Aic}#2icZBWk%+}pG=A~ocFW@$7=xy4%JWR?NKPPsmliPiQy6F8i7c)JH4!MB#
z8@DCuxP?`b`lAaDcWM(yo&^u!+ofMPk5=Ucy|4Eui*At&{c`H-#~V3}%%AP|b<Zck
zs{D*r9>+t_wnK1!6Z!l2nG9jBM46#MR4(1VDL2d2@rD9-kOx^4N%=Sukz|ec21~f;
zd~^`X$DUCYh+$L&K=K2oUq<PjaA$z-f#t<8@_}94Fen9*i5yg}@di*V1tknD*MaC5
zYPua-M8gcF%p+0;0C*S_`co?YhtD1;fc(cGN_aX2YuBk^B@Us&&mo@t`fTGo?FT&v
zc@T*~Kxy+>RXL2AR?+!!pBT3DOIF?(lhHv07ZXTz6#%3x04O8nWR)FYG?2H0W8Q*(
zUF>-=bS*#(6)gxG%e&}HC-dk;NN@cD*4DZ;OPJyxX8}O}9ev3~Gk5@L*%)=eCo<%c
z_8^(LA&`dvm7gb5cJ~H+o3w$&u)aLp(n^zjR^e6#n&9&exHZlfYeho&`s4gOK-}Ho
zYUC;Jay2<cKo+U83%bYuK8YQUMa#B#*A`L*tYWtl1E8y|4VrNIX~~6b34Ds->+fQT
zCHmw2Fj#`iHs-sSncKQ-KNPSBbIKlYXL^pnpwxS}e^5a8P-sCYpKb7+`WBs0EO}0&
z(JZ2rJ@d`1AxCB}drU3G;gQGbKST$;RiyO=IJ03KRiBtdm2EyF_>bn)!Z86A8=Z2U
z&LAH-4d&y7e_<eh=O>)x>?K0xC-eaAZn~t{yUlUIqzdLeU@tYbM>IVYq%&aJB}diI
zc=<iC)pHK}nx2v&N(5!e1g3bwQ*$5Ve@l!Xo*%%6&E=WCL8>P}_V(ZG4_9me9LSdW
zDXjntz&y`1&p6)jFHDd_V89(lgFC!UD|S7-v#I*>J6rnG&%bY|w&pf)M4#JT3P>xq
zc@&t;cSsgUEVy<oZIg=MEdh4Fq+q{@4jM(C2=V`DN~C{;_I8>t_|OVp4waEEKP^-X
zN%hr^AyVGr70rEibGk>m0#6X3c5?sWv1sa4H(QA>5cKHG@N$2gRXtH>d561*RY1`y
z$<CL9ZMB>E2jh9nH<J)`Q<8v`{*S3I>9Bg=V<Tt-neH|gjUR0-DetMyQLY?Q(TGK>
z^(qjSjg>8PesrvNz4g@kzLNNCc`%K^{PIVOeRm@yAqsRX3bDmD{=Bi6Cm-HPyQ;_W
zFK$G8tzRJt=v+iF<x(puXI^<RhYI_?FJzs1A<NdTya^fwd-8I$@_jrLrou16vpH{d
zjZn%>f77k+X-ur<jfKPfsgj+1{tFfhFFWy!{ggJ?Z|)Cq`pS>;KUr6q%4F!D6`YTJ
zrrf))ZupaZ*`-S#H9jtkvN*5ZzgOAijO;Mxf8F=gfVlq|KgH=OMhm@}Jp*A1501nn
zdOtoeDDGA#8KL*xtS!l^Zh^7Th`l)Y^(d6JdfbJ|Q(!{Qc$H&=(fg3)otZ+jEd@5(
zeqrAS@Rg2-4h5pPq(nYe8Qy$_oPFkYqSad5OZO%D)X(BxZ@dp)_O_|=$uo|l5;i!@
zyJ;&pl4tLhdC59tV^QMtvRUnk*rsCJ=OJo$N1LTFB_g5~=ejscSI6W@O6_uGCa-P>
zeGD5*oHY;CyV>pZa8e;^>1%OV3~+1e`GPSsuW&ig-Rye0WSIlxBDX*;lD?A-_b4jW
z3R{N_>EHMv?k?$k{2w6$xcxm5?UW<5Z1lUwgPaVJJM@B%jhS5N{2ts$fo;+Z7BF1D
zM(n1^Z4#m{znu(a0XbQ@zmlO6*p%H(hW{fO`M={E591Z64Xav@5DYDB9*I!2FP~Q`
zy=;;HvM=^|u1SG!-kq-4HHWV(`8ph0F4q!QJimvpTuGvf%;C>vlH)(hMkh*4_x*OP
z1Qz~7yE<-!Wr<i(^-(G+E?JOka(?7U`@YEX{ZeXLV;*PUTO3(@Y1=<1E<OLEq9$;T
zpBj7SlEjPQ54g$Ua|wEolcPGCNn>GN$4)FNg<f^K@$_vRrrL5jNPiU-yMNrJ+L}(l
z(@#mDLF0x?<%Cgq&leR|k57z6XrDL59lYI&42}b{JSD9dlE(EGLPxzBe?^U*Y3Sx)
zD)HitgDS6z3|=nYL9&$|lSmgsd`T!yH4Eaf5%tdyjm+cLhikvqMn|0t^b->~m!Yc6
zQuXy~?(CuCAEGA&*@t5!A6;n9n|Q5OK>R+(@8EN3*)okq%8sNVUQX2RnKa5j;H}&t
zvGSxWov7t`^{!r3j%wim#Z>cR!Qm%bV_XK2?DD;RCgq>9k8CpD!$^J)6c^T9&}yc-
z;%;bp^s~i^qM_+&c;CTe3ZYUZE4r?YLTBt&$50a&H&t5JDuE)C!FL%(c4{vu5;v<-
zUpN~Fv07a0Orbw?JXx@$RdnwfJ2NXqxQkE&<~4e%cv|gi8>v#Ak0$6txszVtE7w9h
z8mKsgG0ys9&pW5b&H!tZUT)2cpt?Rr?@anWx$5qUUB2N2;+y@y<r{z1<o_0#euu6P
zgRf)y0-P`=lL!y>x%!M-2bj$Nj+xN-?ZO`<9)E|(;9aZ$F~%Ff{f7vnxjPDg#VhP0
z-hY5F<P)kd5270h(Ef>>hXGYUIZrW9K3;ZL55ebukDR}h`1}U||My4f+lUozf41e~
zU3^BVjvzF`{pFB=*7O}N1hXkyFJRTv%(edLsM9NBiFN;EhB67<2ClW2ch5UD*T+M2
zGmggxeG|UN!A0be9^H3Y)A8*`P270t_r{cPHkI1;auClz1x0$&aO(QO>jV<};8wYL
z^1&13r@FOW7F_R^nV)yhJ(xR{d}HQEN+U)z!RJC#PS`Vl+OSV0je+L%4y&cil}_)r
z#I2JS2a*GVup?cIghHY3En+b`w=%_e%7ytvTWcpI=fCDwgl0w;+QygD>UK`HpUIoc
zSYI#BA>3|%)Y|G5F#M1$il+VU)$W7@;Rf?U!@6Mi^Gk#)?~GxV*OekJTHQFryVsEE
zQn$*9@huT_rr5zF>fYCv+#hImo8Q&Q77);QR?8;bJ;ocN`X=}0jC{a_K~e8F%Ea<w
zsCkq6p^%#<H`m+KPA<^8$f+b~hMZ7-cV&89=m)R(i$`m3moi+|rG_Gw^>P9a@`)W3
z9mR8;<lBE*@!rM$+2wti_D}p5m6|gklW<ORv2|Au&V2X!ahn!ZiTFDic~T2$nzgC}
z92v-JHyS3|rs!d|&E{**SB?!gQhtw_ke#GVT7+~vwXHo9iiFU;34)0ZFJgnViX{?g
z^rdDaxv!mK+Q>-%YGW<MAN9RunNe!y<$9@%4u{bk8zb+ik}`L`)YpZVVH?O8XdQUy
zYC!4$1pkke=P+jae?t;}<2HHG&jIdVJcxz@$?!L-104A49u<;_{37NzdICuOCJduT
z9ssxj@QE@d`zjmE8pCs?r_Vy#t)uy>L|n?oH$dhuRg_3UO8AA~9%g+B?F(!|BCwYH
zrTAwE%8$r_ioEl>)hz;NeB41=@E7ZX$&laf0Kxz`u<nGYCok8#x-hibHv<)nP2lD9
zk)zr=2UAnJXT+u;rQ}L{n+t&N3@8l%J(vJwJ;Kzc62Iz;h-#pJks(<=_fCwqUh(u-
zq0BzV{)dOfL6L?>KT=-I3JD6Re5t+I<(&+<I?}D4)7xeuWk8V^uYH{S3fG=37JRez
z=kvz{e?0KV1Ajd5#{+*n@W%sxJn+W@e?0KV1Ajd5#{+*n@W%sxJn+W@e?0L2&I4cV
zp%8iorKuBHLSgsMAO=mY<{El=)i7tZm<$g_xo<V3p0Co!eUJ1$x^VqbWI<~G+cwxS
zB*(Gpnd{$NEv<6n<HZvX-7KbPUiTQ7;dxj%$Ej4Nd4hq8R_2PN-+s8Qu7*<Y>&ojK
zaN?~V2Pe9>3{qCt<r1k<d1O?7$fj`X5H`gg^lND__!q1`Gj>>Sr8ndI7|j*+@zwbA
z7#AdWa<wPApzHF3WDV1S=Owt(@1(NRYsqGny<0j%Y#nZ<y%qs??N^S=TLo2xXOOrQ
z-|`Qse$Bfk6FQUOw||-tDT0gSo{gz*yKP8wH_hh$T5(b1)u&5*iM@BLquaBpZ)~iw
zWzC%n2x$a8Oyh505B^IJ9UJ)zg=Agf0{ftbI-1s=(M?&CcwT*uN9rEIpT2x)3cBKQ
zCg4NAh;P4EKC6X|aI%h(O_7!nRV1u&DehdzYnLgRDQLSfzXOec0DEbEDdl0EaB(lq
zjiYPR$^kL2+e;(I=DjByh#^Bc<C()w>-7aD)jc1&GF9eIMs%k(Ex#HKw$X)9J=yZ9
zxUJ>HQr&kQ9#f+3uu{)%ZP_D(ZBTYIm?$ZWX0}Y0dX{Nq;IAoviFWVPmiea>)^f}P
z_x)w*Og0b|fztX^Fm{rP=D~9%WrHEYiH_79$CnPZi<L9hY}~NbJ#wOy$C^d!$Z4qX
zEg;%tpspQiA*Tl!h*6yn^fW#up&$RUe8A&o!|`mIvMlIxYHwxcMaKz-12$Jh-+Zw3
z{?>2$?yI5pRfU|{cmv6c3D1w;(=vT-RODJxGbSb@&?2d+Sdj=bx&W2zloNn`<nTwF
zHu3O#T=tDi<jxpss#>s~eM9zk+Lc25mQIeS_rr6KUmv$PPu-1z`JZ_|`_h3O8+>lu
zh@WV6!j|6X)z?$;B?eZBR%ycYwyQ__T@8o2j#A`@19j|c4O8ujZ?bM!+4?doh2WKK
z->V*O_Rcl)G+GHVsml{llyssR=A@}{HvAkYbyC-1{&qsW6(`-tHi`RU100=L>v;!7
zJBod03+g+rX%0PjqLV4rbv7A!|FCZAB@SJr-Dv~3<^8v&;<H=TCEWz;i)ZPsr!<TS
z>Ou^eFFn~}NRp(t!rlO0uv!+j3#yfAiPzd1UAc5tT=#O#Gmj+gXp6EB*NtwAG|Ep-
zXB#^?XI-70iyVFR(5qSaQkayLA$_PT2I*FT8`{debiOkVuiI87HtJ~qe(C)wgp2AC
zn`e%1Yc}Y;E~dXeh&n8yd-z_3yWH^gG3O9n0h=LnIUbpw>U)*_uWO3<WOC=9osE5w
z()MtIOJtJ5D7>CHqhOR?v+={0W__{y&G}{GIc`1b9+KOwgF&I;q4AgZ)nB=iOsiUG
z^rpQv+QK$iuf!cuC|FlZIs7QpMp!*{D1Om#St9BH*9_dI{$}FsD><|8m+5aiy$y&E
zUHYtgpy)<q<)gMz#KN@?!{%veH)H#9Oaj^1(|ve89n8v9uRq=QJVq*Wo?bs*nHAAf
z^X;KqsuH4Sd8{-jJskG^%cGNHCl62cwb6_izWMSgg}(fdko%~`M>Pjbp6VkOjWO3?
zq@5Mttb^V(+~%QP<|mQH`k~h&9rpL{1KlL4GTy2~2dXM7v?G;gPaBJ6=J?ro`i=9u
z($)q!l{s@YOo%vCHCGn*Yh;V3*z7->W+v#UHaHE=fAWM^{F-0iUR8xBBkorlQmNa|
zFV4(Zkw(9KR<d2Mer>Ye5l|p7MTg>GW%Dr(E3l+1ZF9wh5bkzJ?K|Pv5EAorPPKpj
z{=w{q^|6VeqGt8tQNN|JS4n!zkY<<p7iVQBG6l+R*^k?6TPoT}moPqlk(0sir1qfp
zs#@ziv#_{t_P}K5(A;znGuqX?tYaUd3z;UL>NLvxf`7le!+D|8wu;RWP8Nlm&c>4W
zGf?JdmIu~w_g6Pcg`iwEd_D|yD|dRu6%tz<Ydfk=6RTf6SXfOs8D2aVD56dgYX7u}
zs^aj>x#R55mn{W3@72{mU7d7#{obmovGLiAk5cJ9H_%^`JcoRk^g2fT%LZrr+71Me
zNVJWCks1ft_YpQHms12@@xQPhf0|%ay`Hjqh7gXuJTKL7WnQ$=|L%kNr&VDKVV8Tq
zxP4UP_TO5HvQATGO|i($m|yJLplQ2eaqR2ECkqP}=!dnL*2%%gmbCT<Dhx}TG>;#i
zi<FgbJbCgmPi=4}?$O4#Q}&2JA?8F~E*|VV(q*yU9urEKD;k(p{}IrQcu=8pwx#LO
zofy5WIUoFklC137O+!I!y~t-)ROFTAS@rKGwNK_xdCYp)N4OD~A*<^`eDr#1GWzK^
zL@rB(MTrYpdPLd2<>t@hpb1{Jv|X2glp+s*{KR`QcxCfDUnx!KrI>jECNEjINWNSv
z62kE4NkX;|Bn7z<FauTEs(#`g8R-W9bo1kEwDZ=R$S0AR8^eWJH$93@-LPMX?EW~T
zmb|?AfI_G8b9Orm)7|eIUkf=lLnAM~FFIZ`R<8u7)AVqDv`jnmvIDA@OS#eRJmnw$
z`K>;?S_rAd^~NdP*UD~^mJv(Ss*_C-326%!LWxW-SGlseBhEUudPnP8v{N@2PcddP
z>*wDLei?7lk-0g_GB(0K;dna4qoy}FqNYtoeM0c&aMI?i%P47OVC)eKbwre4ZI)(I
z%NeHb?%)vrfg?Fw5#b)G25ElupL|=6dnf003AcUS%-|nue8hyGC{$PEJ2yE#Uc_Ou
zR)6%y)wCW*Rr4UNYT66Se)ISC@2RX-<C4JN{!l@L3=XE1mNfRB)_vQ)_;RxL+qWe(
z_0XBay;tA)pFG)K7+w0Kh3$l0ynd@amo(SfhWS>R?FB;R4OU(cfyYlDV_FB*FvkPW
zNfND)gSojgGO6(!YpC!bIR%Z!rvg9KRN@oOEcTe7deG@FDcybb?-0)|SEVW%y5+MC
zN||)1WbC>8*zZ88>ur-NTb5*E0}Q=-tGuE_-(vcBzBtVVVZmg04b1pR_<4iu!`Bke
zt0Ja#&J@j-6&HW3>h$`0&l%ZhS(hxyc)E4$g8HV#!o6JfiTY>4AqK~>*C_Y>sHq&1
zYm_^AR+t6H=h4Zt#0zzdy{!6LsndD-xJ69Wdx;qjs!#PIj>0*Pb6JfNL0(NYdP5JA
z8D@o6irv(u`m0u}3(Zbb%l9oJy)1Fr4^8t#1{Ez-p76iBd!YVZ`MV48L7x&|z<mN>
z*2(;A)*+{)ia6D$_o`P87&|<)lQ3N4-t;Mknrt3}Jv9Q_yA95q=$91|W0MYhb#5s6
zUR#6ZTb<f((=ri`pK8=UFOB%KMZK0<yB^ohR(an0=<RElrk)(U<l0x)bl2;CHJsMZ
z^44;a<)(5`ke(8}L#ZbFc{|D?prW|rq4YE?QL+AH#?|FsTE!sweMOWUk`Kp4*y-#n
zmheyKS>tM*2rxBA^$(smQ>rDO#5@pXDvaNPZ57nM!nxNglWR~zT{E3qTCOqw1=NEl
AD*ylh

literal 0
HcmV?d00001

diff --git a/public/images/accounts/telegram.svg b/public/images/accounts/telegram.svg
deleted file mode 100644
index 8e5fccef..00000000
--- a/public/images/accounts/telegram.svg
+++ /dev/null
@@ -1,10 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 240 240" fill="none">
-    <defs>
-        <linearGradient id="tg" x1="120" y1="0" x2="120" y2="240" gradientUnits="userSpaceOnUse">
-            <stop stop-color="#2AABEE" />
-            <stop offset="1" stop-color="#229ED9" />
-        </linearGradient>
-    </defs>
-    <circle cx="120" cy="120" r="120" fill="url(#tg)" />
-    <path fill="#fff" d="M54 118.7c35-15.2 58.3-25.3 70-30.2 33.3-13.9 40.2-16.3 44.7-16.4 1 0 3.2.2 4.7 1.4.8.7 1.2 1.6 1.4 2.6.2 1 .4 3.2.2 4.9-1.8 19-9.7 65.1-13.7 86.4-1.7 9-5 12.1-8.2 12.4-7 .6-12.3-4.6-19-9-10.6-7-16.6-11.3-26.9-18.1-11.9-7.8-4.2-12.1 2.6-19.1 1.8-1.8 32.5-29.8 33.1-32.3.1-.3.1-1.5-.6-2.1-.7-.6-1.7-.4-2.5-.2-1.1.2-17.9 11.4-50.6 33.4-4.8 3.3-9.1 4.9-13 4.8-4.3-.1-12.5-2.4-18.6-4.4-7.5-2.4-13.5-3.7-13-7.9.3-2.2 3.3-4.4 9.1-6.6z" />
-</svg>
diff --git a/resources/js/components/accounts/AddSocialDialog.vue b/resources/js/components/accounts/AddSocialDialog.vue
index bb754109..06a57081 100644
--- a/resources/js/components/accounts/AddSocialDialog.vue
+++ b/resources/js/components/accounts/AddSocialDialog.vue
@@ -101,7 +101,7 @@ const platformTheme: Record<
     telegram: {
         bg: 'bg-sky-200',
         rotate: '-rotate-2',
-        image: '/images/accounts/telegram.svg',
+        image: '/images/accounts/telegram.png',
     },
 };
 
@@ -130,7 +130,7 @@ const connectPlatform = (platformValue: string) => {
 <template>
     <div>
         <Dialog v-model:open="open">
-            <DialogContent class="sm:max-w-3xl">
+            <DialogContent class="sm:max-w-5xl">
                 <DialogHeader>
                     <DialogTitle>{{
                         $t('accounts.add_social_title')
@@ -140,7 +140,7 @@ const connectPlatform = (platformValue: string) => {
                     </DialogDescription>
                 </DialogHeader>
                 <div
-                    class="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4"
+                    class="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-5"
                 >
                     <div
                         v-for="platform in platforms"
diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index 57c701e3..33b12f2b 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -57,7 +57,9 @@ const poll = async () => {
     if (phase.value !== 'ready') return;
 
     try {
-        const response = await httpStatus.get(telegramStatus.url());
+        const response = await httpStatus.get(
+            telegramStatus.url({ query: { code: code.value } }),
+        );
 
         if (response?.status === 'connected') {
             phase.value = 'connected';
@@ -123,7 +125,7 @@ onUnmounted(stopPolling);
             <DialogHeader>
                 <div class="flex items-center gap-3">
                     <img
-                        src="/images/accounts/telegram.svg"
+                        src="/images/accounts/telegram.png"
                         alt="Telegram"
                         class="size-10"
                     />
diff --git a/resources/js/composables/usePlatformLogo.ts b/resources/js/composables/usePlatformLogo.ts
index 317278f0..8b282b32 100644
--- a/resources/js/composables/usePlatformLogo.ts
+++ b/resources/js/composables/usePlatformLogo.ts
@@ -11,7 +11,7 @@ const PLATFORM_LOGOS: Record<string, string> = {
     bluesky: '/images/accounts/bluesky.png',
     pinterest: '/images/accounts/pinterest.png',
     mastodon: '/images/accounts/mastodon.png',
-    telegram: '/images/accounts/telegram.svg',
+    telegram: '/images/accounts/telegram.png',
 };
 
 const PLATFORM_LABELS: Record<string, string> = {
@@ -32,7 +32,11 @@ const PLATFORM_LABELS: Record<string, string> = {
 
 const PLATFORM_CONTENT_TYPES: Record<string, string[]> = {
     instagram: ['instagram_feed', 'instagram_reel', 'instagram_story'],
-    'instagram-facebook': ['instagram_feed', 'instagram_reel', 'instagram_story'],
+    'instagram-facebook': [
+        'instagram_feed',
+        'instagram_reel',
+        'instagram_story',
+    ],
     linkedin: ['linkedin_post', 'linkedin_carousel'],
     'linkedin-page': ['linkedin_page_post', 'linkedin_page_carousel'],
     facebook: ['facebook_post', 'facebook_reel', 'facebook_story'],
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index 4bd19bb2..d39f9094 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -43,12 +43,11 @@ function telegramUpdate(string $code, array $chat = []): array
     ];
 }
 
-it('issues a signed connect code and stores it in the session', function () {
+it('issues a signed connect code carrying the workspace', function () {
     $response = $this->actingAs($this->user)
         ->postJson(route('app.social.telegram.connect'))
         ->assertOk()
-        ->assertJsonStructure(['code', 'bot_username', 'expires_at'])
-        ->assertSessionHas('telegram_connect_code');
+        ->assertJsonStructure(['code', 'bot_username', 'expires_at']);
 
     expect($response->json('bot_username'))->toBe('TryPostBot');
     expect(data_get(TelegramConnectCode::decode($response->json('code')), 'workspace_id'))
@@ -127,6 +126,23 @@ function telegramUpdate(string $code, array $chat = []): array
     )->toBe(1);
 });
 
+it('consumes the code once so it cannot be replayed for another chat', function () {
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate($code, ['id' => -1001111111111]))
+        ->assertNoContent();
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate($code, ['id' => -1002222222222]))
+        ->assertNoContent();
+
+    expect(SocialAccount::where('platform', Platform::Telegram)->count())->toBe(1);
+    expect(
+        SocialAccount::where('platform', Platform::Telegram)->where('platform_user_id', '-1001111111111')->exists()
+    )->toBeTrue();
+});
+
 it('rejects the webhook without the secret token', function () {
     $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 
@@ -148,13 +164,12 @@ function telegramUpdate(string $code, array $chat = []): array
     expect(SocialAccount::where('platform', Platform::Telegram)->count())->toBe(0);
 });
 
-it('reports the session connection status while pending and once connected', function () {
+it('reports the connection status for a code while pending and once connected', function () {
     $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
     $nonce = data_get(TelegramConnectCode::decode($code), 'nonce');
 
     $this->actingAs($this->user)
-        ->withSession(['telegram_connect_code' => $code])
-        ->getJson(route('app.social.telegram.status'))
+        ->getJson(route('app.social.telegram.status', ['code' => $code]))
         ->assertOk()
         ->assertJson(['status' => 'pending']);
 
@@ -164,17 +179,21 @@ function telegramUpdate(string $code, array $chat = []): array
     ]);
 
     $this->actingAs($this->user)
-        ->withSession(['telegram_connect_code' => $code])
-        ->getJson(route('app.social.telegram.status'))
+        ->getJson(route('app.social.telegram.status', ['code' => $code]))
         ->assertOk()
         ->assertJson(['status' => 'connected']);
 });
 
-it('reports unknown status without a session code', function () {
+it('reports unknown status without a valid code', function () {
     $this->actingAs($this->user)
         ->getJson(route('app.social.telegram.status'))
         ->assertOk()
         ->assertJson(['status' => 'unknown']);
+
+    $this->actingAs($this->user)
+        ->getJson(route('app.social.telegram.status', ['code' => 'tampered']))
+        ->assertOk()
+        ->assertJson(['status' => 'unknown']);
 });
 
 it('verifies a connected telegram account via getChat', function () {

From cc61adbac2634988aae67c20ed69b1baa97d163b Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 09:23:46 -0300
Subject: [PATCH 13/35] Move webhook routes into dedicated routes/webhook.php

---
 routes/web.php     | 6 +-----
 routes/webhook.php | 8 ++++++++
 2 files changed, 9 insertions(+), 5 deletions(-)
 create mode 100644 routes/webhook.php

diff --git a/routes/web.php b/routes/web.php
index 77575c38..81265863 100644
--- a/routes/web.php
+++ b/routes/web.php
@@ -2,10 +2,6 @@
 
 declare(strict_types=1);
 
-use App\Http\Controllers\Webhooks\TelegramWebhookController;
-use Illuminate\Support\Facades\Route;
-
-Route::post('telegram/webhook', [TelegramWebhookController::class, 'handle'])->name('telegram.webhook');
-
+require __DIR__.'/webhook.php';
 require __DIR__.'/auth.php';
 require __DIR__.'/app.php';
diff --git a/routes/webhook.php b/routes/webhook.php
new file mode 100644
index 00000000..ecd2fee8
--- /dev/null
+++ b/routes/webhook.php
@@ -0,0 +1,8 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Http\Controllers\Webhooks\TelegramWebhookController;
+use Illuminate\Support\Facades\Route;
+
+Route::post('telegram/webhook', [TelegramWebhookController::class, 'handle'])->name('telegram.webhook');

From e72bf51c38fb08bdabae8698e6b601129f0c73f6 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 09:31:00 -0300
Subject: [PATCH 14/35] Make webhook host configurable via WEBHOOK_URL
 (sendkit-style domain group)

---
 .env.example               |  4 ++++
 config/app.php             | 15 ++++++++++++++-
 docker/.env.docker.example |  4 ++++
 routes/webhook.php         |  6 +++++-
 4 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/.env.example b/.env.example
index dd9e2b17..dc13c3bb 100644
--- a/.env.example
+++ b/.env.example
@@ -4,6 +4,10 @@ APP_KEY=
 APP_DEBUG=true
 APP_URL=http://localhost
 
+# Public base URL inbound webhooks (e.g. Telegram) are registered on.
+# Defaults to APP_URL; set a tunnel URL (e.g. ngrok) for local development.
+WEBHOOK_URL=
+
 # Self-hosted mode (skips payment requirements)
 SELF_HOSTED=true
 
diff --git a/config/app.php b/config/app.php
index 997df9a8..e8080f34 100644
--- a/config/app.php
+++ b/config/app.php
@@ -54,7 +54,20 @@
     |
     */
 
-    'url' => env('APP_URL', 'https://trypost.it'),
+    'url' => env('APP_URL', 'https://app.trypost.it'),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Webhook URL
+    |--------------------------------------------------------------------------
+    |
+    | Public base URL that inbound provider webhooks (e.g. Telegram) are
+    | registered on. Defaults to the app URL; override it (for example with a
+    | tunnel like ngrok) when the app URL isn't reachable from the internet.
+    |
+    */
+
+    'webhook_url' => env('WEBHOOK_URL', env('APP_URL', 'https://app.trypost.it')),
 
     /*
     |--------------------------------------------------------------------------
diff --git a/docker/.env.docker.example b/docker/.env.docker.example
index 706b63df..0c31fd1a 100644
--- a/docker/.env.docker.example
+++ b/docker/.env.docker.example
@@ -4,6 +4,10 @@ APP_KEY=
 APP_DEBUG=true
 APP_URL=http://localhost:8000
 
+# Public base URL inbound webhooks (e.g. Telegram) are registered on.
+# Defaults to APP_URL; set a tunnel URL (e.g. ngrok) for local development.
+WEBHOOK_URL=
+
 # Self-hosted mode (skips payment requirements)
 SELF_HOSTED=true
 
diff --git a/routes/webhook.php b/routes/webhook.php
index ecd2fee8..0f0c5d2b 100644
--- a/routes/webhook.php
+++ b/routes/webhook.php
@@ -5,4 +5,8 @@
 use App\Http\Controllers\Webhooks\TelegramWebhookController;
 use Illuminate\Support\Facades\Route;
 
-Route::post('telegram/webhook', [TelegramWebhookController::class, 'handle'])->name('telegram.webhook');
+Route::group([
+    'domain' => parse_url(config('app.webhook_url'), PHP_URL_HOST) ?: config('app.webhook_url'),
+], function () {
+    Route::post('telegram/webhook', [TelegramWebhookController::class, 'handle'])->name('telegram.webhook');
+});

From 33bc0019779408c03cf6fdeb5dda8fe166bbe2b3 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 09:32:09 -0300
Subject: [PATCH 15/35] Truncate the long Telegram connect code so the dialog
 doesn't overflow

---
 resources/js/components/accounts/TelegramConnectDialog.vue | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index 33b12f2b..461da084 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -197,7 +197,7 @@ onUnmounted(stopPolling);
                             class="flex size-6 shrink-0 items-center justify-center rounded-full border-2 border-foreground text-xs font-semibold"
                             >2</span
                         >
-                        <div class="flex-1 space-y-2">
+                        <div class="min-w-0 flex-1 space-y-2">
                             <span>{{
                                 $t('accounts.telegram.step_command')
                             }}</span>
@@ -206,7 +206,9 @@ onUnmounted(stopPolling);
                                 class="group flex w-full items-center justify-between gap-2 rounded-lg border bg-muted px-3 py-2 text-left font-mono text-sm transition-colors hover:bg-muted/70"
                                 @click="copyCommand"
                             >
-                                <span>/connect {{ code }}</span>
+                                <span class="min-w-0 truncate"
+                                    >/connect {{ code }}</span
+                                >
                                 <IconCopy
                                     class="size-4 shrink-0 text-muted-foreground group-hover:text-foreground"
                                 />

From d5da44fd757b3a39f9eb5708398df7f0733cf73e Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 09:36:42 -0300
Subject: [PATCH 16/35] Fix Telegram dialog overflow (min-w-0 grid item), round
 icon, dedupe copy toast

---
 .../js/components/accounts/TelegramConnectDialog.vue   | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index 461da084..5dff9bf7 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -104,8 +104,10 @@ const start = async () => {
 };
 
 const copyCommand = () => {
-    copyToClipboard(`/connect ${code.value}`);
-    toast.success(trans('accounts.telegram.copied_toast'));
+    copyToClipboard(
+        `/connect ${code.value}`,
+        trans('accounts.telegram.copied_toast'),
+    );
 };
 
 watch(open, (isOpen) => {
@@ -127,7 +129,7 @@ onUnmounted(stopPolling);
                     <img
                         src="/images/accounts/telegram.png"
                         alt="Telegram"
-                        class="size-10"
+                        class="size-10 rounded-lg"
                     />
                     <div class="text-left">
                         <DialogTitle>{{
@@ -179,7 +181,7 @@ onUnmounted(stopPolling);
                 </p>
             </div>
 
-            <div v-else class="space-y-5 py-2">
+            <div v-else class="min-w-0 space-y-5 py-2">
                 <ol class="space-y-4 text-sm">
                     <li class="flex gap-3">
                         <span

From ec5a3a3b162bb0f9a01e95380461fa77faca9432 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 09:42:31 -0300
Subject: [PATCH 17/35] Add cursor-pointer and tooltip to Telegram copy button

---
 lang/en/accounts.php                          |  1 +
 lang/es/accounts.php                          |  1 +
 lang/pt-BR/accounts.php                       |  1 +
 .../accounts/TelegramConnectDialog.vue        | 45 ++++++++++++++-----
 4 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/lang/en/accounts.php b/lang/en/accounts.php
index 9a58a9ad..c30ef3ff 100644
--- a/lang/en/accounts.php
+++ b/lang/en/accounts.php
@@ -92,6 +92,7 @@
         'connected' => 'Channel connected!',
         'connected_toast' => 'Telegram channel connected successfully!',
         'copied_toast' => 'Command copied to clipboard',
+        'copy_tooltip' => 'Copy command',
         'expired' => 'This code has expired. Generate a new one to try again.',
         'new_code' => 'Generate a new code',
         'retry' => 'Try again',
diff --git a/lang/es/accounts.php b/lang/es/accounts.php
index 48842e10..0a6fd872 100644
--- a/lang/es/accounts.php
+++ b/lang/es/accounts.php
@@ -92,6 +92,7 @@
         'connected' => '¡Canal conectado!',
         'connected_toast' => '¡Canal de Telegram conectado correctamente!',
         'copied_toast' => 'Comando copiado al portapapeles',
+        'copy_tooltip' => 'Copiar comando',
         'expired' => 'Este código ha caducado. Genera uno nuevo para volver a intentarlo.',
         'new_code' => 'Generar un nuevo código',
         'retry' => 'Reintentar',
diff --git a/lang/pt-BR/accounts.php b/lang/pt-BR/accounts.php
index 7c238aa9..bc103450 100644
--- a/lang/pt-BR/accounts.php
+++ b/lang/pt-BR/accounts.php
@@ -92,6 +92,7 @@
         'connected' => 'Canal conectado!',
         'connected_toast' => 'Canal do Telegram conectado com sucesso!',
         'copied_toast' => 'Comando copiado para a área de transferência',
+        'copy_tooltip' => 'Copiar comando',
         'expired' => 'Este código expirou. Gere um novo para tentar de novo.',
         'new_code' => 'Gerar um novo código',
         'retry' => 'Tentar novamente',
diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index 5dff9bf7..de946207 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -14,6 +14,12 @@ import {
     DialogHeader,
     DialogTitle,
 } from '@/components/ui/dialog';
+import {
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
+} from '@/components/ui/tooltip';
 import { copyToClipboard } from '@/lib/utils';
 import {
     connect as connectTelegram,
@@ -203,18 +209,33 @@ onUnmounted(stopPolling);
                             <span>{{
                                 $t('accounts.telegram.step_command')
                             }}</span>
-                            <button
-                                type="button"
-                                class="group flex w-full items-center justify-between gap-2 rounded-lg border bg-muted px-3 py-2 text-left font-mono text-sm transition-colors hover:bg-muted/70"
-                                @click="copyCommand"
-                            >
-                                <span class="min-w-0 truncate"
-                                    >/connect {{ code }}</span
-                                >
-                                <IconCopy
-                                    class="size-4 shrink-0 text-muted-foreground group-hover:text-foreground"
-                                />
-                            </button>
+                            <TooltipProvider>
+                                <Tooltip>
+                                    <TooltipTrigger as-child>
+                                        <button
+                                            type="button"
+                                            class="group flex w-full cursor-pointer items-center justify-between gap-2 rounded-lg border bg-muted px-3 py-2 text-left font-mono text-sm transition-colors hover:bg-muted/70"
+                                            @click="copyCommand"
+                                        >
+                                            <span class="min-w-0 truncate"
+                                                >/connect {{ code }}</span
+                                            >
+                                            <IconCopy
+                                                class="size-4 shrink-0 text-muted-foreground group-hover:text-foreground"
+                                            />
+                                        </button>
+                                    </TooltipTrigger>
+                                    <TooltipContent>
+                                        <p>
+                                            {{
+                                                $t(
+                                                    'accounts.telegram.copy_tooltip',
+                                                )
+                                            }}
+                                        </p>
+                                    </TooltipContent>
+                                </Tooltip>
+                            </TooltipProvider>
                         </div>
                     </li>
                 </ol>

From 92e642590695220a842cd12332528229d58787a7 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 09:55:50 -0300
Subject: [PATCH 18/35] Use Platform enum instead of magic string in
 AddSocialDialog

---
 resources/js/components/accounts/AddSocialDialog.vue | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/resources/js/components/accounts/AddSocialDialog.vue b/resources/js/components/accounts/AddSocialDialog.vue
index 06a57081..0e93b7a1 100644
--- a/resources/js/components/accounts/AddSocialDialog.vue
+++ b/resources/js/components/accounts/AddSocialDialog.vue
@@ -14,6 +14,7 @@ import {
     DialogTitle,
 } from '@/components/ui/dialog';
 import { useOAuthPopup } from '@/composables/useOAuthPopup';
+import { Platform } from '@/types/platform';
 
 export interface AvailablePlatform {
     value: string;
@@ -118,7 +119,7 @@ const { openOAuthPopup } = useOAuthPopup(() => {
 const connectPlatform = (platformValue: string) => {
     open.value = false;
 
-    if (platformValue === 'telegram') {
+    if (platformValue === Platform.Telegram) {
         telegramOpen.value = true;
         return;
     }
@@ -147,7 +148,6 @@ const connectPlatform = (platformValue: string) => {
                         :key="platform.value"
                         class="group relative flex flex-col items-center gap-3 rounded-xl border-2 border-foreground bg-card p-4 text-center shadow-xs transition-shadow hover:shadow-md"
                     >
-                        <!-- "+" sticker badge appears only on hover so the grid doesn't feel cluttered. -->
                         <span
                             class="pointer-events-none absolute -top-2 -right-2 inline-flex size-6 items-center justify-center rounded-full border-2 border-foreground bg-violet-200 text-foreground opacity-0 shadow-2xs transition-all group-hover:scale-110 group-hover:rotate-90 group-hover:opacity-100"
                             aria-hidden="true"

From 58eab0619b9d8ab6d84337ca67deea6af7a8de14 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 09:59:36 -0300
Subject: [PATCH 19/35] Use TelegramConnectStatus enum for connect status
 instead of magic strings

---
 .../accounts/TelegramConnectDialog.vue           | 16 ++++++++++------
 resources/js/types/telegram-connect-status.ts    |  8 ++++++++
 2 files changed, 18 insertions(+), 6 deletions(-)
 create mode 100644 resources/js/types/telegram-connect-status.ts

diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index de946207..0f875f63 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -25,11 +25,14 @@ import {
     connect as connectTelegram,
     status as telegramStatus,
 } from '@/routes/app/social/telegram';
+import {
+    TelegramConnectStatus,
+    type TelegramConnectStatusValue,
+} from '@/types/telegram-connect-status';
 
 const open = defineModel<boolean>('open', { required: true });
 
 type Phase = 'loading' | 'ready' | 'connected' | 'expired' | 'error';
-type ConnectStatus = 'unknown' | 'pending' | 'connected';
 
 interface ConnectResponse {
     code: string;
@@ -46,9 +49,10 @@ const botUsername = ref('');
 const errorMessage = ref('');
 
 const httpConnect = useHttp<Record<string, never>, ConnectResponse>({});
-const httpStatus = useHttp<Record<string, never>, { status: ConnectStatus }>(
-    {},
-);
+const httpStatus = useHttp<
+    Record<string, never>,
+    { status: TelegramConnectStatusValue }
+>({});
 
 let pollTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -67,7 +71,7 @@ const poll = async () => {
             telegramStatus.url({ query: { code: code.value } }),
         );
 
-        if (response?.status === 'connected') {
+        if (response?.status === TelegramConnectStatus.Connected) {
             phase.value = 'connected';
             stopPolling();
             toast.success(trans('accounts.telegram.connected_toast'));
@@ -79,7 +83,7 @@ const poll = async () => {
         }
 
         // The signed code expired (or the session was lost): prompt a fresh one.
-        if (response?.status === 'unknown') {
+        if (response?.status === TelegramConnectStatus.Unknown) {
             phase.value = 'expired';
             stopPolling();
             return;
diff --git a/resources/js/types/telegram-connect-status.ts b/resources/js/types/telegram-connect-status.ts
new file mode 100644
index 00000000..4a380801
--- /dev/null
+++ b/resources/js/types/telegram-connect-status.ts
@@ -0,0 +1,8 @@
+export const TelegramConnectStatus = {
+    Unknown: 'unknown',
+    Pending: 'pending',
+    Connected: 'connected',
+} as const;
+
+export type TelegramConnectStatusValue =
+    (typeof TelegramConnectStatus)[keyof typeof TelegramConnectStatus];

From b9cc12aef7d7abd0a1f520970019b38f2a3cf86a Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 10:18:44 -0300
Subject: [PATCH 20/35] Fetch Telegram channel photo as avatar; extract
 ConnectTelegramChannel action

---
 .../SocialAccount/ConnectTelegramChannel.php  | 84 +++++++++++++++++++
 .../Webhooks/TelegramWebhookController.php    | 63 +-------------
 app/Jobs/SyncTelegramAccountAvatar.php        | 50 +++++++++++
 .../Jobs/SyncTelegramAccountAvatarTest.php    | 39 +++++++++
 .../Feature/Social/TelegramConnectionTest.php |  6 ++
 5 files changed, 182 insertions(+), 60 deletions(-)
 create mode 100644 app/Actions/SocialAccount/ConnectTelegramChannel.php
 create mode 100644 app/Jobs/SyncTelegramAccountAvatar.php
 create mode 100644 tests/Feature/Jobs/SyncTelegramAccountAvatarTest.php

diff --git a/app/Actions/SocialAccount/ConnectTelegramChannel.php b/app/Actions/SocialAccount/ConnectTelegramChannel.php
new file mode 100644
index 00000000..0e2514f4
--- /dev/null
+++ b/app/Actions/SocialAccount/ConnectTelegramChannel.php
@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\SocialAccount;
+
+use App\Enums\SocialAccount\Platform;
+use App\Enums\SocialAccount\Status;
+use App\Features\SocialAccountLimit;
+use App\Jobs\SyncTelegramAccountAvatar;
+use App\Models\SocialAccount;
+use App\Models\Workspace;
+use Illuminate\Support\Facades\Cache;
+use Laravel\Pennant\Feature;
+
+class ConnectTelegramChannel
+{
+    /**
+     * Link a Telegram chat to a workspace for a one-off connect nonce.
+     *
+     * @param  array<string, mixed>  $chat  The `chat` object from the Bot API update.
+     * @return SocialAccount|null The linked account, or null when blocked (account
+     *                            limit reached or the code was already consumed).
+     */
+    public static function execute(Workspace $workspace, array $chat, string $nonce): ?SocialAccount
+    {
+        $chatId = (string) data_get($chat, 'id');
+        $username = data_get($chat, 'username');
+
+        // Block only brand-new accounts against the plan limit, never reconnects.
+        $isNewAccount = ! $workspace->socialAccounts()
+            ->where('platform', Platform::Telegram->value)
+            ->where('platform_user_id', $chatId)
+            ->exists();
+
+        if ($isNewAccount && self::workspaceAtAccountLimit($workspace)) {
+            return null;
+        }
+
+        // Consume the code once so a leaked code can't be replayed to link another chat.
+        if (! Cache::add("telegram:connect:{$nonce}", true, now()->addMinutes(15))) {
+            return null;
+        }
+
+        $account = $workspace->socialAccounts()->updateOrCreate(
+            [
+                'platform' => Platform::Telegram->value,
+                'platform_user_id' => $chatId,
+            ],
+            [
+                'username' => $username,
+                'display_name' => data_get($chat, 'title') ?? $username ?? "Telegram {$chatId}",
+                'access_token' => '',
+                'refresh_token' => '',
+                'token_expires_at' => null,
+                'scopes' => [],
+                'status' => Status::Connected,
+                'error_message' => null,
+                'disconnected_at' => null,
+                'meta' => [
+                    'chat_id' => $chatId,
+                    'username' => $username,
+                    'type' => data_get($chat, 'type'),
+                    'connect_nonce' => $nonce,
+                ],
+            ],
+        );
+
+        SyncTelegramAccountAvatar::dispatch($account);
+
+        return $account;
+    }
+
+    private static function workspaceAtAccountLimit(Workspace $workspace): bool
+    {
+        if (config('trypost.self_hosted')) {
+            return false;
+        }
+
+        $limit = Feature::for($workspace->account)->value(SocialAccountLimit::class);
+
+        return $workspace->socialAccounts()->count() >= $limit;
+    }
+}
diff --git a/app/Http/Controllers/Webhooks/TelegramWebhookController.php b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
index 6aa0e05f..04400724 100644
--- a/app/Http/Controllers/Webhooks/TelegramWebhookController.php
+++ b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
@@ -4,16 +4,12 @@
 
 namespace App\Http\Controllers\Webhooks;
 
-use App\Enums\SocialAccount\Platform as SocialPlatform;
-use App\Enums\SocialAccount\Status;
-use App\Features\SocialAccountLimit;
+use App\Actions\SocialAccount\ConnectTelegramChannel;
 use App\Http\Controllers\Controller;
 use App\Models\Workspace;
 use App\Services\Social\TelegramConnectCode;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
-use Illuminate\Support\Facades\Cache;
-use Laravel\Pennant\Feature;
 use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
 
 class TelegramWebhookController extends Controller
@@ -43,63 +39,10 @@ public function handle(Request $request): Response
         $payload = TelegramConnectCode::decode($matches[1]);
         $workspace = $payload === null ? null : Workspace::find(data_get($payload, 'workspace_id'));
 
-        if ($workspace === null) {
-            return response()->noContent();
+        if ($workspace !== null) {
+            ConnectTelegramChannel::execute($workspace, $chat, data_get($payload, 'nonce'));
         }
 
-        $chatId = (string) data_get($chat, 'id');
-        $username = data_get($chat, 'username');
-
-        // Mirror the controller's limit gate: block only brand-new accounts, never reconnects.
-        $isNewAccount = ! $workspace->socialAccounts()
-            ->where('platform', SocialPlatform::Telegram->value)
-            ->where('platform_user_id', $chatId)
-            ->exists();
-
-        if ($isNewAccount && $this->workspaceAtAccountLimit($workspace)) {
-            return response()->noContent();
-        }
-
-        // Consume the code once so a leaked code can't be replayed to link another chat.
-        if (! Cache::add("telegram:connect:{$payload['nonce']}", true, now()->addMinutes(15))) {
-            return response()->noContent();
-        }
-
-        $workspace->socialAccounts()->updateOrCreate(
-            [
-                'platform' => SocialPlatform::Telegram->value,
-                'platform_user_id' => $chatId,
-            ],
-            [
-                'username' => $username,
-                'display_name' => data_get($chat, 'title') ?? $username ?? "Telegram {$chatId}",
-                'access_token' => '',
-                'refresh_token' => '',
-                'token_expires_at' => null,
-                'scopes' => [],
-                'status' => Status::Connected,
-                'error_message' => null,
-                'disconnected_at' => null,
-                'meta' => [
-                    'chat_id' => $chatId,
-                    'username' => $username,
-                    'type' => data_get($chat, 'type'),
-                    'connect_nonce' => data_get($payload, 'nonce'),
-                ],
-            ],
-        );
-
         return response()->noContent();
     }
-
-    private function workspaceAtAccountLimit(Workspace $workspace): bool
-    {
-        if (config('trypost.self_hosted')) {
-            return false;
-        }
-
-        $limit = Feature::for($workspace->account)->value(SocialAccountLimit::class);
-
-        return $workspace->socialAccounts()->count() >= $limit;
-    }
 }
diff --git a/app/Jobs/SyncTelegramAccountAvatar.php b/app/Jobs/SyncTelegramAccountAvatar.php
new file mode 100644
index 00000000..de2268b4
--- /dev/null
+++ b/app/Jobs/SyncTelegramAccountAvatar.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\SocialAccount;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Queue\Queueable;
+use Illuminate\Support\Facades\Http;
+
+class SyncTelegramAccountAvatar implements ShouldQueue
+{
+    use Queueable;
+
+    public int $tries = 1;
+
+    public function __construct(public SocialAccount $account) {}
+
+    public function handle(): void
+    {
+        $token = (string) config('trypost.platforms.telegram.bot_token');
+        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
+        $chatId = data_get($this->account->meta, 'chat_id');
+
+        if ($token === '' || $chatId === null) {
+            return;
+        }
+
+        $chat = Http::get("{$api}/bot{$token}/getChat", ['chat_id' => $chatId]);
+        $fileId = data_get($chat->json(), 'result.photo.big_file_id');
+
+        if (! is_string($fileId)) {
+            return;
+        }
+
+        $file = Http::get("{$api}/bot{$token}/getFile", ['file_id' => $fileId]);
+        $filePath = data_get($file->json(), 'result.file_path');
+
+        if (! is_string($filePath)) {
+            return;
+        }
+
+        $avatar = uploadFromUrl("{$api}/file/bot{$token}/{$filePath}");
+
+        if ($avatar !== null) {
+            $this->account->update(['avatar_url' => $avatar]);
+        }
+    }
+}
diff --git a/tests/Feature/Jobs/SyncTelegramAccountAvatarTest.php b/tests/Feature/Jobs/SyncTelegramAccountAvatarTest.php
new file mode 100644
index 00000000..9072c7f6
--- /dev/null
+++ b/tests/Feature/Jobs/SyncTelegramAccountAvatarTest.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Jobs\SyncTelegramAccountAvatar;
+use App\Models\SocialAccount;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Storage;
+
+beforeEach(function () {
+    config(['trypost.platforms.telegram.bot_token' => 'TESTTOKEN']);
+    Storage::fake();
+});
+
+it('stores the telegram channel photo as the account avatar', function () {
+    $account = SocialAccount::factory()->telegram()->create(['avatar_url' => null]);
+
+    Http::fake([
+        '*/botTESTTOKEN/getChat*' => Http::response(['ok' => true, 'result' => ['photo' => ['big_file_id' => 'BIGFILE']]], 200),
+        '*/botTESTTOKEN/getFile*' => Http::response(['ok' => true, 'result' => ['file_path' => 'photos/file_1.jpg']], 200),
+        '*/file/botTESTTOKEN/photos/file_1.jpg' => Http::response('image-bytes', 200, ['Content-Type' => 'image/jpeg']),
+    ]);
+
+    (new SyncTelegramAccountAvatar($account))->handle();
+
+    expect($account->fresh()->getRawOriginal('avatar_url'))->not->toBeNull();
+});
+
+it('does nothing when the channel has no photo', function () {
+    $account = SocialAccount::factory()->telegram()->create(['avatar_url' => null]);
+
+    Http::fake([
+        '*/botTESTTOKEN/getChat*' => Http::response(['ok' => true, 'result' => []], 200),
+    ]);
+
+    (new SyncTelegramAccountAvatar($account))->handle();
+
+    expect($account->fresh()->getRawOriginal('avatar_url'))->toBeNull();
+});
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index d39f9094..2f8451d5 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -4,14 +4,18 @@
 
 use App\Enums\SocialAccount\Platform;
 use App\Enums\UserWorkspace\Role;
+use App\Jobs\SyncTelegramAccountAvatar;
 use App\Models\SocialAccount;
 use App\Models\User;
 use App\Models\Workspace;
 use App\Services\Social\ConnectionVerifier;
 use App\Services\Social\TelegramConnectCode;
 use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Queue;
 
 beforeEach(function () {
+    Queue::fake();
+
     config([
         'trypost.platforms.telegram.bot_token' => 'TESTTOKEN',
         'trypost.platforms.telegram.bot_username' => 'TryPostBot',
@@ -72,6 +76,8 @@ function telegramUpdate(string $code, array $chat = []): array
     expect(data_get($account->meta, 'chat_id'))->toBe('-1001234567890');
     expect(data_get($account->meta, 'connect_nonce'))
         ->toBe(data_get(TelegramConnectCode::decode($code), 'nonce'));
+
+    Queue::assertPushed(SyncTelegramAccountAvatar::class);
 });
 
 it('links a private channel that has no username', function () {

From f194bde58d5fea355a5f0a23c36514d2d6564fa6 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 10:21:52 -0300
Subject: [PATCH 21/35] Fall back to display_name for disconnect confirmation
 when username is null (Telegram)

---
 resources/js/pages/accounts/Index.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/js/pages/accounts/Index.vue b/resources/js/pages/accounts/Index.vue
index bec3d356..9a52f75e 100644
--- a/resources/js/pages/accounts/Index.vue
+++ b/resources/js/pages/accounts/Index.vue
@@ -121,7 +121,7 @@ const handleToggle = (accountId: string) => {
 const handleDisconnect = (account: SocialAccount) => {
     deleteModal.value?.open({
         url: disconnectAccount.url(account.id),
-        confirmText: account.username,
+        confirmText: account.username || account.display_name,
     });
 };
 </script>

From f5d6c4a18694b525ccfb609d0ee513a62a9594c9 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 10:30:17 -0300
Subject: [PATCH 22/35] Fetch Telegram channel photo synchronously in the
 connect action (drop avatar job)

---
 .../SocialAccount/ConnectTelegramChannel.php  | 37 ++++++++++++--
 app/Jobs/SyncTelegramAccountAvatar.php        | 50 -------------------
 .../Jobs/SyncTelegramAccountAvatarTest.php    | 39 ---------------
 .../Feature/Social/TelegramConnectionTest.php | 29 +++++++++--
 4 files changed, 57 insertions(+), 98 deletions(-)
 delete mode 100644 app/Jobs/SyncTelegramAccountAvatar.php
 delete mode 100644 tests/Feature/Jobs/SyncTelegramAccountAvatarTest.php

diff --git a/app/Actions/SocialAccount/ConnectTelegramChannel.php b/app/Actions/SocialAccount/ConnectTelegramChannel.php
index 0e2514f4..b5711919 100644
--- a/app/Actions/SocialAccount/ConnectTelegramChannel.php
+++ b/app/Actions/SocialAccount/ConnectTelegramChannel.php
@@ -7,11 +7,12 @@
 use App\Enums\SocialAccount\Platform;
 use App\Enums\SocialAccount\Status;
 use App\Features\SocialAccountLimit;
-use App\Jobs\SyncTelegramAccountAvatar;
 use App\Models\SocialAccount;
 use App\Models\Workspace;
 use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Http;
 use Laravel\Pennant\Feature;
+use Throwable;
 
 class ConnectTelegramChannel
 {
@@ -42,7 +43,7 @@ public static function execute(Workspace $workspace, array $chat, string $nonce)
             return null;
         }
 
-        $account = $workspace->socialAccounts()->updateOrCreate(
+        return $workspace->socialAccounts()->updateOrCreate(
             [
                 'platform' => Platform::Telegram->value,
                 'platform_user_id' => $chatId,
@@ -50,6 +51,7 @@ public static function execute(Workspace $workspace, array $chat, string $nonce)
             [
                 'username' => $username,
                 'display_name' => data_get($chat, 'title') ?? $username ?? "Telegram {$chatId}",
+                'avatar_url' => self::fetchChannelAvatar($chatId),
                 'access_token' => '',
                 'refresh_token' => '',
                 'token_expires_at' => null,
@@ -65,10 +67,37 @@ public static function execute(Workspace $workspace, array $chat, string $nonce)
                 ],
             ],
         );
+    }
 
-        SyncTelegramAccountAvatar::dispatch($account);
+    /**
+     * Download the channel's photo via the Bot API and store it, returning the path.
+     */
+    private static function fetchChannelAvatar(string $chatId): ?string
+    {
+        $token = (string) config('trypost.platforms.telegram.bot_token');
+        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
 
-        return $account;
+        if ($token === '') {
+            return null;
+        }
+
+        try {
+            $fileId = data_get(Http::get("{$api}/bot{$token}/getChat", ['chat_id' => $chatId])->json(), 'result.photo.big_file_id');
+
+            if (! is_string($fileId)) {
+                return null;
+            }
+
+            $filePath = data_get(Http::get("{$api}/bot{$token}/getFile", ['file_id' => $fileId])->json(), 'result.file_path');
+
+            if (! is_string($filePath)) {
+                return null;
+            }
+
+            return uploadFromUrl("{$api}/file/bot{$token}/{$filePath}");
+        } catch (Throwable) {
+            return null;
+        }
     }
 
     private static function workspaceAtAccountLimit(Workspace $workspace): bool
diff --git a/app/Jobs/SyncTelegramAccountAvatar.php b/app/Jobs/SyncTelegramAccountAvatar.php
deleted file mode 100644
index de2268b4..00000000
--- a/app/Jobs/SyncTelegramAccountAvatar.php
+++ /dev/null
@@ -1,50 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace App\Jobs;
-
-use App\Models\SocialAccount;
-use Illuminate\Contracts\Queue\ShouldQueue;
-use Illuminate\Foundation\Queue\Queueable;
-use Illuminate\Support\Facades\Http;
-
-class SyncTelegramAccountAvatar implements ShouldQueue
-{
-    use Queueable;
-
-    public int $tries = 1;
-
-    public function __construct(public SocialAccount $account) {}
-
-    public function handle(): void
-    {
-        $token = (string) config('trypost.platforms.telegram.bot_token');
-        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
-        $chatId = data_get($this->account->meta, 'chat_id');
-
-        if ($token === '' || $chatId === null) {
-            return;
-        }
-
-        $chat = Http::get("{$api}/bot{$token}/getChat", ['chat_id' => $chatId]);
-        $fileId = data_get($chat->json(), 'result.photo.big_file_id');
-
-        if (! is_string($fileId)) {
-            return;
-        }
-
-        $file = Http::get("{$api}/bot{$token}/getFile", ['file_id' => $fileId]);
-        $filePath = data_get($file->json(), 'result.file_path');
-
-        if (! is_string($filePath)) {
-            return;
-        }
-
-        $avatar = uploadFromUrl("{$api}/file/bot{$token}/{$filePath}");
-
-        if ($avatar !== null) {
-            $this->account->update(['avatar_url' => $avatar]);
-        }
-    }
-}
diff --git a/tests/Feature/Jobs/SyncTelegramAccountAvatarTest.php b/tests/Feature/Jobs/SyncTelegramAccountAvatarTest.php
deleted file mode 100644
index 9072c7f6..00000000
--- a/tests/Feature/Jobs/SyncTelegramAccountAvatarTest.php
+++ /dev/null
@@ -1,39 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-use App\Jobs\SyncTelegramAccountAvatar;
-use App\Models\SocialAccount;
-use Illuminate\Support\Facades\Http;
-use Illuminate\Support\Facades\Storage;
-
-beforeEach(function () {
-    config(['trypost.platforms.telegram.bot_token' => 'TESTTOKEN']);
-    Storage::fake();
-});
-
-it('stores the telegram channel photo as the account avatar', function () {
-    $account = SocialAccount::factory()->telegram()->create(['avatar_url' => null]);
-
-    Http::fake([
-        '*/botTESTTOKEN/getChat*' => Http::response(['ok' => true, 'result' => ['photo' => ['big_file_id' => 'BIGFILE']]], 200),
-        '*/botTESTTOKEN/getFile*' => Http::response(['ok' => true, 'result' => ['file_path' => 'photos/file_1.jpg']], 200),
-        '*/file/botTESTTOKEN/photos/file_1.jpg' => Http::response('image-bytes', 200, ['Content-Type' => 'image/jpeg']),
-    ]);
-
-    (new SyncTelegramAccountAvatar($account))->handle();
-
-    expect($account->fresh()->getRawOriginal('avatar_url'))->not->toBeNull();
-});
-
-it('does nothing when the channel has no photo', function () {
-    $account = SocialAccount::factory()->telegram()->create(['avatar_url' => null]);
-
-    Http::fake([
-        '*/botTESTTOKEN/getChat*' => Http::response(['ok' => true, 'result' => []], 200),
-    ]);
-
-    (new SyncTelegramAccountAvatar($account))->handle();
-
-    expect($account->fresh()->getRawOriginal('avatar_url'))->toBeNull();
-});
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index 2f8451d5..b5acad5a 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -4,18 +4,15 @@
 
 use App\Enums\SocialAccount\Platform;
 use App\Enums\UserWorkspace\Role;
-use App\Jobs\SyncTelegramAccountAvatar;
 use App\Models\SocialAccount;
 use App\Models\User;
 use App\Models\Workspace;
 use App\Services\Social\ConnectionVerifier;
 use App\Services\Social\TelegramConnectCode;
 use Illuminate\Support\Facades\Http;
-use Illuminate\Support\Facades\Queue;
+use Illuminate\Support\Facades\Storage;
 
 beforeEach(function () {
-    Queue::fake();
-
     config([
         'trypost.platforms.telegram.bot_token' => 'TESTTOKEN',
         'trypost.platforms.telegram.bot_username' => 'TryPostBot',
@@ -59,6 +56,7 @@ function telegramUpdate(string $code, array $chat = []): array
 });
 
 it('links the channel when the webhook receives a matching /connect', function () {
+    Http::fake();
     $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
@@ -76,11 +74,30 @@ function telegramUpdate(string $code, array $chat = []): array
     expect(data_get($account->meta, 'chat_id'))->toBe('-1001234567890');
     expect(data_get($account->meta, 'connect_nonce'))
         ->toBe(data_get(TelegramConnectCode::decode($code), 'nonce'));
+});
 
-    Queue::assertPushed(SyncTelegramAccountAvatar::class);
+it('stores the channel photo as the account avatar on connect', function () {
+    Storage::fake();
+
+    Http::fake([
+        '*/botTESTTOKEN/getChat*' => Http::response(['ok' => true, 'result' => ['photo' => ['big_file_id' => 'BIGFILE']]], 200),
+        '*/botTESTTOKEN/getFile*' => Http::response(['ok' => true, 'result' => ['file_path' => 'photos/file_1.jpg']], 200),
+        '*/file/botTESTTOKEN/photos/file_1.jpg' => Http::response('image-bytes', 200, ['Content-Type' => 'image/jpeg']),
+    ]);
+
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate($code))
+        ->assertNoContent();
+
+    $account = SocialAccount::where('platform', Platform::Telegram)->first();
+
+    expect($account->getRawOriginal('avatar_url'))->not->toBeNull();
 });
 
 it('links a private channel that has no username', function () {
+    Http::fake();
     $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
@@ -112,6 +129,7 @@ function telegramUpdate(string $code, array $chat = []): array
 });
 
 it('still reconnects an existing telegram channel even at the account limit', function () {
+    Http::fake();
     config(['trypost.self_hosted' => false]);
 
     SocialAccount::factory()->count(4)->create(['workspace_id' => $this->workspace->id]);
@@ -133,6 +151,7 @@ function telegramUpdate(string $code, array $chat = []): array
 });
 
 it('consumes the code once so it cannot be replayed for another chat', function () {
+    Http::fake();
     $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 
     $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')

From ce5d59a1491bb0cec1afacd9b4af8c05e9d104af Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 10:58:13 -0300
Subject: [PATCH 23/35] Detect Telegram connection via broadcast instead of
 polling

---
 .../SocialAccount/ConnectTelegramChannel.php  |  7 +-
 .../SocialAccount/TelegramConnectStatus.php   | 22 -----
 app/Events/TelegramChannelConnected.php       | 45 ++++++++++
 .../Controllers/Auth/TelegramController.php   | 32 ++-----
 .../accounts/TelegramConnectDialog.vue        | 86 ++++++++-----------
 resources/js/types/telegram-connect-status.ts |  8 --
 routes/app.php                                |  1 -
 .../Feature/Social/TelegramConnectionTest.php | 48 +++++------
 8 files changed, 117 insertions(+), 132 deletions(-)
 delete mode 100644 app/Enums/SocialAccount/TelegramConnectStatus.php
 create mode 100644 app/Events/TelegramChannelConnected.php
 delete mode 100644 resources/js/types/telegram-connect-status.ts

diff --git a/app/Actions/SocialAccount/ConnectTelegramChannel.php b/app/Actions/SocialAccount/ConnectTelegramChannel.php
index b5711919..45743922 100644
--- a/app/Actions/SocialAccount/ConnectTelegramChannel.php
+++ b/app/Actions/SocialAccount/ConnectTelegramChannel.php
@@ -6,6 +6,7 @@
 
 use App\Enums\SocialAccount\Platform;
 use App\Enums\SocialAccount\Status;
+use App\Events\TelegramChannelConnected;
 use App\Features\SocialAccountLimit;
 use App\Models\SocialAccount;
 use App\Models\Workspace;
@@ -43,7 +44,7 @@ public static function execute(Workspace $workspace, array $chat, string $nonce)
             return null;
         }
 
-        return $workspace->socialAccounts()->updateOrCreate(
+        $account = $workspace->socialAccounts()->updateOrCreate(
             [
                 'platform' => Platform::Telegram->value,
                 'platform_user_id' => $chatId,
@@ -67,6 +68,10 @@ public static function execute(Workspace $workspace, array $chat, string $nonce)
                 ],
             ],
         );
+
+        TelegramChannelConnected::dispatch($workspace->id, $nonce);
+
+        return $account;
     }
 
     /**
diff --git a/app/Enums/SocialAccount/TelegramConnectStatus.php b/app/Enums/SocialAccount/TelegramConnectStatus.php
deleted file mode 100644
index 56c006f9..00000000
--- a/app/Enums/SocialAccount/TelegramConnectStatus.php
+++ /dev/null
@@ -1,22 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace App\Enums\SocialAccount;
-
-use App\Models\SocialAccount;
-
-enum TelegramConnectStatus: string
-{
-    case Unknown = 'unknown';
-    case Pending = 'pending';
-    case Connected = 'connected';
-
-    /**
-     * Connected once the channel has been linked to an account; otherwise still pending.
-     */
-    public static function for(?SocialAccount $account): self
-    {
-        return $account === null ? self::Pending : self::Connected;
-    }
-}
diff --git a/app/Events/TelegramChannelConnected.php b/app/Events/TelegramChannelConnected.php
new file mode 100644
index 00000000..604207e3
--- /dev/null
+++ b/app/Events/TelegramChannelConnected.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Events;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Broadcasting\PrivateChannel;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class TelegramChannelConnected implements ShouldBroadcast
+{
+    use Dispatchable, InteractsWithSockets, SerializesModels;
+
+    public function __construct(public string $workspaceId, public string $nonce) {}
+
+    public function broadcastAs(): string
+    {
+        return 'telegram.channel.connected';
+    }
+
+    public function broadcastOn(): array
+    {
+        return [
+            new PrivateChannel("workspace.{$this->workspaceId}"),
+        ];
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function broadcastWith(): array
+    {
+        return [
+            'nonce' => $this->nonce,
+        ];
+    }
+
+    public function broadcastQueue(): string
+    {
+        return 'broadcasts';
+    }
+}
diff --git a/app/Http/Controllers/Auth/TelegramController.php b/app/Http/Controllers/Auth/TelegramController.php
index bf84f7e3..329bf8a1 100644
--- a/app/Http/Controllers/Auth/TelegramController.php
+++ b/app/Http/Controllers/Auth/TelegramController.php
@@ -5,7 +5,6 @@
 namespace App\Http\Controllers\Auth;
 
 use App\Enums\SocialAccount\Platform as SocialPlatform;
-use App\Enums\SocialAccount\TelegramConnectStatus;
 use App\Services\Social\TelegramConnectCode;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -18,7 +17,8 @@ class TelegramController extends SocialController
     /**
      * Start a connection: issue a signed one-off code the user posts in their
      * channel (`/connect <code>`). The code carries the workspace, so the webhook
-     * can link the channel without any persisted state.
+     * can link the channel without any persisted state. The returned `nonce` lets
+     * the UI recognise its own connection on the broadcast channel.
      */
     public function connect(Request $request): JsonResponse
     {
@@ -31,35 +31,13 @@ public function connect(Request $request): JsonResponse
         $this->ensureSocialAccountLimit($workspace);
 
         $expiresAt = now()->addMinutes(15);
+        $code = TelegramConnectCode::issue($workspace->id, $expiresAt);
 
         return response()->json([
-            'code' => TelegramConnectCode::issue($workspace->id, $expiresAt),
+            'code' => $code,
+            'nonce' => data_get(TelegramConnectCode::decode($code), 'nonce'),
             'bot_username' => config('trypost.platforms.telegram.bot_username'),
             'expires_at' => $expiresAt->toIso8601String(),
         ]);
     }
-
-    /**
-     * Poll whether the channel for the given code has been linked yet.
-     */
-    public function status(Request $request): JsonResponse
-    {
-        $workspace = $request->user()->currentWorkspace;
-        abort_if($workspace === null, SymfonyResponse::HTTP_CONFLICT, 'No active workspace.');
-
-        $payload = TelegramConnectCode::decode($request->query('code'));
-
-        if ($payload === null) {
-            return response()->json(['status' => TelegramConnectStatus::Unknown->value]);
-        }
-
-        $account = $workspace->socialAccounts()
-            ->where('platform', SocialPlatform::Telegram->value)
-            ->where('meta->connect_nonce', data_get($payload, 'nonce'))
-            ->first();
-
-        return response()->json([
-            'status' => TelegramConnectStatus::for($account)->value,
-        ]);
-    }
 }
diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index 0f875f63..ce84b8d6 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -20,15 +20,10 @@ import {
     TooltipProvider,
     TooltipTrigger,
 } from '@/components/ui/tooltip';
+import { useWorkspaceEcho } from '@/composables/echo/useWorkspaceEcho';
+import dayjs from '@/dayjs';
 import { copyToClipboard } from '@/lib/utils';
-import {
-    connect as connectTelegram,
-    status as telegramStatus,
-} from '@/routes/app/social/telegram';
-import {
-    TelegramConnectStatus,
-    type TelegramConnectStatusValue,
-} from '@/types/telegram-connect-status';
+import { connect as connectTelegram } from '@/routes/app/social/telegram';
 
 const open = defineModel<boolean>('open', { required: true });
 
@@ -36,64 +31,47 @@ type Phase = 'loading' | 'ready' | 'connected' | 'expired' | 'error';
 
 interface ConnectResponse {
     code: string;
+    nonce: string;
     bot_username: string;
     expires_at: string;
 }
 
-const POLL_INTERVAL_MS = 3000;
 const SUCCESS_CLOSE_DELAY_MS = 1200;
 
 const phase = ref<Phase>('loading');
 const code = ref('');
+const nonce = ref('');
 const botUsername = ref('');
 const errorMessage = ref('');
 
 const httpConnect = useHttp<Record<string, never>, ConnectResponse>({});
-const httpStatus = useHttp<
-    Record<string, never>,
-    { status: TelegramConnectStatusValue }
->({});
 
-let pollTimer: ReturnType<typeof setTimeout> | null = null;
+let expiryTimer: ReturnType<typeof setTimeout> | null = null;
 
-const stopPolling = () => {
-    if (pollTimer !== null) {
-        clearTimeout(pollTimer);
-        pollTimer = null;
+const clearExpiry = () => {
+    if (expiryTimer !== null) {
+        clearTimeout(expiryTimer);
+        expiryTimer = null;
     }
 };
 
-const poll = async () => {
-    if (phase.value !== 'ready') return;
-
-    try {
-        const response = await httpStatus.get(
-            telegramStatus.url({ query: { code: code.value } }),
-        );
-
-        if (response?.status === TelegramConnectStatus.Connected) {
-            phase.value = 'connected';
-            stopPolling();
-            toast.success(trans('accounts.telegram.connected_toast'));
-            setTimeout(() => {
-                open.value = false;
-                router.reload();
-            }, SUCCESS_CLOSE_DELAY_MS);
+// The channel is linked server-side by the webhook; Reverb pushes the result here.
+useWorkspaceEcho<{ nonce: string }>(
+    '.telegram.channel.connected',
+    (payload) => {
+        if (phase.value !== 'ready' || payload.nonce !== nonce.value) {
             return;
         }
 
-        // The signed code expired (or the session was lost): prompt a fresh one.
-        if (response?.status === TelegramConnectStatus.Unknown) {
-            phase.value = 'expired';
-            stopPolling();
-            return;
-        }
-    } catch {
-        // Transient polling failures are ignored; the next tick retries.
-    }
-
-    pollTimer = setTimeout(poll, POLL_INTERVAL_MS);
-};
+        phase.value = 'connected';
+        clearExpiry();
+        toast.success(trans('accounts.telegram.connected_toast'));
+        setTimeout(() => {
+            open.value = false;
+            router.reload();
+        }, SUCCESS_CLOSE_DELAY_MS);
+    },
+);
 
 const start = async () => {
     phase.value = 'loading';
@@ -102,9 +80,19 @@ const start = async () => {
     try {
         const response = await httpConnect.post(connectTelegram.url());
         code.value = response.code;
+        nonce.value = response.nonce;
         botUsername.value = response.bot_username;
         phase.value = 'ready';
-        poll();
+
+        clearExpiry();
+        expiryTimer = setTimeout(
+            () => {
+                if (phase.value === 'ready') {
+                    phase.value = 'expired';
+                }
+            },
+            Math.max(0, dayjs(response.expires_at).diff(dayjs())),
+        );
     } catch (error) {
         phase.value = 'error';
         errorMessage.value =
@@ -124,11 +112,11 @@ watch(open, (isOpen) => {
     if (isOpen) {
         start();
     } else {
-        stopPolling();
+        clearExpiry();
     }
 });
 
-onUnmounted(stopPolling);
+onUnmounted(clearExpiry);
 </script>
 
 <template>
diff --git a/resources/js/types/telegram-connect-status.ts b/resources/js/types/telegram-connect-status.ts
deleted file mode 100644
index 4a380801..00000000
--- a/resources/js/types/telegram-connect-status.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-export const TelegramConnectStatus = {
-    Unknown: 'unknown',
-    Pending: 'pending',
-    Connected: 'connected',
-} as const;
-
-export type TelegramConnectStatusValue =
-    (typeof TelegramConnectStatus)[keyof typeof TelegramConnectStatus];
diff --git a/routes/app.php b/routes/app.php
index f20c6a33..403d9a60 100644
--- a/routes/app.php
+++ b/routes/app.php
@@ -120,7 +120,6 @@
     Route::get('accounts/mastodon/callback', [MastodonController::class, 'callback'])->name('app.social.mastodon.callback');
 
     Route::post('connect/telegram', [TelegramController::class, 'connect'])->name('app.social.telegram.connect');
-    Route::get('connect/telegram/status', [TelegramController::class, 'status'])->name('app.social.telegram.status');
 });
 
 // Routes that require active subscription and completed onboarding
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index b5acad5a..4ba127aa 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -4,11 +4,13 @@
 
 use App\Enums\SocialAccount\Platform;
 use App\Enums\UserWorkspace\Role;
+use App\Events\TelegramChannelConnected;
 use App\Models\SocialAccount;
 use App\Models\User;
 use App\Models\Workspace;
 use App\Services\Social\ConnectionVerifier;
 use App\Services\Social\TelegramConnectCode;
+use Illuminate\Support\Facades\Event;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Storage;
 
@@ -48,11 +50,13 @@ function telegramUpdate(string $code, array $chat = []): array
     $response = $this->actingAs($this->user)
         ->postJson(route('app.social.telegram.connect'))
         ->assertOk()
-        ->assertJsonStructure(['code', 'bot_username', 'expires_at']);
+        ->assertJsonStructure(['code', 'nonce', 'bot_username', 'expires_at']);
 
     expect($response->json('bot_username'))->toBe('TryPostBot');
     expect(data_get(TelegramConnectCode::decode($response->json('code')), 'workspace_id'))
         ->toBe($this->workspace->id);
+    expect($response->json('nonce'))
+        ->toBe(data_get(TelegramConnectCode::decode($response->json('code')), 'nonce'));
 });
 
 it('links the channel when the webhook receives a matching /connect', function () {
@@ -189,36 +193,32 @@ function telegramUpdate(string $code, array $chat = []): array
     expect(SocialAccount::where('platform', Platform::Telegram)->count())->toBe(0);
 });
 
-it('reports the connection status for a code while pending and once connected', function () {
+it('broadcasts to the workspace with the nonce when a channel connects', function () {
+    Event::fake([TelegramChannelConnected::class]);
+    Http::fake();
+
     $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
     $nonce = data_get(TelegramConnectCode::decode($code), 'nonce');
 
-    $this->actingAs($this->user)
-        ->getJson(route('app.social.telegram.status', ['code' => $code]))
-        ->assertOk()
-        ->assertJson(['status' => 'pending']);
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate($code))
+        ->assertNoContent();
 
-    SocialAccount::factory()->telegram()->create([
-        'workspace_id' => $this->workspace->id,
-        'meta' => ['chat_id' => '-1001234567890', 'username' => 'mychannel', 'type' => 'channel', 'connect_nonce' => $nonce],
-    ]);
-
-    $this->actingAs($this->user)
-        ->getJson(route('app.social.telegram.status', ['code' => $code]))
-        ->assertOk()
-        ->assertJson(['status' => 'connected']);
+    Event::assertDispatched(
+        TelegramChannelConnected::class,
+        fn (TelegramChannelConnected $event) => $event->workspaceId === $this->workspace->id
+            && $event->nonce === $nonce,
+    );
 });
 
-it('reports unknown status without a valid code', function () {
-    $this->actingAs($this->user)
-        ->getJson(route('app.social.telegram.status'))
-        ->assertOk()
-        ->assertJson(['status' => 'unknown']);
+it('does not broadcast when the code is tampered or already used', function () {
+    Event::fake([TelegramChannelConnected::class]);
 
-    $this->actingAs($this->user)
-        ->getJson(route('app.social.telegram.status', ['code' => 'tampered']))
-        ->assertOk()
-        ->assertJson(['status' => 'unknown']);
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate('not-a-valid-code'))
+        ->assertNoContent();
+
+    Event::assertNotDispatched(TelegramChannelConnected::class);
 });
 
 it('verifies a connected telegram account via getChat', function () {

From ba246a3ddd01780ef12bba40f731da8c0b24a66b Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 11:18:40 -0300
Subject: [PATCH 24/35] Add Telegram analytics: per-post reactions (webhook) +
 channel subscribers

---
 .../SocialAccount/RegisterTelegramWebhook.php |  2 +-
 .../SocialAccount/StoreTelegramReactions.php  | 47 ++++++++++++++
 .../Controllers/App/AnalyticsController.php   |  3 +
 .../Webhooks/TelegramWebhookController.php    |  8 +++
 app/Services/Post/PostMetricsFetcher.php      |  2 +
 app/Services/Social/TelegramAnalytics.php     | 61 +++++++++++++++++++
 lang/en/analytics.php                         |  2 +
 lang/es/analytics.php                         |  2 +
 lang/pt-BR/analytics.php                      |  2 +
 .../analytics/TelegramAnalytics.vue           | 57 +++++++++++++++++
 resources/js/pages/analytics/Index.vue        |  6 ++
 .../RegisterTelegramWebhookTest.php           |  2 +-
 .../Services/Social/TelegramAnalyticsTest.php | 53 ++++++++++++++++
 .../Feature/Social/TelegramConnectionTest.php | 34 +++++++++++
 14 files changed, 279 insertions(+), 2 deletions(-)
 create mode 100644 app/Actions/SocialAccount/StoreTelegramReactions.php
 create mode 100644 app/Services/Social/TelegramAnalytics.php
 create mode 100644 resources/js/components/analytics/TelegramAnalytics.vue
 create mode 100644 tests/Feature/Services/Social/TelegramAnalyticsTest.php

diff --git a/app/Actions/SocialAccount/RegisterTelegramWebhook.php b/app/Actions/SocialAccount/RegisterTelegramWebhook.php
index 4b0757e0..58f42dda 100644
--- a/app/Actions/SocialAccount/RegisterTelegramWebhook.php
+++ b/app/Actions/SocialAccount/RegisterTelegramWebhook.php
@@ -33,7 +33,7 @@ public static function execute(): string
         $response = Http::post("{$api}/bot{$token}/setWebhook", [
             'url' => $url,
             'secret_token' => $secret,
-            'allowed_updates' => ['message', 'channel_post'],
+            'allowed_updates' => ['message', 'channel_post', 'message_reaction_count'],
         ]);
 
         if (! $response->successful() || data_get($response->json(), 'ok') !== true) {
diff --git a/app/Actions/SocialAccount/StoreTelegramReactions.php b/app/Actions/SocialAccount/StoreTelegramReactions.php
new file mode 100644
index 00000000..83998c5d
--- /dev/null
+++ b/app/Actions/SocialAccount/StoreTelegramReactions.php
@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\SocialAccount;
+
+use App\Enums\SocialAccount\Platform;
+use App\Models\PostPlatform;
+use Illuminate\Support\Facades\Cache;
+
+class StoreTelegramReactions
+{
+    /**
+     * Persist the reaction counts pushed by a `message_reaction_count` update
+     * onto the matching published post, so they surface as post metrics.
+     *
+     * @param  array<string, mixed>  $update  The `message_reaction_count` payload.
+     */
+    public static function execute(array $update): void
+    {
+        $chatId = (string) data_get($update, 'chat.id');
+        $messageId = (string) data_get($update, 'message_id');
+
+        if ($chatId === '' || $messageId === '') {
+            return;
+        }
+
+        $postPlatform = PostPlatform::query()
+            ->where('platform', Platform::Telegram->value)
+            ->where('platform_post_id', $messageId)
+            ->whereHas('socialAccount', fn ($query) => $query->where('meta->chat_id', $chatId))
+            ->first();
+
+        if ($postPlatform === null) {
+            return;
+        }
+
+        $reactions = array_values(array_map(fn (array $reaction): array => [
+            'type' => (string) (data_get($reaction, 'type.emoji') ?? __('analytics.metrics.custom_reaction')),
+            'count' => (int) data_get($reaction, 'total_count'),
+        ], data_get($update, 'reactions', [])));
+
+        $postPlatform->update(['meta' => [...$postPlatform->meta ?? [], 'reactions' => $reactions]]);
+
+        Cache::forget("post_metrics:{$postPlatform->id}");
+    }
+}
diff --git a/app/Http/Controllers/App/AnalyticsController.php b/app/Http/Controllers/App/AnalyticsController.php
index e3205698..084554b7 100644
--- a/app/Http/Controllers/App/AnalyticsController.php
+++ b/app/Http/Controllers/App/AnalyticsController.php
@@ -11,6 +11,7 @@
 use App\Services\Social\InstagramAnalytics;
 use App\Services\Social\LinkedInPageAnalytics;
 use App\Services\Social\PinterestAnalytics;
+use App\Services\Social\TelegramAnalytics;
 use App\Services\Social\ThreadsAnalytics;
 use App\Services\Social\TikTokAnalytics;
 use App\Services\Social\XAnalytics;
@@ -34,6 +35,7 @@ class AnalyticsController extends Controller
         Platform::LinkedInPage,
         Platform::Pinterest,
         Platform::YouTube,
+        Platform::Telegram,
     ];
 
     public function index(Request $request): Response
@@ -77,6 +79,7 @@ public function show(Request $request, SocialAccount $account): JsonResponse
             Platform::LinkedInPage => app(LinkedInPageAnalytics::class)->getMetrics($account, $since, $until),
             Platform::Pinterest => app(PinterestAnalytics::class)->getMetrics($account, $since, $until),
             Platform::YouTube => app(YouTubeAnalytics::class)->getMetrics($account, $since, $until),
+            Platform::Telegram => app(TelegramAnalytics::class)->getMetrics($account),
             default => [],
         };
 
diff --git a/app/Http/Controllers/Webhooks/TelegramWebhookController.php b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
index 04400724..c823a072 100644
--- a/app/Http/Controllers/Webhooks/TelegramWebhookController.php
+++ b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
@@ -5,6 +5,7 @@
 namespace App\Http\Controllers\Webhooks;
 
 use App\Actions\SocialAccount\ConnectTelegramChannel;
+use App\Actions\SocialAccount\StoreTelegramReactions;
 use App\Http\Controllers\Controller;
 use App\Models\Workspace;
 use App\Services\Social\TelegramConnectCode;
@@ -29,6 +30,13 @@ public function handle(Request $request): Response
         );
 
         $update = $request->all();
+
+        if (is_array($reactionUpdate = data_get($update, 'message_reaction_count'))) {
+            StoreTelegramReactions::execute($reactionUpdate);
+
+            return response()->noContent();
+        }
+
         $chat = data_get($update, 'message.chat') ?? data_get($update, 'channel_post.chat');
         $text = data_get($update, 'message.text') ?? data_get($update, 'channel_post.text');
 
diff --git a/app/Services/Post/PostMetricsFetcher.php b/app/Services/Post/PostMetricsFetcher.php
index 9f6ba8c4..78a5bb55 100644
--- a/app/Services/Post/PostMetricsFetcher.php
+++ b/app/Services/Post/PostMetricsFetcher.php
@@ -13,6 +13,7 @@
 use App\Services\Social\LinkedInPageAnalytics;
 use App\Services\Social\MastodonAnalytics;
 use App\Services\Social\PinterestAnalytics;
+use App\Services\Social\TelegramAnalytics;
 use App\Services\Social\ThreadsAnalytics;
 use App\Services\Social\XAnalytics;
 use App\Services\Social\YouTubeAnalytics;
@@ -64,6 +65,7 @@ public function forPlatform(PostPlatform $postPlatform): array
             Platform::X => app(XAnalytics::class)->fetchPostMetrics($postPlatform),
             Platform::Bluesky => app(BlueskyAnalytics::class)->fetchPostMetrics($postPlatform),
             Platform::Mastodon => app(MastodonAnalytics::class)->fetchPostMetrics($postPlatform),
+            Platform::Telegram => app(TelegramAnalytics::class)->fetchPostMetrics($postPlatform),
             Platform::Instagram, Platform::InstagramFacebook => app(InstagramAnalytics::class)->fetchPostMetrics($postPlatform),
             Platform::Facebook => app(FacebookAnalytics::class)->fetchPostMetrics($postPlatform),
             Platform::Threads => app(ThreadsAnalytics::class)->fetchPostMetrics($postPlatform),
diff --git a/app/Services/Social/TelegramAnalytics.php b/app/Services/Social/TelegramAnalytics.php
new file mode 100644
index 00000000..1cf9f150
--- /dev/null
+++ b/app/Services/Social/TelegramAnalytics.php
@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Social;
+
+use App\Models\PostPlatform;
+use App\Models\SocialAccount;
+use Illuminate\Support\Facades\Http;
+
+class TelegramAnalytics
+{
+    /**
+     * Account-level metrics. The Bot API only exposes the subscriber count.
+     *
+     * @return array<int, array{label: string, value: int}>
+     */
+    public function getMetrics(SocialAccount $account): array
+    {
+        $token = (string) config('trypost.platforms.telegram.bot_token');
+        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
+        $chatId = data_get($account->meta, 'chat_id');
+
+        if ($token === '' || $chatId === null) {
+            return [];
+        }
+
+        $count = data_get(
+            Http::get("{$api}/bot{$token}/getChatMemberCount", ['chat_id' => $chatId])->json(),
+            'result',
+        );
+
+        if (! is_int($count)) {
+            return [];
+        }
+
+        return [
+            ['label' => __('analytics.metrics.subscribers'), 'value' => $count],
+        ];
+    }
+
+    /**
+     * Post-level metrics. Reaction counts are pushed by the webhook and stored
+     * on the post platform's meta (the Bot API offers no post views to bots).
+     *
+     * @return array<int, array{label: string, value: int}>
+     */
+    public function fetchPostMetrics(PostPlatform $postPlatform): array
+    {
+        $reactions = data_get($postPlatform->meta, 'reactions', []);
+
+        if (! is_array($reactions)) {
+            return [];
+        }
+
+        return array_values(array_map(fn (array $reaction): array => [
+            'label' => (string) data_get($reaction, 'type'),
+            'value' => (int) data_get($reaction, 'count'),
+        ], $reactions));
+    }
+}
diff --git a/lang/en/analytics.php b/lang/en/analytics.php
index a91ae0e8..ee6fbf22 100644
--- a/lang/en/analytics.php
+++ b/lang/en/analytics.php
@@ -13,6 +13,7 @@
         'bookmarks' => 'Bookmarks',
         'clicks' => 'Clicks',
         'comments' => 'Comments',
+        'custom_reaction' => 'Custom',
         'engagement' => 'Engagement',
         'favourites' => 'Favourites',
         'followers' => 'Followers',
@@ -42,6 +43,7 @@
         'retweets' => 'Retweets',
         'saves' => 'Saves',
         'shares' => 'Shares',
+        'subscribers' => 'Subscribers',
         'subscribers_gained' => 'Subscribers Gained',
         'subscribers_lost' => 'Subscribers Lost',
         'total_likes' => 'Total Likes',
diff --git a/lang/es/analytics.php b/lang/es/analytics.php
index d8a9d5f7..4f0a4ab0 100644
--- a/lang/es/analytics.php
+++ b/lang/es/analytics.php
@@ -13,6 +13,7 @@
         'bookmarks' => 'Guardados',
         'clicks' => 'Clics',
         'comments' => 'Comentarios',
+        'custom_reaction' => 'Personalizada',
         'engagement' => 'Engagement',
         'favourites' => 'Favoritos',
         'followers' => 'Seguidores',
@@ -42,6 +43,7 @@
         'retweets' => 'Retweets',
         'saves' => 'Guardados',
         'shares' => 'Compartidos',
+        'subscribers' => 'Suscriptores',
         'subscribers_gained' => 'Suscriptores Ganados',
         'subscribers_lost' => 'Suscriptores Perdidos',
         'total_likes' => 'Total de Me gusta',
diff --git a/lang/pt-BR/analytics.php b/lang/pt-BR/analytics.php
index 215139bb..95e2139d 100644
--- a/lang/pt-BR/analytics.php
+++ b/lang/pt-BR/analytics.php
@@ -13,6 +13,7 @@
         'bookmarks' => 'Salvos',
         'clicks' => 'Cliques',
         'comments' => 'Comentários',
+        'custom_reaction' => 'Personalizada',
         'engagement' => 'Engajamento',
         'favourites' => 'Favoritos',
         'followers' => 'Seguidores',
@@ -42,6 +43,7 @@
         'retweets' => 'Retweets',
         'saves' => 'Salvos',
         'shares' => 'Compartilhamentos',
+        'subscribers' => 'Inscritos',
         'subscribers_gained' => 'Inscritos Ganhos',
         'subscribers_lost' => 'Inscritos Perdidos',
         'total_likes' => 'Curtidas Totais',
diff --git a/resources/js/components/analytics/TelegramAnalytics.vue b/resources/js/components/analytics/TelegramAnalytics.vue
new file mode 100644
index 00000000..44994bff
--- /dev/null
+++ b/resources/js/components/analytics/TelegramAnalytics.vue
@@ -0,0 +1,57 @@
+<script setup lang="ts">
+import { useHttp } from '@inertiajs/vue3';
+import { trans } from 'laravel-vue-i18n';
+import { onMounted, ref, watch } from 'vue';
+
+import MetricsGrid from '@/components/analytics/MetricsGrid.vue';
+import { show as showAnalytics } from '@/routes/app/analytics';
+
+interface MetricItem {
+    label: string;
+    value: number;
+}
+
+const props = defineProps<{
+    accountId: string;
+}>();
+
+const metrics = ref<MetricItem[]>([]);
+const isLoading = ref(false);
+
+const http = useHttp<Record<string, never>, { metrics: MetricItem[] }>({});
+
+const fetchMetrics = async () => {
+    isLoading.value = true;
+    metrics.value = [];
+
+    try {
+        const response = await http.get(showAnalytics.url(props.accountId));
+        metrics.value = response?.metrics || [];
+    } catch {
+        metrics.value = [];
+    } finally {
+        isLoading.value = false;
+    }
+};
+
+watch(
+    () => props.accountId,
+    () => {
+        fetchMetrics();
+    },
+);
+
+onMounted(() => {
+    fetchMetrics();
+});
+
+defineExpose({ supportsDateRange: false });
+</script>
+
+<template>
+    <MetricsGrid
+        :metrics="metrics"
+        :loading="isLoading"
+        :empty-label="trans('analytics.no_data')"
+    />
+</template>
diff --git a/resources/js/pages/analytics/Index.vue b/resources/js/pages/analytics/Index.vue
index 8b7f9408..8c4b009b 100644
--- a/resources/js/pages/analytics/Index.vue
+++ b/resources/js/pages/analytics/Index.vue
@@ -8,6 +8,7 @@ import FacebookAnalytics from '@/components/analytics/FacebookAnalytics.vue';
 import InstagramAnalytics from '@/components/analytics/InstagramAnalytics.vue';
 import LinkedInPageAnalytics from '@/components/analytics/LinkedInPageAnalytics.vue';
 import PinterestAnalytics from '@/components/analytics/PinterestAnalytics.vue';
+import TelegramAnalytics from '@/components/analytics/TelegramAnalytics.vue';
 import ThreadsAnalytics from '@/components/analytics/ThreadsAnalytics.vue';
 import TikTokAnalytics from '@/components/analytics/TikTokAnalytics.vue';
 import type { AnalyticsAccount } from '@/components/analytics/types';
@@ -115,6 +116,11 @@ const platformSupportsDateRange = computed(() => {
                 :date-range="dateRange"
             />
 
+            <TelegramAnalytics
+                v-else-if="selectedAccount?.platform === 'telegram'"
+                :account-id="selectedAccountId"
+            />
+
             <div v-else class="flex flex-1 items-center justify-center text-sm font-medium text-foreground/60">
                 {{ $t('analytics.no_data') }}
             </div>
diff --git a/tests/Feature/Actions/SocialAccount/RegisterTelegramWebhookTest.php b/tests/Feature/Actions/SocialAccount/RegisterTelegramWebhookTest.php
index 4bfea510..ef47b125 100644
--- a/tests/Feature/Actions/SocialAccount/RegisterTelegramWebhookTest.php
+++ b/tests/Feature/Actions/SocialAccount/RegisterTelegramWebhookTest.php
@@ -25,7 +25,7 @@
         return str_contains($request->url(), '/botTESTTOKEN/setWebhook')
             && $request['url'] === route('telegram.webhook')
             && $request['secret_token'] === 'shh-secret'
-            && $request['allowed_updates'] === ['message', 'channel_post'];
+            && $request['allowed_updates'] === ['message', 'channel_post', 'message_reaction_count'];
     });
 });
 
diff --git a/tests/Feature/Services/Social/TelegramAnalyticsTest.php b/tests/Feature/Services/Social/TelegramAnalyticsTest.php
new file mode 100644
index 00000000..cfd215a1
--- /dev/null
+++ b/tests/Feature/Services/Social/TelegramAnalyticsTest.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Enums\SocialAccount\Platform;
+use App\Models\PostPlatform;
+use App\Models\SocialAccount;
+use App\Services\Social\TelegramAnalytics;
+use Illuminate\Support\Facades\Http;
+
+beforeEach(function () {
+    config(['trypost.platforms.telegram.bot_token' => 'TESTTOKEN']);
+});
+
+it('returns the channel subscriber count as an account metric', function () {
+    $account = SocialAccount::factory()->telegram()->create();
+
+    Http::fake([
+        '*/botTESTTOKEN/getChatMemberCount*' => Http::response(['ok' => true, 'result' => 1234], 200),
+    ]);
+
+    expect(app(TelegramAnalytics::class)->getMetrics($account))
+        ->toBe([['label' => 'Subscribers', 'value' => 1234]]);
+});
+
+it('returns no account metrics when the member count call fails', function () {
+    $account = SocialAccount::factory()->telegram()->create();
+
+    Http::fake([
+        '*/botTESTTOKEN/getChatMemberCount*' => Http::response(['ok' => false], 400),
+    ]);
+
+    expect(app(TelegramAnalytics::class)->getMetrics($account))->toBe([]);
+});
+
+it('maps stored reactions to post metrics', function () {
+    $postPlatform = PostPlatform::factory()->create([
+        'platform' => Platform::Telegram,
+        'meta' => ['reactions' => [['type' => '👍', 'count' => 12], ['type' => '❤️', 'count' => 5]]],
+    ]);
+
+    expect(app(TelegramAnalytics::class)->fetchPostMetrics($postPlatform))
+        ->toBe([['label' => '👍', 'value' => 12], ['label' => '❤️', 'value' => 5]]);
+});
+
+it('returns no post metrics when there are no reactions yet', function () {
+    $postPlatform = PostPlatform::factory()->create([
+        'platform' => Platform::Telegram,
+        'meta' => [],
+    ]);
+
+    expect(app(TelegramAnalytics::class)->fetchPostMetrics($postPlatform))->toBe([]);
+});
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index 4ba127aa..bb80d30b 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -5,6 +5,8 @@
 use App\Enums\SocialAccount\Platform;
 use App\Enums\UserWorkspace\Role;
 use App\Events\TelegramChannelConnected;
+use App\Models\Post;
+use App\Models\PostPlatform;
 use App\Models\SocialAccount;
 use App\Models\User;
 use App\Models\Workspace;
@@ -172,6 +174,38 @@ function telegramUpdate(string $code, array $chat = []): array
     )->toBeTrue();
 });
 
+it('stores reaction counts on the matching post from a reaction update', function () {
+    $account = SocialAccount::factory()->telegram()->create(['workspace_id' => $this->workspace->id]);
+    $post = Post::factory()->create([
+        'workspace_id' => $this->workspace->id,
+        'user_id' => $this->user->id,
+    ]);
+    $postPlatform = PostPlatform::factory()->published()->create([
+        'post_id' => $post->id,
+        'social_account_id' => $account->id,
+        'platform' => Platform::Telegram,
+        'platform_post_id' => '42',
+    ]);
+
+    $update = [
+        'message_reaction_count' => [
+            'chat' => ['id' => -1001234567890],
+            'message_id' => 42,
+            'reactions' => [
+                ['type' => ['type' => 'emoji', 'emoji' => '👍'], 'total_count' => 12],
+                ['type' => ['type' => 'emoji', 'emoji' => '❤️'], 'total_count' => 5],
+            ],
+        ],
+    ];
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), $update)
+        ->assertNoContent();
+
+    expect(data_get($postPlatform->fresh()->meta, 'reactions'))
+        ->toBe([['type' => '👍', 'count' => 12], ['type' => '❤️', 'count' => 5]]);
+});
+
 it('rejects the webhook without the secret token', function () {
     $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 

From c719480cf1b7d72072b71170b6cf739dc98a1464 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 11:37:04 -0300
Subject: [PATCH 25/35] Harden Telegram reactions/analytics from PR review; add
 scoping + edge-case tests

---
 .../SocialAccount/StoreTelegramReactions.php  |  4 +-
 app/Services/Social/TelegramAnalytics.php     | 13 ++--
 resources/js/pages/analytics/Index.vue        | 35 +++++++--
 .../Feature/Social/TelegramConnectionTest.php | 72 +++++++++++++++++++
 4 files changed, 113 insertions(+), 11 deletions(-)

diff --git a/app/Actions/SocialAccount/StoreTelegramReactions.php b/app/Actions/SocialAccount/StoreTelegramReactions.php
index 83998c5d..2b2f1be5 100644
--- a/app/Actions/SocialAccount/StoreTelegramReactions.php
+++ b/app/Actions/SocialAccount/StoreTelegramReactions.php
@@ -35,10 +35,12 @@ public static function execute(array $update): void
             return;
         }
 
+        $rawReactions = data_get($update, 'reactions');
+
         $reactions = array_values(array_map(fn (array $reaction): array => [
             'type' => (string) (data_get($reaction, 'type.emoji') ?? __('analytics.metrics.custom_reaction')),
             'count' => (int) data_get($reaction, 'total_count'),
-        ], data_get($update, 'reactions', [])));
+        ], is_array($rawReactions) ? $rawReactions : []));
 
         $postPlatform->update(['meta' => [...$postPlatform->meta ?? [], 'reactions' => $reactions]]);
 
diff --git a/app/Services/Social/TelegramAnalytics.php b/app/Services/Social/TelegramAnalytics.php
index 1cf9f150..196809e0 100644
--- a/app/Services/Social/TelegramAnalytics.php
+++ b/app/Services/Social/TelegramAnalytics.php
@@ -7,6 +7,7 @@
 use App\Models\PostPlatform;
 use App\Models\SocialAccount;
 use Illuminate\Support\Facades\Http;
+use Throwable;
 
 class TelegramAnalytics
 {
@@ -25,10 +26,14 @@ public function getMetrics(SocialAccount $account): array
             return [];
         }
 
-        $count = data_get(
-            Http::get("{$api}/bot{$token}/getChatMemberCount", ['chat_id' => $chatId])->json(),
-            'result',
-        );
+        try {
+            $count = data_get(
+                Http::get("{$api}/bot{$token}/getChatMemberCount", ['chat_id' => $chatId])->json(),
+                'result',
+            );
+        } catch (Throwable) {
+            return [];
+        }
 
         if (! is_int($count)) {
             return [];
diff --git a/resources/js/pages/analytics/Index.vue b/resources/js/pages/analytics/Index.vue
index 8c4b009b..fa058770 100644
--- a/resources/js/pages/analytics/Index.vue
+++ b/resources/js/pages/analytics/Index.vue
@@ -36,7 +36,16 @@ const selectedAccount = computed(() =>
 
 const platformSupportsDateRange = computed(() => {
     if (!selectedAccount.value) return false;
-    return ['instagram', 'instagram-facebook', 'facebook', 'youtube', 'pinterest', 'threads', 'x', 'linkedin-page'].includes(selectedAccount.value.platform);
+    return [
+        'instagram',
+        'instagram-facebook',
+        'facebook',
+        'youtube',
+        'pinterest',
+        'threads',
+        'x',
+        'linkedin-page',
+    ].includes(selectedAccount.value.platform);
 });
 </script>
 
@@ -44,7 +53,9 @@ const platformSupportsDateRange = computed(() => {
     <AppLayout>
         <Head :title="trans('sidebar.analytics')" />
 
-        <div class="mx-auto flex h-full w-full max-w-6xl flex-col gap-6 px-6 py-8">
+        <div
+            class="mx-auto flex h-full w-full max-w-6xl flex-col gap-6 px-6 py-8"
+        >
             <div class="flex flex-wrap items-center justify-between gap-3">
                 <PageHeader :title="$t('sidebar.analytics')" />
                 <div class="flex flex-wrap items-center gap-3">
@@ -61,11 +72,17 @@ const platformSupportsDateRange = computed(() => {
                 </div>
             </div>
 
-            <div v-if="accounts.length === 0" class="flex flex-1 items-center justify-center text-sm font-medium text-foreground/60">
+            <div
+                v-if="accounts.length === 0"
+                class="flex flex-1 items-center justify-center text-sm font-medium text-foreground/60"
+            >
                 {{ $t('analytics.no_accounts') }}
             </div>
 
-            <div v-else-if="!selectedAccountId" class="flex flex-1 items-center justify-center text-sm font-medium text-foreground/60">
+            <div
+                v-else-if="!selectedAccountId"
+                class="flex flex-1 items-center justify-center text-sm font-medium text-foreground/60"
+            >
                 {{ $t('analytics.select_account') }}
             </div>
 
@@ -75,7 +92,10 @@ const platformSupportsDateRange = computed(() => {
             />
 
             <InstagramAnalytics
-                v-else-if="selectedAccount?.platform === 'instagram' || selectedAccount?.platform === 'instagram-facebook'"
+                v-else-if="
+                    selectedAccount?.platform === 'instagram' ||
+                    selectedAccount?.platform === 'instagram-facebook'
+                "
                 :account-id="selectedAccountId"
                 :date-range="dateRange"
             />
@@ -121,7 +141,10 @@ const platformSupportsDateRange = computed(() => {
                 :account-id="selectedAccountId"
             />
 
-            <div v-else class="flex flex-1 items-center justify-center text-sm font-medium text-foreground/60">
+            <div
+                v-else
+                class="flex flex-1 items-center justify-center text-sm font-medium text-foreground/60"
+            >
                 {{ $t('analytics.no_data') }}
             </div>
         </div>
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index bb80d30b..767f4375 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -206,6 +206,78 @@ function telegramUpdate(string $code, array $chat = []): array
         ->toBe([['type' => '👍', 'count' => 12], ['type' => '❤️', 'count' => 5]]);
 });
 
+it('does not store reactions on a post from a different channel with the same message id', function () {
+    $otherAccount = SocialAccount::factory()->telegram()->create([
+        'workspace_id' => $this->workspace->id,
+        'platform_user_id' => '-1009999999999',
+        'meta' => ['chat_id' => '-1009999999999', 'username' => 'other', 'type' => 'channel'],
+    ]);
+    $post = Post::factory()->create(['workspace_id' => $this->workspace->id, 'user_id' => $this->user->id]);
+    $postPlatform = PostPlatform::factory()->published()->create([
+        'post_id' => $post->id,
+        'social_account_id' => $otherAccount->id,
+        'platform' => Platform::Telegram,
+        'platform_post_id' => '42',
+    ]);
+
+    $update = [
+        'message_reaction_count' => [
+            'chat' => ['id' => -1001234567890],
+            'message_id' => 42,
+            'reactions' => [['type' => ['type' => 'emoji', 'emoji' => '👍'], 'total_count' => 9]],
+        ],
+    ];
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), $update)
+        ->assertNoContent();
+
+    expect(data_get($postPlatform->fresh()->meta, 'reactions'))->toBeNull();
+});
+
+it('labels custom emoji reactions with a fallback', function () {
+    $account = SocialAccount::factory()->telegram()->create(['workspace_id' => $this->workspace->id]);
+    $post = Post::factory()->create(['workspace_id' => $this->workspace->id, 'user_id' => $this->user->id]);
+    $postPlatform = PostPlatform::factory()->published()->create([
+        'post_id' => $post->id,
+        'social_account_id' => $account->id,
+        'platform' => Platform::Telegram,
+        'platform_post_id' => '77',
+    ]);
+
+    $update = [
+        'message_reaction_count' => [
+            'chat' => ['id' => -1001234567890],
+            'message_id' => 77,
+            'reactions' => [['type' => ['type' => 'custom_emoji', 'custom_emoji_id' => '555'], 'total_count' => 3]],
+        ],
+    ];
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), $update)
+        ->assertNoContent();
+
+    expect(data_get($postPlatform->fresh()->meta, 'reactions'))
+        ->toBe([['type' => 'Custom', 'count' => 3]]);
+});
+
+it('connects without an avatar when the channel has no photo', function () {
+    Http::fake([
+        '*/botTESTTOKEN/getChat*' => Http::response(['ok' => true, 'result' => []], 200),
+    ]);
+
+    $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
+
+    $this->withHeader('X-Telegram-Bot-Api-Secret-Token', 'shh-secret')
+        ->postJson(route('telegram.webhook'), telegramUpdate($code))
+        ->assertNoContent();
+
+    $account = SocialAccount::where('platform', Platform::Telegram)->first();
+
+    expect($account)->not->toBeNull();
+    expect($account->getRawOriginal('avatar_url'))->toBeNull();
+});
+
 it('rejects the webhook without the secret token', function () {
     $code = TelegramConnectCode::issue($this->workspace->id, now()->addMinutes(15));
 

From e907ad087f2293c06755e5077bb37d870007c017 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 11:40:55 -0300
Subject: [PATCH 26/35] Lock Telegram @mention passthrough in sanitizer test

---
 tests/Feature/Services/Social/ContentSanitizerTest.php | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/tests/Feature/Services/Social/ContentSanitizerTest.php b/tests/Feature/Services/Social/ContentSanitizerTest.php
index 4acbc3fb..4a0e607a 100644
--- a/tests/Feature/Services/Social/ContentSanitizerTest.php
+++ b/tests/Feature/Services/Social/ContentSanitizerTest.php
@@ -100,3 +100,9 @@
     $result = $sanitizer->sanitize('<p>see <a>bare</a> and <a href="https://x.com">link</a></p>', Platform::Telegram);
     expect($result)->toBe('see bare and <a href="https://x.com">link</a>');
 });
+
+test('it preserves @username mentions as plain text for telegram', function () {
+    $sanitizer = new ContentSanitizer;
+    $result = $sanitizer->sanitize('<p>Hey @durov and @TryPostBot</p>', Platform::Telegram);
+    expect($result)->toBe('Hey @durov and @TryPostBot');
+});

From b6a3cb886c2cbef7a569e5a2b6e0fccd0d423240 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 12:41:19 -0300
Subject: [PATCH 27/35] Centralize Telegram Bot API URL/token construction in a
 TelegramApi helper

---
 .../SocialAccount/ConnectTelegramChannel.php  | 12 +++--
 .../SocialAccount/RegisterTelegramWebhook.php |  7 ++-
 app/Services/Social/ConnectionVerifier.php    |  5 +--
 app/Services/Social/TelegramAnalytics.php     |  6 +--
 app/Services/Social/TelegramApi.php           | 44 +++++++++++++++++++
 app/Services/Social/TelegramPublisher.php     |  5 +--
 .../Unit/Services/Social/TelegramApiTest.php  | 29 ++++++++++++
 7 files changed, 85 insertions(+), 23 deletions(-)
 create mode 100644 app/Services/Social/TelegramApi.php
 create mode 100644 tests/Unit/Services/Social/TelegramApiTest.php

diff --git a/app/Actions/SocialAccount/ConnectTelegramChannel.php b/app/Actions/SocialAccount/ConnectTelegramChannel.php
index 45743922..68d945be 100644
--- a/app/Actions/SocialAccount/ConnectTelegramChannel.php
+++ b/app/Actions/SocialAccount/ConnectTelegramChannel.php
@@ -10,6 +10,7 @@
 use App\Features\SocialAccountLimit;
 use App\Models\SocialAccount;
 use App\Models\Workspace;
+use App\Services\Social\TelegramApi;
 use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\Http;
 use Laravel\Pennant\Feature;
@@ -79,27 +80,24 @@ public static function execute(Workspace $workspace, array $chat, string $nonce)
      */
     private static function fetchChannelAvatar(string $chatId): ?string
     {
-        $token = (string) config('trypost.platforms.telegram.bot_token');
-        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
-
-        if ($token === '') {
+        if (TelegramApi::token() === '') {
             return null;
         }
 
         try {
-            $fileId = data_get(Http::get("{$api}/bot{$token}/getChat", ['chat_id' => $chatId])->json(), 'result.photo.big_file_id');
+            $fileId = data_get(Http::get(TelegramApi::endpoint('getChat'), ['chat_id' => $chatId])->json(), 'result.photo.big_file_id');
 
             if (! is_string($fileId)) {
                 return null;
             }
 
-            $filePath = data_get(Http::get("{$api}/bot{$token}/getFile", ['file_id' => $fileId])->json(), 'result.file_path');
+            $filePath = data_get(Http::get(TelegramApi::endpoint('getFile'), ['file_id' => $fileId])->json(), 'result.file_path');
 
             if (! is_string($filePath)) {
                 return null;
             }
 
-            return uploadFromUrl("{$api}/file/bot{$token}/{$filePath}");
+            return uploadFromUrl(TelegramApi::fileUrl($filePath));
         } catch (Throwable) {
             return null;
         }
diff --git a/app/Actions/SocialAccount/RegisterTelegramWebhook.php b/app/Actions/SocialAccount/RegisterTelegramWebhook.php
index 58f42dda..fbbd6206 100644
--- a/app/Actions/SocialAccount/RegisterTelegramWebhook.php
+++ b/app/Actions/SocialAccount/RegisterTelegramWebhook.php
@@ -4,6 +4,7 @@
 
 namespace App\Actions\SocialAccount;
 
+use App\Services\Social\TelegramApi;
 use Illuminate\Support\Facades\Http;
 use InvalidArgumentException;
 use RuntimeException;
@@ -20,17 +21,15 @@ class RegisterTelegramWebhook
      */
     public static function execute(): string
     {
-        $token = (string) config('trypost.platforms.telegram.bot_token');
-        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
         $secret = (string) config('trypost.platforms.telegram.webhook_secret');
 
-        if ($token === '' || $secret === '') {
+        if (TelegramApi::token() === '' || $secret === '') {
             throw new InvalidArgumentException('TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET must both be set.');
         }
 
         $url = route('telegram.webhook');
 
-        $response = Http::post("{$api}/bot{$token}/setWebhook", [
+        $response = Http::post(TelegramApi::endpoint('setWebhook'), [
             'url' => $url,
             'secret_token' => $secret,
             'allowed_updates' => ['message', 'channel_post', 'message_reaction_count'],
diff --git a/app/Services/Social/ConnectionVerifier.php b/app/Services/Social/ConnectionVerifier.php
index 4fb3da56..400d079e 100644
--- a/app/Services/Social/ConnectionVerifier.php
+++ b/app/Services/Social/ConnectionVerifier.php
@@ -507,11 +507,8 @@ private function verifyBluesky(SocialAccount $account): bool
 
     private function verifyTelegram(SocialAccount $account): bool
     {
-        $token = (string) config('trypost.platforms.telegram.bot_token');
-        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
-
         // getChat succeeds only while the bot can still reach the chat.
-        $response = Http::get("{$api}/bot{$token}/getChat", [
+        $response = Http::get(TelegramApi::endpoint('getChat'), [
             'chat_id' => data_get($account->meta, 'chat_id'),
         ]);
 
diff --git a/app/Services/Social/TelegramAnalytics.php b/app/Services/Social/TelegramAnalytics.php
index 196809e0..35d5a0d4 100644
--- a/app/Services/Social/TelegramAnalytics.php
+++ b/app/Services/Social/TelegramAnalytics.php
@@ -18,17 +18,15 @@ class TelegramAnalytics
      */
     public function getMetrics(SocialAccount $account): array
     {
-        $token = (string) config('trypost.platforms.telegram.bot_token');
-        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
         $chatId = data_get($account->meta, 'chat_id');
 
-        if ($token === '' || $chatId === null) {
+        if (TelegramApi::token() === '' || $chatId === null) {
             return [];
         }
 
         try {
             $count = data_get(
-                Http::get("{$api}/bot{$token}/getChatMemberCount", ['chat_id' => $chatId])->json(),
+                Http::get(TelegramApi::endpoint('getChatMemberCount'), ['chat_id' => $chatId])->json(),
                 'result',
             );
         } catch (Throwable) {
diff --git a/app/Services/Social/TelegramApi.php b/app/Services/Social/TelegramApi.php
new file mode 100644
index 00000000..1d9d0dd5
--- /dev/null
+++ b/app/Services/Social/TelegramApi.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Social;
+
+/**
+ * Builds Telegram Bot API URLs from the configured token + host, so the
+ * `bot<token>/<method>` shape and config keys live in one place.
+ */
+class TelegramApi
+{
+    public static function token(): string
+    {
+        return (string) config('trypost.platforms.telegram.bot_token');
+    }
+
+    /**
+     * Endpoint for a Bot API method, e.g. `https://api.telegram.org/bot<token>/sendMessage`.
+     */
+    public static function endpoint(string $method): string
+    {
+        $base = self::baseUrl();
+        $token = self::token();
+
+        return "{$base}/bot{$token}/{$method}";
+    }
+
+    /**
+     * Download URL for a file path returned by `getFile`.
+     */
+    public static function fileUrl(string $path): string
+    {
+        $base = self::baseUrl();
+        $token = self::token();
+
+        return "{$base}/file/bot{$token}/{$path}";
+    }
+
+    private static function baseUrl(): string
+    {
+        return rtrim((string) config('trypost.platforms.telegram.api'), '/');
+    }
+}
diff --git a/app/Services/Social/TelegramPublisher.php b/app/Services/Social/TelegramPublisher.php
index 8772fda5..073471f4 100644
--- a/app/Services/Social/TelegramPublisher.php
+++ b/app/Services/Social/TelegramPublisher.php
@@ -141,10 +141,7 @@ private function telegramMedia(MediaItem $media): array
 
     private function call(string $method, array $payload): Response
     {
-        $token = (string) config('trypost.platforms.telegram.bot_token');
-        $api = rtrim((string) config('trypost.platforms.telegram.api'), '/');
-
-        $response = $this->socialHttp()->post("{$api}/bot{$token}/{$method}", $payload);
+        $response = $this->socialHttp()->post(TelegramApi::endpoint($method), $payload);
 
         if ($response->failed() || data_get($response->json(), 'ok') !== true) {
             $this->handleApiError($response);
diff --git a/tests/Unit/Services/Social/TelegramApiTest.php b/tests/Unit/Services/Social/TelegramApiTest.php
new file mode 100644
index 00000000..bcab8ef5
--- /dev/null
+++ b/tests/Unit/Services/Social/TelegramApiTest.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Services\Social\TelegramApi;
+
+beforeEach(function () {
+    config([
+        'trypost.platforms.telegram.bot_token' => 'TESTTOKEN',
+        'trypost.platforms.telegram.api' => 'https://api.telegram.org',
+    ]);
+});
+
+it('builds a method endpoint from the token and host', function () {
+    expect(TelegramApi::endpoint('sendMessage'))
+        ->toBe('https://api.telegram.org/botTESTTOKEN/sendMessage');
+});
+
+it('builds a file download url', function () {
+    expect(TelegramApi::fileUrl('photos/file_1.jpg'))
+        ->toBe('https://api.telegram.org/file/botTESTTOKEN/photos/file_1.jpg');
+});
+
+it('trims a trailing slash from the configured host', function () {
+    config(['trypost.platforms.telegram.api' => 'https://api.telegram.org/']);
+
+    expect(TelegramApi::endpoint('getChat'))
+        ->toBe('https://api.telegram.org/botTESTTOKEN/getChat');
+});

From 80b68088a05d0b0b1b1053263204a50a4a4a6acd Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 13:23:05 -0300
Subject: [PATCH 28/35] Type Telegram media kinds with a TelegramMediaType enum

---
 app/Services/Social/TelegramMediaType.php | 39 +++++++++++++++++++++++
 app/Services/Social/TelegramPublisher.php | 26 +++++----------
 2 files changed, 47 insertions(+), 18 deletions(-)
 create mode 100644 app/Services/Social/TelegramMediaType.php

diff --git a/app/Services/Social/TelegramMediaType.php b/app/Services/Social/TelegramMediaType.php
new file mode 100644
index 00000000..b4f19211
--- /dev/null
+++ b/app/Services/Social/TelegramMediaType.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Social;
+
+use App\DataTransferObjects\MediaItem;
+
+/**
+ * Telegram's media kinds, as used both in the `sendMediaGroup` `type` field and
+ * to pick the matching single-media Bot API method.
+ */
+enum TelegramMediaType: string
+{
+    case Photo = 'photo';
+    case Video = 'video';
+    case Document = 'document';
+
+    public static function for(MediaItem $media): self
+    {
+        return match (true) {
+            $media->isImage() => self::Photo,
+            $media->isVideo() => self::Video,
+            default => self::Document,
+        };
+    }
+
+    /**
+     * The Bot API method that sends a single media of this type.
+     */
+    public function sendMethod(): string
+    {
+        return match ($this) {
+            self::Photo => 'sendPhoto',
+            self::Video => 'sendVideo',
+            self::Document => 'sendDocument',
+        };
+    }
+}
diff --git a/app/Services/Social/TelegramPublisher.php b/app/Services/Social/TelegramPublisher.php
index 073471f4..997d1fb8 100644
--- a/app/Services/Social/TelegramPublisher.php
+++ b/app/Services/Social/TelegramPublisher.php
@@ -79,19 +79,15 @@ private function sendWithMedia(string $chatId, string $content, Collection $medi
     }
 
     /**
-     * @param  array{type: string, url: string}  $item
+     * @param  array{type: TelegramMediaType, url: string}  $item
      */
     private function sendSingleMedia(string $chatId, array $item, string $caption): int
     {
-        $method = match ($item['type']) {
-            'photo' => 'sendPhoto',
-            'video' => 'sendVideo',
-            default => 'sendDocument',
-        };
+        $type = $item['type'];
 
-        $response = $this->call($method, [
+        $response = $this->call($type->sendMethod(), [
             'chat_id' => $chatId,
-            $item['type'] => $item['url'],
+            $type->value => $item['url'],
             'caption' => $caption,
             'parse_mode' => 'HTML',
         ]);
@@ -100,14 +96,14 @@ private function sendSingleMedia(string $chatId, array $item, string $caption):
     }
 
     /**
-     * @param  array<int, array{type: string, url: string}>  $items
+     * @param  array<int, array{type: TelegramMediaType, url: string}>  $items
      */
     private function sendMediaGroup(string $chatId, array $items, string $caption): int
     {
         $group = [];
 
         foreach ($items as $index => $item) {
-            $entry = ['type' => $item['type'], 'media' => $item['url']];
+            $entry = ['type' => $item['type']->value, 'media' => $item['url']];
 
             if ($index === 0 && $caption !== '') {
                 $entry['caption'] = $caption;
@@ -126,17 +122,11 @@ private function sendMediaGroup(string $chatId, array $items, string $caption):
     }
 
     /**
-     * @return array{type: string, url: string}
+     * @return array{type: TelegramMediaType, url: string}
      */
     private function telegramMedia(MediaItem $media): array
     {
-        $type = match (true) {
-            $media->isImage() => 'photo',
-            $media->isVideo() => 'video',
-            default => 'document',
-        };
-
-        return ['type' => $type, 'url' => $media->url];
+        return ['type' => TelegramMediaType::for($media), 'url' => $media->url];
     }
 
     private function call(string $method, array $payload): Response

From b9fa8be513a72fb74e36f7730cad38bc190652e1 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 13:32:03 -0300
Subject: [PATCH 29/35] Group Telegram service classes under
 Services/Social/Telegram

---
 app/Actions/SocialAccount/ConnectTelegramChannel.php        | 2 +-
 app/Actions/SocialAccount/RegisterTelegramWebhook.php       | 2 +-
 app/Http/Controllers/App/AnalyticsController.php            | 2 +-
 app/Http/Controllers/Auth/TelegramController.php            | 2 +-
 app/Http/Controllers/Webhooks/TelegramWebhookController.php | 2 +-
 app/Jobs/PublishToSocialPlatform.php                        | 2 +-
 app/Services/Post/PostMetricsFetcher.php                    | 2 +-
 app/Services/Social/ConnectionVerifier.php                  | 1 +
 app/Services/Social/{ => Telegram}/TelegramAnalytics.php    | 2 +-
 app/Services/Social/{ => Telegram}/TelegramApi.php          | 2 +-
 app/Services/Social/{ => Telegram}/TelegramConnectCode.php  | 2 +-
 app/Services/Social/{ => Telegram}/TelegramMediaType.php    | 2 +-
 app/Services/Social/{ => Telegram}/TelegramPublisher.php    | 3 ++-
 tests/Feature/Services/Social/TelegramAnalyticsTest.php     | 2 +-
 tests/Feature/Services/Social/TelegramPublisherTest.php     | 2 +-
 tests/Feature/Social/TelegramConnectionTest.php             | 2 +-
 tests/Unit/Services/Social/TelegramApiTest.php              | 2 +-
 17 files changed, 18 insertions(+), 16 deletions(-)
 rename app/Services/Social/{ => Telegram}/TelegramAnalytics.php (97%)
 rename app/Services/Social/{ => Telegram}/TelegramApi.php (96%)
 rename app/Services/Social/{ => Telegram}/TelegramConnectCode.php (97%)
 rename app/Services/Social/{ => Telegram}/TelegramMediaType.php (95%)
 rename app/Services/Social/{ => Telegram}/TelegramPublisher.php (98%)

diff --git a/app/Actions/SocialAccount/ConnectTelegramChannel.php b/app/Actions/SocialAccount/ConnectTelegramChannel.php
index 68d945be..3743a113 100644
--- a/app/Actions/SocialAccount/ConnectTelegramChannel.php
+++ b/app/Actions/SocialAccount/ConnectTelegramChannel.php
@@ -10,7 +10,7 @@
 use App\Features\SocialAccountLimit;
 use App\Models\SocialAccount;
 use App\Models\Workspace;
-use App\Services\Social\TelegramApi;
+use App\Services\Social\Telegram\TelegramApi;
 use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\Http;
 use Laravel\Pennant\Feature;
diff --git a/app/Actions/SocialAccount/RegisterTelegramWebhook.php b/app/Actions/SocialAccount/RegisterTelegramWebhook.php
index fbbd6206..68d12ddc 100644
--- a/app/Actions/SocialAccount/RegisterTelegramWebhook.php
+++ b/app/Actions/SocialAccount/RegisterTelegramWebhook.php
@@ -4,7 +4,7 @@
 
 namespace App\Actions\SocialAccount;
 
-use App\Services\Social\TelegramApi;
+use App\Services\Social\Telegram\TelegramApi;
 use Illuminate\Support\Facades\Http;
 use InvalidArgumentException;
 use RuntimeException;
diff --git a/app/Http/Controllers/App/AnalyticsController.php b/app/Http/Controllers/App/AnalyticsController.php
index 084554b7..aee64aad 100644
--- a/app/Http/Controllers/App/AnalyticsController.php
+++ b/app/Http/Controllers/App/AnalyticsController.php
@@ -11,7 +11,7 @@
 use App\Services\Social\InstagramAnalytics;
 use App\Services\Social\LinkedInPageAnalytics;
 use App\Services\Social\PinterestAnalytics;
-use App\Services\Social\TelegramAnalytics;
+use App\Services\Social\Telegram\TelegramAnalytics;
 use App\Services\Social\ThreadsAnalytics;
 use App\Services\Social\TikTokAnalytics;
 use App\Services\Social\XAnalytics;
diff --git a/app/Http/Controllers/Auth/TelegramController.php b/app/Http/Controllers/Auth/TelegramController.php
index 329bf8a1..e24fa9cf 100644
--- a/app/Http/Controllers/Auth/TelegramController.php
+++ b/app/Http/Controllers/Auth/TelegramController.php
@@ -5,7 +5,7 @@
 namespace App\Http\Controllers\Auth;
 
 use App\Enums\SocialAccount\Platform as SocialPlatform;
-use App\Services\Social\TelegramConnectCode;
+use App\Services\Social\Telegram\TelegramConnectCode;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
diff --git a/app/Http/Controllers/Webhooks/TelegramWebhookController.php b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
index c823a072..d00e8717 100644
--- a/app/Http/Controllers/Webhooks/TelegramWebhookController.php
+++ b/app/Http/Controllers/Webhooks/TelegramWebhookController.php
@@ -8,7 +8,7 @@
 use App\Actions\SocialAccount\StoreTelegramReactions;
 use App\Http\Controllers\Controller;
 use App\Models\Workspace;
-use App\Services\Social\TelegramConnectCode;
+use App\Services\Social\Telegram\TelegramConnectCode;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
 use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
diff --git a/app/Jobs/PublishToSocialPlatform.php b/app/Jobs/PublishToSocialPlatform.php
index e163a90d..e4d494d1 100644
--- a/app/Jobs/PublishToSocialPlatform.php
+++ b/app/Jobs/PublishToSocialPlatform.php
@@ -25,7 +25,7 @@
 use App\Services\Social\LinkedInPublisher;
 use App\Services\Social\MastodonPublisher;
 use App\Services\Social\PinterestPublisher;
-use App\Services\Social\TelegramPublisher;
+use App\Services\Social\Telegram\TelegramPublisher;
 use App\Services\Social\ThreadsPublisher;
 use App\Services\Social\TikTokPublisher;
 use App\Services\Social\XPublisher;
diff --git a/app/Services/Post/PostMetricsFetcher.php b/app/Services/Post/PostMetricsFetcher.php
index 78a5bb55..de26dff9 100644
--- a/app/Services/Post/PostMetricsFetcher.php
+++ b/app/Services/Post/PostMetricsFetcher.php
@@ -13,7 +13,7 @@
 use App\Services\Social\LinkedInPageAnalytics;
 use App\Services\Social\MastodonAnalytics;
 use App\Services\Social\PinterestAnalytics;
-use App\Services\Social\TelegramAnalytics;
+use App\Services\Social\Telegram\TelegramAnalytics;
 use App\Services\Social\ThreadsAnalytics;
 use App\Services\Social\XAnalytics;
 use App\Services\Social\YouTubeAnalytics;
diff --git a/app/Services/Social/ConnectionVerifier.php b/app/Services/Social/ConnectionVerifier.php
index 400d079e..79ea1d50 100644
--- a/app/Services/Social/ConnectionVerifier.php
+++ b/app/Services/Social/ConnectionVerifier.php
@@ -8,6 +8,7 @@
 use App\Exceptions\PlatformUnavailableException;
 use App\Exceptions\TokenExpiredException;
 use App\Models\SocialAccount;
+use App\Services\Social\Telegram\TelegramApi;
 use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\Http;
 
diff --git a/app/Services/Social/TelegramAnalytics.php b/app/Services/Social/Telegram/TelegramAnalytics.php
similarity index 97%
rename from app/Services/Social/TelegramAnalytics.php
rename to app/Services/Social/Telegram/TelegramAnalytics.php
index 35d5a0d4..9e0cdd71 100644
--- a/app/Services/Social/TelegramAnalytics.php
+++ b/app/Services/Social/Telegram/TelegramAnalytics.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace App\Services\Social;
+namespace App\Services\Social\Telegram;
 
 use App\Models\PostPlatform;
 use App\Models\SocialAccount;
diff --git a/app/Services/Social/TelegramApi.php b/app/Services/Social/Telegram/TelegramApi.php
similarity index 96%
rename from app/Services/Social/TelegramApi.php
rename to app/Services/Social/Telegram/TelegramApi.php
index 1d9d0dd5..dbe5d412 100644
--- a/app/Services/Social/TelegramApi.php
+++ b/app/Services/Social/Telegram/TelegramApi.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace App\Services\Social;
+namespace App\Services\Social\Telegram;
 
 /**
  * Builds Telegram Bot API URLs from the configured token + host, so the
diff --git a/app/Services/Social/TelegramConnectCode.php b/app/Services/Social/Telegram/TelegramConnectCode.php
similarity index 97%
rename from app/Services/Social/TelegramConnectCode.php
rename to app/Services/Social/Telegram/TelegramConnectCode.php
index fe34e23b..c8ad463c 100644
--- a/app/Services/Social/TelegramConnectCode.php
+++ b/app/Services/Social/Telegram/TelegramConnectCode.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace App\Services\Social;
+namespace App\Services\Social\Telegram;
 
 use Carbon\CarbonInterface;
 use Illuminate\Contracts\Encryption\DecryptException;
diff --git a/app/Services/Social/TelegramMediaType.php b/app/Services/Social/Telegram/TelegramMediaType.php
similarity index 95%
rename from app/Services/Social/TelegramMediaType.php
rename to app/Services/Social/Telegram/TelegramMediaType.php
index b4f19211..d7b881b3 100644
--- a/app/Services/Social/TelegramMediaType.php
+++ b/app/Services/Social/Telegram/TelegramMediaType.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace App\Services\Social;
+namespace App\Services\Social\Telegram;
 
 use App\DataTransferObjects\MediaItem;
 
diff --git a/app/Services/Social/TelegramPublisher.php b/app/Services/Social/Telegram/TelegramPublisher.php
similarity index 98%
rename from app/Services/Social/TelegramPublisher.php
rename to app/Services/Social/Telegram/TelegramPublisher.php
index 997d1fb8..7a589da1 100644
--- a/app/Services/Social/TelegramPublisher.php
+++ b/app/Services/Social/Telegram/TelegramPublisher.php
@@ -2,13 +2,14 @@
 
 declare(strict_types=1);
 
-namespace App\Services\Social;
+namespace App\Services\Social\Telegram;
 
 use App\DataTransferObjects\MediaItem;
 use App\Exceptions\Social\TelegramPublishException;
 use App\Models\PostPlatform;
 use App\Models\SocialAccount;
 use App\Services\Social\Concerns\HasSocialHttpClient;
+use App\Services\Social\ContentSanitizer;
 use Illuminate\Http\Client\Response;
 use Illuminate\Support\Collection;
 
diff --git a/tests/Feature/Services/Social/TelegramAnalyticsTest.php b/tests/Feature/Services/Social/TelegramAnalyticsTest.php
index cfd215a1..e3fb8047 100644
--- a/tests/Feature/Services/Social/TelegramAnalyticsTest.php
+++ b/tests/Feature/Services/Social/TelegramAnalyticsTest.php
@@ -5,7 +5,7 @@
 use App\Enums\SocialAccount\Platform;
 use App\Models\PostPlatform;
 use App\Models\SocialAccount;
-use App\Services\Social\TelegramAnalytics;
+use App\Services\Social\Telegram\TelegramAnalytics;
 use Illuminate\Support\Facades\Http;
 
 beforeEach(function () {
diff --git a/tests/Feature/Services/Social/TelegramPublisherTest.php b/tests/Feature/Services/Social/TelegramPublisherTest.php
index 43be60be..7e50ceb5 100644
--- a/tests/Feature/Services/Social/TelegramPublisherTest.php
+++ b/tests/Feature/Services/Social/TelegramPublisherTest.php
@@ -10,7 +10,7 @@
 use App\Models\SocialAccount;
 use App\Models\User;
 use App\Models\Workspace;
-use App\Services\Social\TelegramPublisher;
+use App\Services\Social\Telegram\TelegramPublisher;
 use Illuminate\Support\Facades\Http;
 
 beforeEach(function () {
diff --git a/tests/Feature/Social/TelegramConnectionTest.php b/tests/Feature/Social/TelegramConnectionTest.php
index 767f4375..198b4ddf 100644
--- a/tests/Feature/Social/TelegramConnectionTest.php
+++ b/tests/Feature/Social/TelegramConnectionTest.php
@@ -11,7 +11,7 @@
 use App\Models\User;
 use App\Models\Workspace;
 use App\Services\Social\ConnectionVerifier;
-use App\Services\Social\TelegramConnectCode;
+use App\Services\Social\Telegram\TelegramConnectCode;
 use Illuminate\Support\Facades\Event;
 use Illuminate\Support\Facades\Http;
 use Illuminate\Support\Facades\Storage;
diff --git a/tests/Unit/Services/Social/TelegramApiTest.php b/tests/Unit/Services/Social/TelegramApiTest.php
index bcab8ef5..8ae35841 100644
--- a/tests/Unit/Services/Social/TelegramApiTest.php
+++ b/tests/Unit/Services/Social/TelegramApiTest.php
@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-use App\Services\Social\TelegramApi;
+use App\Services\Social\Telegram\TelegramApi;
 
 beforeEach(function () {
     config([

From fc1d51ca605eb4671afc5c376a4aeb74ae65f5ff Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 13:35:03 -0300
Subject: [PATCH 30/35] Telegram connect dialog: drop footer Close button,
 top-align icon

---
 lang/en/accounts.php                                     | 1 -
 lang/es/accounts.php                                     | 1 -
 lang/pt-BR/accounts.php                                  | 1 -
 .../js/components/accounts/TelegramConnectDialog.vue     | 9 +--------
 4 files changed, 1 insertion(+), 11 deletions(-)

diff --git a/lang/en/accounts.php b/lang/en/accounts.php
index c30ef3ff..71a3369f 100644
--- a/lang/en/accounts.php
+++ b/lang/en/accounts.php
@@ -97,7 +97,6 @@
         'new_code' => 'Generate a new code',
         'retry' => 'Try again',
         'error_generic' => 'Could not start the connection. Please try again.',
-        'close' => 'Close',
     ],
 
     'facebook' => [
diff --git a/lang/es/accounts.php b/lang/es/accounts.php
index 0a6fd872..4fe5eb1e 100644
--- a/lang/es/accounts.php
+++ b/lang/es/accounts.php
@@ -97,7 +97,6 @@
         'new_code' => 'Generar un nuevo código',
         'retry' => 'Reintentar',
         'error_generic' => 'No se pudo iniciar la conexión. Inténtalo de nuevo.',
-        'close' => 'Cerrar',
     ],
 
     'facebook' => [
diff --git a/lang/pt-BR/accounts.php b/lang/pt-BR/accounts.php
index bc103450..9323dc74 100644
--- a/lang/pt-BR/accounts.php
+++ b/lang/pt-BR/accounts.php
@@ -97,7 +97,6 @@
         'new_code' => 'Gerar um novo código',
         'retry' => 'Tentar novamente',
         'error_generic' => 'Não foi possível iniciar a conexão. Tente novamente.',
-        'close' => 'Fechar',
     ],
 
     'facebook' => [
diff --git a/resources/js/components/accounts/TelegramConnectDialog.vue b/resources/js/components/accounts/TelegramConnectDialog.vue
index ce84b8d6..7ec1425a 100644
--- a/resources/js/components/accounts/TelegramConnectDialog.vue
+++ b/resources/js/components/accounts/TelegramConnectDialog.vue
@@ -10,7 +10,6 @@ import {
     Dialog,
     DialogContent,
     DialogDescription,
-    DialogFooter,
     DialogHeader,
     DialogTitle,
 } from '@/components/ui/dialog';
@@ -123,7 +122,7 @@ onUnmounted(clearExpiry);
     <Dialog v-model:open="open">
         <DialogContent class="sm:max-w-lg">
             <DialogHeader>
-                <div class="flex items-center gap-3">
+                <div class="flex items-start gap-3">
                     <img
                         src="/images/accounts/telegram.png"
                         alt="Telegram"
@@ -239,12 +238,6 @@ onUnmounted(clearExpiry);
                     {{ $t('accounts.telegram.waiting') }}
                 </div>
             </div>
-
-            <DialogFooter>
-                <Button variant="outline" @click="open = false">{{
-                    $t('accounts.telegram.close')
-                }}</Button>
-            </DialogFooter>
         </DialogContent>
     </Dialog>
 </template>

From a5b33f5b0ae672cbffc6b21edc41a231b3bbb202 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 13:50:12 -0300
Subject: [PATCH 31/35] Show Telegram subscribers on post metrics; render
 reactions as compact pills

---
 .../Social/Telegram/TelegramAnalytics.php     | 20 +++++---
 .../components/posts/PostPlatformMetrics.vue  | 51 ++++++++++++++++---
 .../Services/Social/TelegramAnalyticsTest.php | 30 ++++++++++-
 3 files changed, 85 insertions(+), 16 deletions(-)

diff --git a/app/Services/Social/Telegram/TelegramAnalytics.php b/app/Services/Social/Telegram/TelegramAnalytics.php
index 9e0cdd71..c21d8075 100644
--- a/app/Services/Social/Telegram/TelegramAnalytics.php
+++ b/app/Services/Social/Telegram/TelegramAnalytics.php
@@ -46,19 +46,25 @@ public function getMetrics(SocialAccount $account): array
      * Post-level metrics. Reaction counts are pushed by the webhook and stored
      * on the post platform's meta (the Bot API offers no post views to bots).
      *
-     * @return array<int, array{label: string, value: int}>
+     * @return array<int, array{label: string, value: int, kind?: string}>
      */
     public function fetchPostMetrics(PostPlatform $postPlatform): array
     {
+        $account = $postPlatform->socialAccount;
+        $metrics = $account ? $this->getMetrics($account) : [];
+
         $reactions = data_get($postPlatform->meta, 'reactions', []);
 
-        if (! is_array($reactions)) {
-            return [];
+        if (is_array($reactions)) {
+            foreach ($reactions as $reaction) {
+                $metrics[] = [
+                    'label' => (string) data_get($reaction, 'type'),
+                    'value' => (int) data_get($reaction, 'count'),
+                    'kind' => 'reaction',
+                ];
+            }
         }
 
-        return array_values(array_map(fn (array $reaction): array => [
-            'label' => (string) data_get($reaction, 'type'),
-            'value' => (int) data_get($reaction, 'count'),
-        ], $reactions));
+        return $metrics;
     }
 }
diff --git a/resources/js/components/posts/PostPlatformMetrics.vue b/resources/js/components/posts/PostPlatformMetrics.vue
index 9fd89b2f..54ea70ba 100644
--- a/resources/js/components/posts/PostPlatformMetrics.vue
+++ b/resources/js/components/posts/PostPlatformMetrics.vue
@@ -8,6 +8,7 @@ import { metrics as metricsRoute } from '@/routes/app/posts/platforms';
 interface Metric {
     label: string;
     value: number;
+    kind?: string;
 }
 
 type MetricsResponse = Metric[] | { unsupported: true; reason: string };
@@ -22,10 +23,18 @@ const props = defineProps<Props>();
 const loading = ref(true);
 const metrics = ref<Metric[]>([]);
 
+const stats = computed(() =>
+    metrics.value.filter((m) => m.kind !== 'reaction'),
+);
+const reactions = computed(() =>
+    metrics.value.filter((m) => m.kind === 'reaction'),
+);
+
 const hasMetrics = computed(() => metrics.value.length > 0);
 
 const formatNumber = (n: number): string => {
-    if (n >= 1_000_000) return (n / 1_000_000).toFixed(1).replace(/\.0$/, '') + 'M';
+    if (n >= 1_000_000)
+        return (n / 1_000_000).toFixed(1).replace(/\.0$/, '') + 'M';
     if (n >= 1_000) return (n / 1_000).toFixed(1).replace(/\.0$/, '') + 'K';
     return n.toString();
 };
@@ -35,7 +44,10 @@ const http = useHttp<Record<string, never>, MetricsResponse>({});
 onMounted(async () => {
     try {
         const response = await http.get(
-            metricsRoute.url({ post: props.postId, postPlatform: props.postPlatformId }),
+            metricsRoute.url({
+                post: props.postId,
+                postPlatform: props.postPlatformId,
+            }),
         );
 
         if (Array.isArray(response)) {
@@ -61,20 +73,45 @@ onMounted(async () => {
 
     <!-- Loaded with data: full metrics block. -->
     <div v-else-if="hasMetrics" class="border-t px-4 py-3">
-        <div class="mb-2 flex items-center gap-1.5 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+        <div
+            class="mb-2 flex items-center gap-1.5 text-xs font-semibold tracking-wider text-muted-foreground uppercase"
+        >
             <IconChartBar class="h-3 w-3" />
             {{ $t('posts.show.metrics') }}
         </div>
-        <div class="grid grid-cols-3 gap-2">
+        <div v-if="stats.length > 0" class="grid grid-cols-3 gap-2">
             <div
-                v-for="metric in metrics"
+                v-for="metric in stats"
                 :key="metric.label"
                 class="rounded-md bg-muted/50 px-2.5 py-1.5"
             >
-                <p class="text-[10px] uppercase tracking-wider text-muted-foreground">{{ metric.label }}</p>
-                <p class="text-sm font-semibold tabular-nums">{{ formatNumber(metric.value) }}</p>
+                <p
+                    class="text-[10px] tracking-wider text-muted-foreground uppercase"
+                >
+                    {{ metric.label }}
+                </p>
+                <p class="text-sm font-semibold tabular-nums">
+                    {{ formatNumber(metric.value) }}
+                </p>
             </div>
         </div>
+
+        <div
+            v-if="reactions.length > 0"
+            class="flex flex-wrap gap-1.5"
+            :class="{ 'mt-2': stats.length > 0 }"
+        >
+            <span
+                v-for="reaction in reactions"
+                :key="reaction.label"
+                class="inline-flex items-center gap-1 rounded-full bg-muted/50 px-2 py-1 text-xs"
+            >
+                <span class="text-sm leading-none">{{ reaction.label }}</span>
+                <span class="font-semibold tabular-nums">{{
+                    formatNumber(reaction.value)
+                }}</span>
+            </span>
+        </div>
     </div>
 
     <!-- No data / unsupported: render nothing so the card stays clean. -->
diff --git a/tests/Feature/Services/Social/TelegramAnalyticsTest.php b/tests/Feature/Services/Social/TelegramAnalyticsTest.php
index e3fb8047..7ab63b7e 100644
--- a/tests/Feature/Services/Social/TelegramAnalyticsTest.php
+++ b/tests/Feature/Services/Social/TelegramAnalyticsTest.php
@@ -33,17 +33,43 @@
     expect(app(TelegramAnalytics::class)->getMetrics($account))->toBe([]);
 });
 
-it('maps stored reactions to post metrics', function () {
+it('maps stored reactions to post metrics, tagged as reactions', function () {
+    config(['trypost.platforms.telegram.bot_token' => '']); // skip the subscriber lookup
+
     $postPlatform = PostPlatform::factory()->create([
         'platform' => Platform::Telegram,
         'meta' => ['reactions' => [['type' => '👍', 'count' => 12], ['type' => '❤️', 'count' => 5]]],
     ]);
 
     expect(app(TelegramAnalytics::class)->fetchPostMetrics($postPlatform))
-        ->toBe([['label' => '👍', 'value' => 12], ['label' => '❤️', 'value' => 5]]);
+        ->toBe([
+            ['label' => '👍', 'value' => 12, 'kind' => 'reaction'],
+            ['label' => '❤️', 'value' => 5, 'kind' => 'reaction'],
+        ]);
+});
+
+it('includes the channel subscriber count alongside reactions', function () {
+    $account = SocialAccount::factory()->telegram()->create();
+    $postPlatform = PostPlatform::factory()->create([
+        'social_account_id' => $account->id,
+        'platform' => Platform::Telegram,
+        'meta' => ['reactions' => [['type' => '👍', 'count' => 3]]],
+    ]);
+
+    Http::fake([
+        '*/botTESTTOKEN/getChatMemberCount*' => Http::response(['ok' => true, 'result' => 50], 200),
+    ]);
+
+    expect(app(TelegramAnalytics::class)->fetchPostMetrics($postPlatform))
+        ->toBe([
+            ['label' => 'Subscribers', 'value' => 50],
+            ['label' => '👍', 'value' => 3, 'kind' => 'reaction'],
+        ]);
 });
 
 it('returns no post metrics when there are no reactions yet', function () {
+    config(['trypost.platforms.telegram.bot_token' => '']);
+
     $postPlatform = PostPlatform::factory()->create([
         'platform' => Platform::Telegram,
         'meta' => [],

From 548138f277e247cda70bfdba68cba5accccf558e Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 13:53:57 -0300
Subject: [PATCH 32/35] Render Telegram subscribers as an icon pill with
 divider before reactions

---
 .../Social/Telegram/TelegramAnalytics.php     |  4 +-
 .../components/posts/PostPlatformMetrics.vue  | 41 ++++++++++++++++---
 .../Services/Social/TelegramAnalyticsTest.php |  2 +-
 3 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/app/Services/Social/Telegram/TelegramAnalytics.php b/app/Services/Social/Telegram/TelegramAnalytics.php
index c21d8075..395f2e9a 100644
--- a/app/Services/Social/Telegram/TelegramAnalytics.php
+++ b/app/Services/Social/Telegram/TelegramAnalytics.php
@@ -51,7 +51,9 @@ public function getMetrics(SocialAccount $account): array
     public function fetchPostMetrics(PostPlatform $postPlatform): array
     {
         $account = $postPlatform->socialAccount;
-        $metrics = $account ? $this->getMetrics($account) : [];
+        $metrics = $account
+            ? array_map(fn (array $metric): array => [...$metric, 'kind' => 'subscribers'], $this->getMetrics($account))
+            : [];
 
         $reactions = data_get($postPlatform->meta, 'reactions', []);
 
diff --git a/resources/js/components/posts/PostPlatformMetrics.vue b/resources/js/components/posts/PostPlatformMetrics.vue
index 54ea70ba..65946d83 100644
--- a/resources/js/components/posts/PostPlatformMetrics.vue
+++ b/resources/js/components/posts/PostPlatformMetrics.vue
@@ -1,8 +1,14 @@
 <script setup lang="ts">
 import { useHttp } from '@inertiajs/vue3';
-import { IconChartBar, IconLoader2 } from '@tabler/icons-vue';
+import { IconChartBar, IconLoader2, IconUsers } from '@tabler/icons-vue';
 import { computed, onMounted, ref } from 'vue';
 
+import {
+    Tooltip,
+    TooltipContent,
+    TooltipProvider,
+    TooltipTrigger,
+} from '@/components/ui/tooltip';
 import { metrics as metricsRoute } from '@/routes/app/posts/platforms';
 
 interface Metric {
@@ -23,8 +29,9 @@ const props = defineProps<Props>();
 const loading = ref(true);
 const metrics = ref<Metric[]>([]);
 
-const stats = computed(() =>
-    metrics.value.filter((m) => m.kind !== 'reaction'),
+const stats = computed(() => metrics.value.filter((m) => !m.kind));
+const subscribers = computed(() =>
+    metrics.value.find((m) => m.kind === 'subscribers'),
 );
 const reactions = computed(() =>
     metrics.value.filter((m) => m.kind === 'reaction'),
@@ -97,10 +104,34 @@ onMounted(async () => {
         </div>
 
         <div
-            v-if="reactions.length > 0"
-            class="flex flex-wrap gap-1.5"
+            v-if="subscribers || reactions.length > 0"
+            class="flex flex-wrap items-center gap-1.5"
             :class="{ 'mt-2': stats.length > 0 }"
         >
+            <TooltipProvider v-if="subscribers">
+                <Tooltip>
+                    <TooltipTrigger as-child>
+                        <span
+                            class="inline-flex items-center gap-1 rounded-full bg-muted px-2 py-1 text-xs"
+                        >
+                            <IconUsers class="size-3.5 text-muted-foreground" />
+                            <span class="font-semibold tabular-nums">{{
+                                formatNumber(subscribers.value)
+                            }}</span>
+                        </span>
+                    </TooltipTrigger>
+                    <TooltipContent>
+                        <p>{{ subscribers.label }}</p>
+                    </TooltipContent>
+                </Tooltip>
+            </TooltipProvider>
+
+            <span
+                v-if="subscribers && reactions.length > 0"
+                class="mx-0.5 h-4 w-px bg-border"
+                aria-hidden="true"
+            />
+
             <span
                 v-for="reaction in reactions"
                 :key="reaction.label"
diff --git a/tests/Feature/Services/Social/TelegramAnalyticsTest.php b/tests/Feature/Services/Social/TelegramAnalyticsTest.php
index 7ab63b7e..275295a7 100644
--- a/tests/Feature/Services/Social/TelegramAnalyticsTest.php
+++ b/tests/Feature/Services/Social/TelegramAnalyticsTest.php
@@ -62,7 +62,7 @@
 
     expect(app(TelegramAnalytics::class)->fetchPostMetrics($postPlatform))
         ->toBe([
-            ['label' => 'Subscribers', 'value' => 50],
+            ['label' => 'Subscribers', 'value' => 50, 'kind' => 'subscribers'],
             ['label' => '👍', 'value' => 3, 'kind' => 'reaction'],
         ]);
 });

From 0c3c837bd3e6d35111feb3f26c8a70328ab01f64 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 13:58:14 -0300
Subject: [PATCH 33/35] Polish Telegram preview: simulate channel reactions

---
 .../posts/previews/TelegramPreview.vue        | 38 +++++++++++++++++--
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/resources/js/components/posts/previews/TelegramPreview.vue b/resources/js/components/posts/previews/TelegramPreview.vue
index 96ea9e6a..5c4c5fb0 100644
--- a/resources/js/components/posts/previews/TelegramPreview.vue
+++ b/resources/js/components/posts/previews/TelegramPreview.vue
@@ -18,6 +18,13 @@ interface Props {
 }
 
 defineProps<Props>();
+
+// Mock reactions so the preview mirrors how a real Telegram channel post looks.
+const sampleReactions = [
+    { emoji: '❤️', count: 12, reacted: true },
+    { emoji: '🔥', count: 7, reacted: false },
+    { emoji: '👍', count: 4, reacted: false },
+];
 </script>
 
 <template>
@@ -55,7 +62,7 @@ defineProps<Props>();
         <!-- Chat area -->
         <div class="flex-1 overflow-y-auto px-3 py-4">
             <div
-                class="max-w-[85%] overflow-hidden rounded-2xl rounded-bl-md bg-white shadow-sm dark:bg-[#182533]"
+                class="max-w-[90%] overflow-hidden rounded-2xl rounded-bl-sm bg-white shadow-sm dark:bg-[#182533]"
             >
                 <!-- Media -->
                 <div v-if="media.length > 0">
@@ -97,7 +104,7 @@ defineProps<Props>();
                     </div>
                 </div>
 
-                <!-- Text + meta -->
+                <!-- Body -->
                 <div class="px-3 py-2">
                     <div
                         v-if="content"
@@ -105,8 +112,31 @@ defineProps<Props>();
                     >
                         {{ content }}
                     </div>
+
+                    <!-- Reactions -->
+                    <div class="mt-2 flex flex-wrap gap-1.5">
+                        <span
+                            v-for="reaction in sampleReactions"
+                            :key="reaction.emoji"
+                            class="inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-[13px] font-medium"
+                            :class="
+                                reaction.reacted
+                                    ? 'bg-[#3390ec]/15 text-[#3390ec]'
+                                    : 'bg-black/[0.06] text-[#5a6570] dark:bg-white/10 dark:text-[#aeb9c4]'
+                            "
+                        >
+                            <span class="text-sm leading-none">{{
+                                reaction.emoji
+                            }}</span>
+                            <span class="tabular-nums">{{
+                                reaction.count
+                            }}</span>
+                        </span>
+                    </div>
+
+                    <!-- Meta -->
                     <div
-                        class="mt-1 flex items-center justify-end gap-1 text-[12px] text-[#707991] dark:text-[#708499]"
+                        class="mt-1.5 flex items-center justify-end gap-1 text-[12px] text-[#707991] dark:text-[#708499]"
                     >
                         <svg
                             class="h-3.5 w-3.5"
@@ -120,7 +150,7 @@ defineProps<Props>();
                             />
                             <circle cx="12" cy="12" r="3" />
                         </svg>
-                        <span>0</span>
+                        <span>1.2K</span>
                         <span class="ml-1">4:30 PM</span>
                     </div>
                 </div>

From 389177c25b93e89df834a6924c38d1ee551f8d0e Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 14:07:36 -0300
Subject: [PATCH 34/35] Soften Telegram preview bubble shadow (drop trypost ink
 shadow)

---
 resources/js/components/posts/previews/TelegramPreview.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/js/components/posts/previews/TelegramPreview.vue b/resources/js/components/posts/previews/TelegramPreview.vue
index 5c4c5fb0..533f71eb 100644
--- a/resources/js/components/posts/previews/TelegramPreview.vue
+++ b/resources/js/components/posts/previews/TelegramPreview.vue
@@ -62,7 +62,7 @@ const sampleReactions = [
         <!-- Chat area -->
         <div class="flex-1 overflow-y-auto px-3 py-4">
             <div
-                class="max-w-[90%] overflow-hidden rounded-2xl rounded-bl-sm bg-white shadow-sm dark:bg-[#182533]"
+                class="max-w-[90%] overflow-hidden rounded-2xl rounded-bl-sm bg-white shadow-[0_1px_2px_rgba(0,0,0,0.12)] dark:bg-[#182533]"
             >
                 <!-- Media -->
                 <div v-if="media.length > 0">

From c9f086ea9466636805de203d0c52b45cd3514501 Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Sun, 14 Jun 2026 14:09:39 -0300
Subject: [PATCH 35/35] Use formatNumberCompact helper in post platform metrics

---
 .../js/components/posts/PostPlatformMetrics.vue    | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/resources/js/components/posts/PostPlatformMetrics.vue b/resources/js/components/posts/PostPlatformMetrics.vue
index 65946d83..bf4fb35c 100644
--- a/resources/js/components/posts/PostPlatformMetrics.vue
+++ b/resources/js/components/posts/PostPlatformMetrics.vue
@@ -9,6 +9,7 @@ import {
     TooltipProvider,
     TooltipTrigger,
 } from '@/components/ui/tooltip';
+import { formatNumberCompact } from '@/lib/utils';
 import { metrics as metricsRoute } from '@/routes/app/posts/platforms';
 
 interface Metric {
@@ -39,13 +40,6 @@ const reactions = computed(() =>
 
 const hasMetrics = computed(() => metrics.value.length > 0);
 
-const formatNumber = (n: number): string => {
-    if (n >= 1_000_000)
-        return (n / 1_000_000).toFixed(1).replace(/\.0$/, '') + 'M';
-    if (n >= 1_000) return (n / 1_000).toFixed(1).replace(/\.0$/, '') + 'K';
-    return n.toString();
-};
-
 const http = useHttp<Record<string, never>, MetricsResponse>({});
 
 onMounted(async () => {
@@ -98,7 +92,7 @@ onMounted(async () => {
                     {{ metric.label }}
                 </p>
                 <p class="text-sm font-semibold tabular-nums">
-                    {{ formatNumber(metric.value) }}
+                    {{ formatNumberCompact(metric.value) }}
                 </p>
             </div>
         </div>
@@ -116,7 +110,7 @@ onMounted(async () => {
                         >
                             <IconUsers class="size-3.5 text-muted-foreground" />
                             <span class="font-semibold tabular-nums">{{
-                                formatNumber(subscribers.value)
+                                formatNumberCompact(subscribers.value)
                             }}</span>
                         </span>
                     </TooltipTrigger>
@@ -139,7 +133,7 @@ onMounted(async () => {
             >
                 <span class="text-sm leading-none">{{ reaction.label }}</span>
                 <span class="font-semibold tabular-nums">{{
-                    formatNumber(reaction.value)
+                    formatNumberCompact(reaction.value)
                 }}</span>
             </span>
         </div>