Telegram Bot

Connect your Telegram bot to Fainflow to automate messaging, media, chats, and user interactions.

Step 1 — Create a bot in BotFather

1. Open @BotFather in Telegram and start a chat.
2. Send /newbot.
3. Enter a display name for the bot (e.g. My Support Bot). Users see this name.
4. Enter a username for the bot — it must:
   • end with bot (case-insensitive)
   • be 5–32 characters long
   • contain only Latin letters, digits, and underscores
   • be globally unique on Telegram
5. BotFather replies with your bot token, e.g. 123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.

⚠️ Keep the token secret. Anyone with the token can control your bot. Never commit it, never share it. If it leaks, send /revoke to BotFather to invalidate it and generate a new one.

Step 2 — Configure the bot (optional but recommended)

While still in BotFather, send /mybots → select your bot to access:

Group Privacy is the most common gotcha — by default, bots in groups receive only commands and replies. If your flow needs every message, switch privacy to Disable.

Step 3 — Connect in Fainflow

1. In Fainflow, open Connections → click + New Connection → choose Telegram Bot.
2. Fill the form:

⚠️ The real bot is determined by the token, not the Name. Name is just a label inside Fainflow. If you paste the token of @bot_A and call the connection My Trading Bot, the connection still talks to @bot_A — messages sent to @trading_bot will never reach this flow. After saving, the connection card shows the actual @username Fainflow detected via getMe — make sure that matches the bot you intend to chat with.

3. Click Connect.

Fainflow validates the token by calling Telegram's getMe and saves your bot's username, first_name, and capabilities. On success you see Bot connected! with the bot's @username.

New Connection

Name

Bot Token

CancelSave

Step 4 — Verify the connection

After saving, open the connection card in Connections. You'll see:

• Bot username — clickable, opens the bot in Telegram
• Bot token — masked (only first 8 characters visible)
• Capabilities — can_join_groups, can_read_all_group_messages, supports_inline_queries

Use the Test connection button to verify the bot is alive and the webhook is registered. If the webhook is missing or broken, click Re-register webhook.

Step 5 — Rotate the token / edit the connection

You can change the bot token without deleting the connection — all attached flows keep working.

1. Open Connections → click the connection card.
2. Next to the masked Bot Token click Edit.
3. Fill any combination:
   • New Bot Token — leave empty to keep current. Paste a new one to rotate.
   • Name — display name in Fainflow.
   • Description — short purpose.
4. Click Save.

If you provided a new token, Fainflow re-validates it through getMe and refreshes the bot's bot_id, username, first_name, and capabilities. Saving fails if Telegram rejects the token, so a bad paste can't break the connection.

💡 When to rotate? If you ran /revoke in BotFather (because the old token leaked), generate a new token, paste it here, and Save. No need to recreate the connection or rebuild flows.

Event: Bot Update

Triggers when your bot receives any update — messages, callbacks, media, join requests, etc.

Outputs

Reacting to more than text — messageKind

The single Bot Update event fires for every update. To handle a specific kind — a photo, a voice note, or being added to a channel — branch on messageKind with an If (or Continue If) function right after the event.

messageKind is one of:

text, photo, video, animation, voice, audio, document, sticker, location, contact, poll, dice, callback, inline, join, leave, member_update, join_request, edited, unknown.

Recipes:

• Handle a photo — If messageKind == "photo" → use fileId with the Download File function (and caption for any text).
• Handle a voice message — If messageKind == "voice" → fileId is the audio file.
• Bot added to a channel/group — If messageKind == "join" → chatId is the chat you were added to, memberStatus is your new role.
• Any media at all — If hasMedia == "true".

Specific event triggers (simpler flows)

If a flow only cares about one kind of update, pick a specific trigger instead of Bot Update + a filter — the flow then fires only for that kind:

Text Message · Photo Received · Video Received · Voice Message · Audio Received · Document Received · Sticker Received · Location Received · Contact Received · Poll Received · Added to Chat/Channel

They carry the same outputs as Bot Update (including fileId/caption), so e.g. Photo Received → Send Photo (with fileId) needs no If at all. You can run several flows on the same bot — one per trigger. Use Bot Update when you want one flow to see everything.

Example: Echo Bot

A simple bot that replies with the same text it receives.

Event: Bot Update
  ↓
Action: Send Message
  chatId ← chatId (from event)
  text   ← text (from event)

Echo Bot

Bot repeats the message it receives

Telegram Bot

Bot Update

message

userID

date

Telegram Bot

Send Message

chatId

userID

text

message

Example: AI Chat Bot

A bot that responds using OpenAI GPT.

AI Chat Bot

Bot responds using OpenAI GPT

Telegram Bot

Bot Update

message

userID

OpenAI

Send Prompt

model

gpt-4

instructions

You are a helpful assistant

input

message

responseText

Telegram Bot

Send Message

chatId

userID

text

responseText

Available Actions

See Telegram Bot Actions for detailed input/output reference.

Tips

• Use Continue If to handle only specific message types (text, commands, photos).
• Use If/Else with text contains /start to greet new users.
• Store the bot token in Vault if you also need to call Telegram API directly from a function — reference it as {{vault.BOT_TOKEN}}.
• Keep Group Privacy enabled unless your flow really needs all messages — Telegram throttles bots that pull more data than they need.

Troubleshooting