Telegram Users (CRM)

TL;DR:

• Access a global list of all users across all bots in your workspace.
• Manage subscriptions, tags, and variables at the individual or bulk level.
• Track interaction history and view conversation logs per-bot.
• Spot conversations that need a live operator using the Needs Attention filter and resolve handoffs from the user detail sidebar.

Who this is for

• Bot Owners & Admins — to monitor growth and manage user access.
• Support Agents — to view conversation history and user status.
• Owners sending reminders and offers — to pick the right clients by tags and answers before a broadcast.

What you will learn

• The difference between Workspace and Bot user contexts.
• How to filter and search for specific users.
• Managing user data via bulk actions.
• Reviewing detailed user profiles and activity logs.
• How to find, handle, and resolve Human Handoff requests.

Overview

The CRM (Customer Relationship Management) module provides a "single source of truth" for all people interacting with your bots. While the CRM is Global at the workspace level, user data is maintained within a Bot-scoped context.

Key concepts

• Workspace Level — The CRM aggregates users from every bot owned by your workspace into one central list.
• User-Bot Context — A single Telegram user (identified by their unique Telegram ID) is treated as a separate entry for each bot they interact with. If "John" uses Bot A and Bot B, he will appear twice in the global CRM list—once for each bot.
• Bot User — The specific record of a user's relationship with a particular bot, including their variables, tags, and subscription status for that bot.

How it works

1. Interaction — A user sends a message or clicks a button in one of your bots.
2. Record Creation — The system automatically creates a "Bot User" record for that specific user-bot pair.
3. Synchronization — User metadata (Name, Username, Language) is pulled from Telegram and updated in the CRM.
4. Management — You can now find this user in the CRM list, view their history, or apply tags.

In the UI

Describe where to find it in the product and what the user sees.

• Location: Main Navigation → CRM or Bot Settings → CRM
• Main sections:
  • Users List — The primary table showing all bot users with search and filtering.
  • Filter Panel — Advanced tools to narrow down users by bot, status, or custom conditions.
  • User Detail Drawer — A slide-out panel showing everything about a specific user.

Advanced Filtering

You can filter users based on:

• Bot — View users of a specific bot only.
• Status — Active or Blocked users.
• Subscription — Subscribed or Unsubscribed users.
• Needs Attention — Show only users with an active Human Handoff flag (conversations waiting for a live operator).
• Conditions — Create complex rules based on Dialogs count, Last contact date, or custom Variables (like Email or Phone).

Bulk Actions

Select multiple users to perform operations at once:

• Set/Remove Tag — Organize users into segments.
• Subscribe/Unsubscribe — Manage notification eligibility.
• Delete — Remove user records from the CRM.

Human Handoff

When a scenario fires a Human Handoff action, the subscriber's CRM record is flagged as needing a live operator. This flag is visible in the user list and the user detail sidebar so operators can find and handle the conversation without leaving the CRM.

Amber badge in the list

Users with an active handoff show an amber "Needs Attention" dot next to their name in the CRM table. Use the Needs Attention filter to show only flagged users.

Resolving a handoff

1. Open the user's detail view (click their name in the list).
2. An amber banner appears at the top of the right sidebar with the handoff timestamp and last message preview.
3. Click Resolve to clear the flag.

After resolving, the banner disappears and the resolved timestamp is recorded. The user returns to normal status in the list.

TIP

Resolving a handoff does not affect the conversation — the bot scenario is not paused. If you need the bot to wait for your reply, the scenario should end in a question node that pauses until the user responds.

Who can resolve handoffs

Any workspace member with the CRM Manage capability can resolve handoffs. Viewers can see the badge but cannot resolve.

Notification to operators

When the bot triggers a handoff, the CRM flag is set immediately. Telegram notifications are optional and controlled per bot in Bot Settings → Customization → Telegram Operator Notifications.

If Telegram notifications are enabled, each selected operator receives a Telegram notification with:

• The user's name and @username
• A preview of the last message
• A signed deep link to the user's CRM detail page

Telegram alerts use a 10-minute deduplication window. The first handoff notification is sent immediately. If the same subscriber hits the same Human Handoff step again during the next 10 minutes, operators do not get another Telegram alert, but the CRM flag still remains active and the CRM timeline stays up to date.

Operators are configured per-bot in Bot Settings → Customization by selecting eligible workspace users who:

• are connected to Telegram in their account
• already exist in this bot's CRM

See Bot Customization for setup instructions.

Examples

Example 1 — Identify High-Engagement Users

Goal: Find users who have had more than 10 conversations.
Setup: Add a filter condition where Dialogs is Greater than 10.
Result: The list filters to show only your most active users across all bots.

Example 2 — Handle all pending handoffs at start of shift

Goal: See every conversation waiting for a human operator.
Setup: Open the CRM, click Filter → Needs Attention → Yes.
Result: The list shows only users with active handoff flags, sorted by handoff request time. Work through them top-to-bottom, open each detail view, reply to the user in Telegram, and click Resolve when done.

Example 3 — Segmenting by Region

Goal: Tag users who speak a specific language for a localized update.
Setup: Search for users with Language set to pt-br, select all, and use Bulk Action → Set Tag (e.g., "Region: Brazil").
Result: You now have a segment ready for a targeted message broadcast.

Troubleshooting

Symptom: I see the same person twice in the list

Cause: This is intended behavior. The user has interacted with two different bots in your workspace.
Fix: Use the Bot filter to focus on a single bot's audience if needed.
Prevention: Always check the Bot column in the CRM table to see which bot the record belongs to.

Symptom: New users are not appearing in the CRM

Cause: The user might not have started the bot or the background sync jobs are processing.
Fix: Ensure the user has sent the /start command. Check the bot's health status in settings.
Prevention: Encourage users to interact with a button immediately after starting the bot to trigger profile sync.

FAQ

• Q: Is the CRM real-time?
  A: Yes. As soon as a user interacts with your bot, their record is created or updated.

• Q: Can I send a message directly from the CRM?
  A: Yes. You can open a 1-on-1 chat with any user directly from their CRM profile to send a manual message. To reach multiple users at once, use the Broadcast feature — it lets you send a message to a filtered segment of your subscribers in one go.

• Q: Can I edit a user's variables here?
  A: In the current version, variables are read-only in the CRM UI. They are updated automatically by your scenario flows (e.g., using a Set Variable node).

• Q: Why does the same Telegram user appear more than once in the CRM?
  A: CRM records are bot-scoped, not workspace-scoped. If a subscriber interacts with several bots inside your workspace, they get a separate CRM entry for each bot. This is intentional — each entry has its own variables, tags, and conversation history, so bots don't accidentally share or overwrite each other's data. The user is still the same person; they just have an independent profile per bot.

• Q: The handoff badge is still showing after I resolved it — why?
  A: Your page may be showing a cached list. Refresh the CRM page or re-apply the filter to see the current state.

• Q: Can the bot re-flag a user after a handoff is resolved?
  A: Yes. Resolving the handoff removes the Needs Attention flag in CRM, but the Telegram notification window is still time-based. If the same user hits the same Human Handoff step again after the 10-minute window has passed, a fresh Telegram alert can be sent. If it happens inside the same 10-minute window, CRM still updates but operators are not alerted again.

• Q: What happens if no operators are configured?
  A: The CRM flag, analytics event, and realtime CRM update are still emitted. Operators simply won't receive a Telegram notification until you select eligible users in Bot Settings → Customization → Telegram Operator Notifications.

Related pages

• Variables and Tags
• Scenario Publishing
• AI Agent Node
• Actions Node — Human Handoff action and all other background actions.
• Bot Customization — Configure Telegram operator notifications and templates.

Notes / Limits

• Bulk Actions Limit — You can perform bulk actions on up to 100 users at a time from the UI.
• Data Retention — Conversation history and activity logs are stored according to your workspace's data retention policy.
• Blocked Status — "Blocked" in the CRM refers to users who have blocked your bot on Telegram or users you have manually restricted.