SignalCartel

Setup guide · 3 of 4

Connect your Telegram bot + channels

Telegram is the delivery channel. Paid signals push to private subscriber-only channels; free signals mirror to public channels on a configurable delay (30 minutes by default). Setup time: 30–45 minutes.

  1. 1.Register a bot with @BotFather

    Open Telegram, message @BotFather, run /newbot. Pick a display name and a username ending in "bot". Copy the HTTP API token BotFather returns. Save it as TELEGRAM_BOT_TOKEN in your environment. Set BRAND_TELEGRAM_BOT_HANDLE to the username (without the @).

  2. 2.Create paid + free channels

    For each strategy create two channels: a private paid channel (subscribers only) and a public free channel (30-minute-delayed mirror). Add your bot as an administrator to all of them with "Invite Users via Link" and "Ban Users" permissions enabled. Note each channel ID — bot can fetch it via getChat after you forward a message.

  3. 3.Set channel IDs as environment variables

    For each strategy, set TELEGRAM_PAID_CHANNEL_<KEY> and TELEGRAM_FREE_CHANNEL_<KEY> on both your bot host and your Vercel app. Bot uses paid channel to post signals; web app uses free channel ID to list on the /free-signals page.

  4. 4.Set the webhook

    Run setWebhook against https://<your-domain>/api/telegram/webhook with allowed_updates=["chat_member"]. Verify with getWebhookInfo. The webhook handles two events: chat_member (user joins or leaves a channel) and message (one-time setup of /start deeplink invites).

  5. 5.Generate a tagged invite link

    On subscription activation, the webhook creates a single-use channel invite link via createChatInviteLink with name set to the subscriber profile ID. This is how the platform links a Telegram user back to a paid subscription. The link is emailed to the subscriber and shown on /account/subscriptions.

  6. 6.Test the kick flow

    On a separate Telegram account, subscribe through PayPal sandbox, join the paid channel using the invite link, confirm membership. Cancel the subscription. On the next refresh the auto-kicker calls banChatMember then unbanChatMember (which removes them without permanently banning). Confirm the test account is no longer in the channel.

Common gotchas

  • Channel ID format. Channel IDs are negative integers starting with -100. Copying the username instead of the numeric ID breaks sendMessage with PEER_ID_INVALID.
  • Admin permissions.Without “Ban Users” the bot can't kick expired subscribers and the chat_member webhook silently no-ops. Without “Invite Users via Link” createChatInviteLink 403s.
  • Webhook HTTPS.Telegram refuses webhooks without valid TLS. Vercel domains have automatic SSL; self-signed certs require uploading the public cert via setWebhook's certificate param.
  • Free channel delay. Default 30 minutes is configurable via FREE_CHANNEL_DELAY_MS on each bot. Lowering below 5 minutes erodes the paid/free differential and creates churn.