Familiar logo
Familiar usefamiliar.com
Documentation / Fleet

Telegram Integration

Connect Fleet agents to Telegram so you can chat with them from your phone or desktop.

Overview

Fleet can connect to Telegram, letting you message your agents from anywhere. Messages you send to your Telegram bot are forwarded to Fleet, and agent responses are sent back to Telegram.

How it works:

  1. You create a Telegram bot via @BotFather
  2. Fleet polls the Telegram API for new messages (no webhook setup required)
  3. When you message your bot, Fleet receives it and wakes up the subscribed agent
  4. The agent's response is sent back to your Telegram chat

Step 1: Create a Telegram Bot

First, create a bot using Telegram's official @BotFather.

Open BotFather

  1. Open Telegram on your phone or desktop
  2. Search for @BotFather or go to t.me/BotFather
  3. Start a chat with BotFather

Create the Bot

  1. Send /newbot to BotFather
  2. Enter a name for your bot (e.g., "My Fleet Assistant")
  3. Enter a username for your bot (must end in bot, e.g., my_fleet_bot)

BotFather will respond with your bot token:

Done! Congratulations on your new bot. You will find it at t.me/my_fleet_bot.

Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Keep your token secure and store it safely.

Copy the token (the part that looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz). You'll need it in the next step.

Optional: Customize Your Bot

While in BotFather, you can also:

  • /setdescription — Set a description shown when users open the bot
  • /setabouttext — Set the "About" text in the bot's profile
  • /setuserpic — Upload a profile picture for your bot

Step 2: Create a Telegram Trigger in Fleet

Now connect your bot to Fleet.

Open Triggers

  1. In Fleet, go to Settings → Triggers
  2. Click New Trigger
  3. Select Telegram as the trigger type

Store Your Bot Token

Your bot token is a secret that should be stored securely in Fleet's vault:

  1. In the Bot Token Secret dropdown, select + Create new secret
  2. Enter a name for the secret (e.g., my-telegram-bot)
  3. Paste your bot token from BotFather
  4. Click Save Secret

The token is now stored encrypted in Fleet's vault and will be used to authenticate with Telegram.

Configure Chat Permissions

Choose how your bot should respond:

Setting Description
Allow Private Chats Bot responds to direct messages
Allow Group Chats Bot responds in groups where it's added
Require @mention In groups, only respond when the bot is @mentioned

Recommended for personal use: Enable "Allow Private Chats" only. This limits the bot to just you.

Enable User Approval (Recommended)

Toggle Require User Approval to block unknown users until you approve them. This prevents random people from using your bot if they discover it.

When enabled:

  • New users who message your bot see "pending approval"
  • They appear in Fleet's UI for you to approve or reject
  • Only approved users can interact with the agent

Save the Trigger

  1. Give your trigger a name (e.g., telegram-bot)
  2. Click Save

Step 3: Subscribe an Agent

Connect an agent to receive Telegram messages.

Subscribe to the Trigger

  1. Open the agent you want to connect
  2. Go to Agent Settings → Triggers
  3. Click Add Subscription
  4. Select your Telegram trigger
  5. Set a prompt template that tells the agent how to handle messages:
You received a Telegram message from :



Respond helpfully and concisely. Keep responses under 4000 characters (Telegram's limit).
  1. Click Save

The agent will now receive messages from your Telegram bot.

Step 4: Start the Bot

The Telegram trigger needs to be started to begin receiving messages.

  1. Go to Settings → Triggers
  2. Find your Telegram trigger
  3. Click Start Polling

You should see:

  • Status changes to Polling with a green indicator
  • The bot's username appears (e.g., @my_fleet_bot)

The bot is now listening for messages.

Step 5: Message Your Bot

Open Telegram and start chatting with your bot.

Find Your Bot

  1. In Telegram, search for your bot's username (e.g., @my_fleet_bot)
  2. Click Start to begin the conversation
  3. Send a message

If User Approval is Enabled

The first time you message the bot, you'll see:

"Your request to interact with this bot is pending approval. Please wait for the administrator to approve your access."

Approve Yourself in Fleet

  1. Go to Settings → Triggers in Fleet
  2. Open your Telegram trigger
  3. Under Pending Approval, you'll see your Telegram user
  4. Click the checkmark to approve yourself

You'll receive a message in Telegram:

"You've been approved! You can now interact with this bot."

Now your messages will be forwarded to Fleet and the agent will respond.

Configuration Options

Chat Types

Option When to Use
Private chats only Personal assistant, just for you
Group chats only Team bot in a specific group
Both Flexible access from anywhere

Group Chat Behavior

When "Allow Group Chats" is enabled, you can add your bot to Telegram groups. By default, it responds to every message. Enable Require @mention to make it only respond when someone mentions @your_bot_username.

The bot also responds to replies — if someone replies to a bot message, it counts as a mention.

User Management

With "Require User Approval" enabled:

  • Pending users — Shown with name, username, and approve/reject buttons
  • Approved users — Shown as a list of user IDs with remove buttons
  • Rejected users — Removed from pending and won't be prompted again (until they message again)

Approved user IDs are persisted in the trigger configuration, so they survive restarts.

Troubleshooting

Bot Not Responding

  1. Check trigger status — Go to Settings → Triggers and verify it shows "Polling"
  2. Check user approval — If enabled, make sure you're approved
  3. Check agent subscription — Verify the agent is subscribed to the trigger
  4. Check agent state — The agent might be paused or in an error state

"Failed to create Telegram bot" Error

  • Verify your bot token is correct (copy it again from BotFather)
  • Make sure the secret name in the vault matches what's selected in the trigger

Messages Delayed

Fleet uses long-polling with a 60-second timeout. Messages should arrive within a few seconds. If delays persist:

  1. Stop and restart the trigger
  2. Check your network connection
  3. Check Fleet's logs for errors

Bot Token Compromised

If you think your token was exposed:

  1. Go to @BotFather in Telegram
  2. Send /revoke
  3. Select your bot
  4. BotFather will generate a new token
  5. Update the secret in Fleet's vault with the new token
  6. Restart the trigger

Next Steps