Automatic setup with a bot token

The fastest way to start using Metriox: connect automatically by providing your Telegram bot token.

What you get

When you connect a token, Metriox automatically:

• Tracks every user who interacts with the bot
• Collects incoming and outgoing messages and other events
• Stores the interaction history
• Lets you start analyzing data right away, with no code integration

How to connect

Step 1: Get the bot token

If you already have a Telegram bot, you already have its token. If not:

1. Message @BotFather in Telegram
2. Run the /newbot command
3. Follow the instructions
4. Copy the token (it looks like this: 123456789:ABCdefGHIjklmnoPQRstuvWXYz)

Step 2: Add the bot to Metriox

1. Open the Metriox app
2. Go to Settings → Bots
3. Click + Add bot
4. Open Bot settings (the gear icon)
5. Select the Telegram integration and paste the token
6. Turn on the Enable automatic collection toggle

Security

Never publish or share your bot token with anyone. Anyone who knows the token can control your bot. We store the token encrypted and use it only with your permission.

Step 3: Start using it

That's it. Metriox now tracks your bot's events. Open the dashboard and start analyzing.

Automatically captured user properties

On every interaction with the bot, Metriox stores the user's Telegram profile. These properties are available on the Users page and can be used in filters.

Profile properties ($tg.*)

Property	Type	Description
$tg.first_name	string	First name
$tg.last_name	string	Last name (if set)
$tg.username	string	Telegram username (if set)
$tg.lang	string	Language code ("ru", "en", and so on)
$tg.is_bot	boolean	Whether the account is a bot
$tg.is_premium	boolean	Premium status (if reported by Telegram)

The /start parameter

If a user launched the bot through a deep link with a parameter (for example, t.me/YourBot?start=ref_abc), Metriox stores:

Property	Type	Description
$tg.start_raw	string	The /start parameter, exactly as received
$tg.start.<key>	string	Parsed key=value pairs from the parameter

Example: the deep link t.me/YourBot?start=ref_123%26utm_campaign%3Dpromo produces:

$tg.start_raw           = "ref_123&utm_campaign=promo"
$tg.start.ref           = "123"
$tg.start.utm_campaign  = "promo"

Profile updates

The user profile is refreshed on every interaction. ClickHouse keeps the latest snapshot — newer data overwrites older data.

Choosing which events to capture

Not every bot needs everything. In the Telegram integration settings you choose which update categories to record — a simple bot is fine with messages and button clicks, while a bot working with channels and supergroups also wants posts and members:

Category	What it records	Default
Messages	messages and edits to them	enabled
Button clicks	callbacks from inline buttons	enabled
Inline queries	the bot's inline mode	enabled
Reactions	reactions to messages	enabled
Polls	polls and votes	enabled
Payments	payment stages	enabled
Business messages	Telegram Business	enabled
Channel and supergroup posts	posts and edits to them	disabled
Deletions	deleted messages	disabled
Joins, leaves, and blocks	chat members, join requests, bot blocks	disabled

Changes apply without a restart — they are picked up on the next configuration refresh.

The last three categories are off on purpose: in an active channel or a large supergroup they produce a stream of events that is rarely needed in full, so turn it on deliberately.

Direct messages do not come from here

A token connection receives updates over MTProto. It gives you channels, supergroups, and reactions, but it does not deliver the bot's direct messages (DMs) — only the SDK on top of Bot API brings those. So the "Messages" category alone will not show one-on-one conversations: connect the SDK for the full picture.

Additional events

Besides the automatic events, you can send your own events through the API or the SDK.

What's next?

Once the token is connected:

1. Check the data — open the dashboard and watch events in real time
2. Build widgets — analyze your data with the dashboard
3. Add custom events — use the SDK or the API to send your own events

---

Feedback? If you have questions, contact support.