TrackFox logoTrackFoxDocs
Dashboard
Docs/AUTOMATIONS/Telegram

Telegram Automation

Get real-time notifications in Telegram when custom events are triggered on your website.

Step 1: Create a Telegram Bot

Before setting up automation in TrackFox, you need to create a Telegram bot and get your bot token.

Creating a Bot with BotFather

  1. Open Telegram and search for @BotFather (the official bot for creating bots)
  2. Start a conversation with BotFather by clicking Start or sending /start
  3. Send the command /newbot to create a new bot
  4. BotFather will ask you to choose a name for your bot (this is the display name)
  5. Then choose a username for your bot (must end in "bot", e.g., trackfox_alerts_bot)
  6. BotFather will send you a message containing your bot token - save this token!

Important: Keep your bot token private. Anyone with the token has full control over your bot.

Example bot token format: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Step 2: Get Your Chat ID

You need to tell your bot where to send notifications. This is your Chat ID.

For Personal Chats

  1. Search for your bot in Telegram (using the username you created)
  2. Start a conversation by clicking Start or sending /start
  3. Send any message to your bot (e.g., "Hello")
  4. Open this URL in your browser (replace BOT_TOKEN with your actual bot token): 
    https://api.telegram.org/botBOT_TOKEN/getUpdates
  5. Look for the "chat":{"id": field in the JSON response
  6. Your Chat ID is the number after "id":

Example: If you see "chat":{"id":123456789, your Chat ID is 123456789

Step 3: Connect Telegram in TrackFox

  1. Go to your dashboard and select the website you want to set up automation for
  2. Click on the dropdown menu for your website in the top left of your dashboard
  3. Click on Site Settings
  4. Navigate to the Automations tab
  5. Scroll to the Telegram Bot section
  6. Paste your Bot Token from BotFather
  7. Paste your Chat ID (the ID where notifications will be sent)
  8. Click Connect Telegram

TrackFox will validate your credentials by sending a test message. If successful, you'll see a confirmation message!

Step 4: Configure Event Notifications

After connecting your bot, you can configure which events trigger notifications.

Event States

Each custom event can be in one of two states:

  • Active 🔔: Event will trigger Telegram notifications
  • Muted 🔕: Event will not trigger notifications (default state)

Setting Event States

  1. In the Automations tab, scroll to the Events section under Telegram
  2. You'll see a list of all custom events that have been tracked on your website
  3. Click on any event to toggle between Active and Muted states
  4. Changes are saved automatically

Step 5: Test Your Webhook

Before relying on automation, test that your bot is working correctly:

  1. In the Automations tab, click the Test Webhook button
  2. You should receive a test notification in your Telegram chat/channel/group
  3. The notification will include a ✅ checkmark and "Test Notification" title

Note: The Test button is only available when you have at least one Active event configured.

Notification Format

When a custom event is triggered, you'll receive a formatted message with:

  • Event emoji and title
  • Visitor country with flag emoji
  • Event name
  • Domain name
  • Direct link to your TrackFox dashboard

Example notification:

🎉 New Event

A visitor from 🇺🇸 United States triggered payment on example.com.

Event Name: payment
Country: United States
Domain: example.com

🔗 View in Dashboard

━━━━━━━━━━━━━━━━━━
📊 TrackFox Analytics

Troubleshooting

Bot not receiving messages

  • Verify the bot token is correct
  • Make sure you started a conversation with the bot (send /start)
  • For channels/groups, ensure the bot is added as an administrator

Wrong Chat ID

  • Double-check the Chat ID format (positive for users, negative for channels/groups)
  • Use the getUpdates method to verify your Chat ID
  • Make sure you sent at least one message before checking getUpdates

No events showing

  • Events only appear after they've been tracked at least once on your website
  • Make sure you're tracking custom events correctly

Auto-disabled after failures

If your bot encounters 3 consecutive failures (e.g., bot token revoked, chat not accessible), automation will auto-disable. To re-enable:

  1. Fix the underlying issue (check bot token, chat permissions)
  2. Disconnect and reconnect the bot
  3. The failure counter will reset

Disconnecting Your Bot

To disconnect your Telegram bot:

  1. In the Automations tab, scroll to the bottom of the Telegram section
  2. Click the Disconnect button
  3. Confirm the disconnection in the popup

Warning: Disconnecting will stop all notifications and remove your bot credentials. You'll need to reconnect and reconfigure event states if you want to re-enable notifications later.

Security & Privacy

  • Bot tokens are encrypted in the database using AES-256-GCM encryption
  • Tokens are never exposed in API responses or browser storage
  • Only website owners can configure automation settings
  • Notifications are throttled to maximum 1 per event per minute to prevent spam

Next Steps

Now that you've set up Telegram automation:

Need help? Contact us for assistance.

Suggest features? We'd love your feedback