Documentation

Build a Telegram Bot — Visual Guide

Everything you need to know about the elements you can place on the flow canvas: messages, conditions, wait input, store data, workflows and the webhook.

Getting started

TGBot lets you build a Telegram bot without writing code. You combine small building blocks on a visual canvas, connect them to each other, and the platform runs your bot through a webhook. The whole process takes a few minutes.

  1. Create a bot in Telegram with @BotFather and copy its token.
  2. Open your Cabinet, press New Bot, paste the token and save the bot.
  3. Press Set Webhook on the bot page — this connects your bot to the platform so Telegram forwards every update to it.
  4. Build your first flow: add a /start message, then attach messages, conditions and actions to it.

You must Set Webhook before the toolbar and the flow canvas appear. Until then the page shows the Set Webhook card and the Bot settings card.

The flow canvas

Every bot page contains a visual canvas with flow tabs across the top. A flow is a group of nodes that starts at a root element (usually a command such as /start or /help). You add elements from the toolbar above the canvas:

  • Add Message — a message your bot sends to the user.
  • Add Condition — a decision point that branches the conversation.
  • Add Wait Input — pauses the flow and waits for a specific kind of user input.
  • Add Store Data — silently saves user data into the database.
  • New Workflow — creates a new flow tab (a new root command).
  • Add Workflow — a step that jumps the user from one flow to another.

Clicking the + under any output opens the same picker with more step types, including Chat Action, Fetch Event Data and Publish to Channel.

Each element is a node on the canvas. A child element runs after its parent: for example, a message with an inline button leads to the message bound to that button, a condition leads to its true or false branch, and a Wait Input leads to the next step once the expected input arrives.

Message

A message is the text your bot sends. It is the most common element on the canvas. You can use it to greet the user, show a menu, explain something, or ask a question.

Placeholders

Insert stored values into a message with curly-brace placeholders. The values come from a source you choose in Bot settings → Message Placeholders — pick a database and enable the columns you need. Placeholders always use the namespaced form:

  • { $user->city } — reads from this bot’s stored users.
  • { $event->description } — reads from the sender’s latest owned event.

In the message editor, open the Insert placeholder dropdown to add a placeholder — it inserts the correct namespaced form for the configured source, for example: 

Hello, { $user->first_name }! Your city is { $user->city }.

Every placeholder accepts an optional fallback that is shown when there is no stored value. Separate it with a vertical bar |; surrounding quotes are optional: 

Event city: { $event->city | 'n/a' }
Your age: { $user->age_category | 'not set' }

The fallback works everywhere placeholders are resolved — message text, inline button labels and URLs, and the image URL of a Send Image reply (a fallback keeps the button or image instead of dropping them).

Inline buttons (inline keyboard)

A message can carry a keyboard. Inline buttons appear directly under the message. Each button has either a callback_data value (an internal identifier) or a URL: 

[ Catalog ]  [ Cart ]  [ Contact ]

To connect a button to the next step, create a child message whose button key equals the button’s callback_data. When the user taps the button, the bot runs that child message. You can attach a different branch to each button of the same message.

Reply keyboard

A reply keyboard replaces the user’s input field with buttons. Tapping a button sends its text as a normal message. A message whose keyboard_key matches that text becomes the next step. Reply keyboards support an optional Share Location button. To dismiss a reply keyboard after the user picks an option, enable the remove keyboard flag on the message.

Condition

A condition is a decision point. It looks at the stored data about the user and routes the conversation to one of two branches: true or false. On the canvas a condition is drawn as a rhombus.

The available condition types are:

  • User is registered — true when a user profile is stored for this bot.
  • User location is required — true when a location has been shared.
  • Required user fields are filled — pick one or more columns; true when every column has a value.
  • User selected a value — pick a column and a value (for example age category 25-30); true when the stored value matches. This is great after a user taps a button in a question.

Each branch either jumps to an existing flow or keeps its steps inline inside the current flow. Use the branch switches in the condition dialog to choose. A condition can also be bound to a single inline button, so each button of a message can branch the conversation independently.

Wait Input

Wait Input pauses the flow and waits for a specific kind of user input. When the expected input arrives, the flow resumes and runs the next element. On the canvas it is drawn as a hexagon.

The supported input types are:

  • Text — any text message. Optionally set a max letters limit (default 255).
  • URL — a text message that must be a valid http(s) link.
  • Location — a shared location.
  • Button — a tap on an inline or reply keyboard button.
  • File — any media: photo, document, video, audio, voice, sticker and more.
  • Date — a text message interpreted as a date.
  • Number — a text message interpreted as a number.

A Wait Input always resumes with the next element you attach to it. If the user sends something that does not match the expected type, the bot keeps waiting.

For a Wait Input that stores its input into a column, you can also set a default value. When the chosen column has no stored value yet, the bot writes the default silently and continues without asking the user; otherwise it waits for input as usual. This is handy for pre-filling a field (for example country = Eesti).

Store Data

Store Data silently saves information about the user without showing a message. It combines two modes in one dialog:

  • Store User Data — captures the sender’s Telegram profile (name, username, language) and any shared location, and writes it to the bot’s stored users. Optionally target the events table instead.
  • Store Value — when the user taps a configured inline button, its value is written into the chosen column of the stored users (or events) table. You can map a whole keyboard so each button value lands in its own column.

The selectable columns are the ones you enabled under Bot settings → Message Placeholders (for example first_name, city, country, gender, age_category). Values stored this way become available as placeholders such as { $user->city } anywhere in your messages, and as the source for conditions.

Workflow

A workflow is a complete, reusable flow of nodes that starts at a root element. Flows are shown as tabs at the top of the canvas and are named after their root command (for example /start, /help).

  • New Workflow — creates a new flow tab from a command or button name.
  • Add Workflow — places a step in a flow that jumps the user to another flow. It is drawn as a dashed amber pill on the canvas. The bot can then share logic between flows (for example a common registration flow reached from every command).

Commands are the classic entry points: a message whose button key is /start runs when the user presses Start in Telegram. Commands must look like /command (letters, digits and underscores).

Click a workflow-jump pill on the canvas to open the flow it points to — the matching tab is selected for you, so you can follow the jump without hunting for it in the tab bar.

Publish to Channel

A Publish to Channel step posts a message — with an optional photo and inline buttons — to one of the bot’s Telegram channels. After posting, the flow continues to whatever you attach after the step, for the original chat.

Adding a channel

Open Bot settings → Channels → Manage and enter the channel’s @username or numeric chat ID. The bot must already be an administrator of the channel — the platform checks this against Telegram before saving it, so make the bot an admin there first.

Adding the step

Click the + under any output and pick Publish to Channel from the picker, choose one of your saved channels, and write the message to post. On the canvas the step is drawn as a rose-bordered node carrying a channel badge.

A common pattern: put a Publish inline button on a review or summary message, and attach a Publish to Channel step to it — tapping the button posts the finished content to the channel.

Webhook & deployment

The platform receives Telegram updates through a webhook. Press Set Webhook to register your bot’s URL with Telegram. After that, every update is delivered to: 

POST /telegram/webhook/{botId}

When an update arrives, the platform reads the message or button tap, walks the flow from the matching root element, evaluates conditions, resolves placeholders and sends the replies. The Incoming Messages panel (expand it from the toolbar) shows recent requests, lets you inspect the flow they triggered, and lets you replay a request to debug your bot.

Stored users

Every person who interacts with your bot and is captured by a Store Data step becomes a stored user for that bot. Stored users are per bot, so the same Telegram account can have different data in different bots. You can view them from the Bot settings card and remove them all if needed.

FAQ

My bot does nothing when I send it a message.

Make sure you pressed Set Webhook, the bot is Active, and your /start flow has at least one message attached.

How do I remember the user’s answer?

Use a Message with buttons, then a Wait Input (Button), then Store Data to save the tapped value into a column, then a Condition to branch on it.

How do placeholders work?

Choose a source and enable columns in Bot settings → Message Placeholders, store data for the user, then insert a placeholder from the message editor’s dropdown (for example { $user->city }). The platform replaces it with the stored value. When there is no value, add a fallback after a vertical bar: { $user->city | 'unknown' } shows unknown.

Can I reuse the same steps in different commands?

Yes. Put the shared steps in their own flow and use the Add Workflow step to jump into it from any command.

Can my bot post to a Telegram channel?

Yes. Make the bot an administrator of the channel, add it under Bot settings → Channels, then attach a Publish to Channel step wherever you want a post to go out (for example behind a "Publish" button).