Bot Customization

TL;DR:

• Control whether your bot shows a "typing…" indicator before sending messages.
• Optionally override the workspace default Google Calendar for this bot.
• Choose what happens when your bot replaces a previous message.
• Set how long a user session stays active without activity.
• Set how long persist variables (var.*+) are kept for inactive users.
• Settings apply immediately — no restart required.

Who this is for

• Bot Owners: Anyone managing a deployed Telegram bot.
• When to read: When you want to customize the conversation experience for your users.

What you will learn

• How to enable/disable the typing indicator.
• How to choose the booking calendar for a specific bot.
• What each replace animation option does.
• How session timeout affects conversation tracking.
• How to control how long persist variables are kept for inactive users.
• Where to find question-level timeout settings.

Overview

Bot Customization settings let you control how your bot interacts with users in real time. These settings are per-bot — each bot can have its own behavior.

Key concepts

• Booking Calendar — The Google Calendar used by Calendar Slot Picker cards in this bot.
• Workspace Default — The fallback calendar selected in Workspace Integrations.
• Typing Indicator — Shows "typing…" in Telegram before the bot sends a message.
• Replace Animation — Visual feedback when the bot deletes its previous message.
• Session Timeout — How long the bot remembers a conversation without user activity.
• Persist Variable Lifetime — How long var.*+ data is kept in Redis for users who stopped interacting with the bot. The timer resets on every interaction (sliding window).

How it works

1. Booking Calendar

If Google Calendar is connected for the workspace, each bot can either:

• keep using the workspace default calendar, or
• override it with a different calendar for this bot only.

This setting affects all Calendar Slot Picker cards inside this bot. You do not need to configure calendar selection separately in every scenario node.

2. Typing Indicator

When enabled, the bot sends a "typing" signal to Telegram before each message. Telegram displays this as "typing…" to the user. This makes the bot feel more natural and responsive.

• Smart mode: Adjusts typing duration based on message length.
• Fixed mode: Uses a constant delay.

3. Replace Animation

When the bot replaces (deletes) its previous message, users see a visual indicator:

• None: Message disappears instantly.
• Fade: Brief "…" indicator, then disappears.
• Explosion: 💥 emoji briefly, then disappears.

4. Session Timeout

A session tracks a single conversation thread. The timeout defines how long the bot waits for the user to respond before considering them inactive.

• Session starts when user sends a message.
• Session extends when user sends another message.
• After N minutes of inactivity, the next bot message starts a new session.

5. Persist Variable Lifetime

Persist variables (var.*+) are stored per-user in Redis and survive /start restarts. This setting controls how long they are kept for users who have gone silent.

The lifetime works as a sliding window: every time a user interacts with the bot, the timer resets. Only truly inactive users whose data has not been touched for the full configured period lose their data.

Setting	What it means
30 days	Data expires if user is inactive for 30 days
90 days	Default — good for most bots
180 days	Suitable for seasonal or low-frequency bots
365 days	Use for loyalty programs or annual subscription bots
Never expire	Data is kept indefinitely — use when losing it is unacceptable

When to use "Never expire"

Choose Never expire only when the stored data is business-critical and there is no natural expiry (for example: loyalty points, completed milestones, permanent user preferences). For most bots, 90 or 180 days is sufficient — inactive users who return after a long gap typically need to re-onboard anyway.

WARNING

"Never expire" means data accumulates indefinitely. If your bot has many users, periodically clean up stale data using the CRM or API.

In the UI

• Location: Bot Settings → Customization
• Main controls:
  • Calendar → Booking Calendar — use the workspace default calendar or override it for this bot.
  • Typing Indicator → Enable — Toggle to show typing status.
  • Typing Mode — Choose smart or fixed.
  • Base Delay — Minimum typing time (ms).
  • Per Character Delay — Extra time per character (smart mode).
  • Max Delay — Maximum typing time (smart mode).
  • Replace Animation — Choose none, fade, or explosion.
  • Session Window — Minutes (15, 30, 60, 90, 120).
  • Persist Variable Lifetime — Choose 30 days, 90 days, 180 days, 365 days, or Never expire.

Calendar override

If the workspace has Google Calendar connected, the Calendar section appears on this page.

• Use workspace default keeps the bot aligned with the calendar selected in Workspace Settings → Integrations → Calendar.
• Selecting a specific calendar here overrides the workspace default only for this bot.

This is useful when several bots in the same workspace should book into different calendars while still sharing the same workspace connection and booking defaults.

Learn more: Calendar Integration

Related behavior

Question Timeout (Message Node)

Individual questions can have their own timeout. This is configured in the Message node → Question card, not here.

• If a question has its own timeout → it overrides the bot-level default.
• If no timeout is set → the question can wait indefinitely (or until session timeout).

Learn more: Message Node

Examples

Example 1 — Disable typing indicator

Goal: Bot sends messages instantly without showing typing.
Setup: Go to Bot Settings → Customization, disable "Typing Indicator".
Result: Messages appear instantly, no typing animation.

Example 2 — Use a different booking calendar for one bot

Goal: One sales bot should book into the sales calendar, while other bots keep using the workspace default.
Setup: Open Bot Settings → Customization → Calendar and choose the sales calendar instead of Use workspace default.
Result: All Calendar Slot Picker cards in this bot use the sales calendar, without changing any scenario nodes.

Example 3 — Add fade effect on message updates

Goal: Users see a subtle fade when bot updates its previous message.
Setup: Set "Replace Animation" to fade.
Result: When bot deletes a message, users briefly see "…" before it disappears.

Example 4 — Short session for high-traffic bots

Goal: Start a new session quickly to avoid confusion in quick exchanges.
Setup: Set "Session Timeout" to 15 minutes.
Result: If user is inactive for 15 minutes, next bot message starts fresh context.

Example 5 — Loyalty points that never expire

Goal: A loyalty bot stores accumulated points in var.points+. Points must survive indefinitely — even if the user takes a year-long break.
Setup: Set "Persist Variable Lifetime" to Never expire.
Result: var.points+ is kept permanently in Redis. The bot can greet the user with their balance no matter how long they were away.

Example 6 — Seasonal campaign bot

Goal: A bot runs a winter campaign. Users might interact in December and return next November.
Setup: Set "Persist Variable Lifetime" to 365 days.
Result: Saved answers and progress are kept for one full year. Users who return for next year's campaign start fresh automatically.

Troubleshooting

Symptom: Typing indicator shows but message sends anyway

Cause: Telegram didn't receive the typing signal (network issue).
Fix: This is handled automatically — the message will still send.
Prevention: None needed, this is expected behavior.

Symptom: User sees error when bot tries to replace message

Cause: The previous message may have been deleted by the user already.
Fix: The bot gracefully skips the deletion. No error shown to user.
Prevention: None needed — runtime handles this.

Symptom: Session never expires

Cause: Session timeout may be set very high, or question-level timeout is not set.
Fix: Check both Bot Settings → Customization (bot-level) and Message node → Question card (question-level).
Prevention: Set explicit timeouts on sensitive questions.

FAQ

• Q: Does changing these settings restart the bot?
  A: No. Settings apply immediately on the next user interaction.

• Q: Can I set different typing settings per scenario?
  A: Not yet. Currently these are bot-level settings.

• Q: Can different bots use different booking calendars?
  A: Yes. Each bot can either keep the workspace default or override it in the Calendar section on this page.

• Q: Where do I set timeout for a specific question?
  A: In the Message node → Question card settings. See Message Node.

• Q: Does the typing indicator work with media messages?
  A: Yes, it shows before the media is sent.

• Q: What happens to a user's persist variables when the lifetime expires?
  A: The data is automatically removed from Redis. The next time that user interacts with the bot, their var.*+ variables will be empty — as if they were a new user. Session variables (var.*) are not affected; they reset with every /start regardless.

• Q: Does the timer reset every time the user sends a message?
  A: Yes. The lifetime is a sliding window — it counts from the user's last interaction, not from when the variable was first set. A user who interacts regularly will never have their data expire, regardless of the configured value.

• Q: Can I set different lifetimes for different variables?
  A: No. The lifetime is a bot-level setting and applies to all persist variables (var.*+) for that bot equally.

• Q: Should I change the lifetime if I switch from 90 days to Never expire?
  A: Yes, and the change takes effect on the next interaction for each user. Existing keys that already have a TTL set will have it removed the next time the user's data is read or written.

• Q: How do I move my scenarios to a different Telegram bot?
  A: Open the bot's actions menu and choose Duplicate. The copy gets all scenarios as unpublished drafts, taken from each scenario's latest draft (including edits you have not published yet). Connect the new bot's token to the copy, review the scenarios and publish them. Users, CRM records and chat history stay with the original bot: Telegram does not let a new bot message people who never started it. That is why a bot that already has users does not accept a token from a different Telegram bot.

• Q: My token leaked. Can I replace it?
  A: Yes. Generate a new token for the same bot in @BotFather (/revoke) and paste it in Update Token. Users and history keep working, because it is still the same Telegram bot.

Human Handoff

Human Handoff lets your bot flag conversations that need a live operator. When a Human Handoff action fires in a scenario, the system:

1. Marks the subscriber in the CRM with an amber "Needs Attention" badge.
2. Emits the handoff event used by CRM realtime updates and analytics.
3. Optionally sends a Telegram notification to selected operators with the user's name and last message preview.
4. Protects from repeats — by default, within 10 minutes operators are notified only once per client and step (configurable, see below), but the CRM badge always stays visible.

How to enable

1. Open Bot Settings → Customization for the bot.
2. Scroll to the Human Handoff section.
3. Toggle Telegram Operator Notifications if you want Telegram alerts for your team.
4. Select one or more eligible operators from the list.
5. Edit the Telegram alert in Notification Template if you want your own wording. The editor starts with the default message; insert the client's name, username or last message with the {} button, and check the preview next to it. The text can't be empty: if you clear it, saving is blocked and Reset to default brings the original text back. The Open in CRM button is added under the message automatically.

You can also do this from the scenario editor: a Human Handoff step and the AI Assistant's launch card have Set up notifications — link your Telegram, press Start in the bot, and you are added to the operators. Send a test notification then makes the bot write to you right away, so you can see notifications reach you. A real notification comes only when a client reaches a Human Handoff step — make sure the step is connected to the flow. A step can also send its own text to its own people (Custom setup in the step), for example a ready consultation request.

Who appears in the operator list

An operator is selectable only when all of these are true:

• the person belongs to this workspace
• their account is connected to Telegram
• they have already interacted with this bot, so they exist in this bot's CRM

Operator notification format

When Telegram notifications are enabled, each selected operator receives a message like:

🔔 Human Help Needed!
User: @johndoe (ID: 123456789) — John Doe
Last message: "Can I book a session for Friday?"

[Open in CRM]

The Open in CRM button uses a signed proxy link that redirects into the subscriber's CRM detail page.

Resolving a handoff

An operator resolves a handoff from the CRM user detail page:

1. Open CRM → Users and filter by Needs Attention (or click the link from the notification).
2. Open the subscriber's detail page.
3. Click Resolve in the handoff banner at the top of the sidebar.

The amber badge disappears and the resolved timestamp is recorded. If the same user triggers another handoff later, a fresh cycle begins.

Deduplication

Repeat protection keeps a fallback branch that fires several times in a row from flooding your Telegram. By default it is on, 10 minutes: after a notification about a client from a Human Handoff step, more triggers from the same client and the same step wait for the interval.

Change it in Bot Settings → Customization → Human Handoff → Repeat protection: turn it off to get every notification (useful when each run is a new request), or pick 30 seconds, 1, 2, 5 or 10 minutes. A Human Handoff step with Custom setup has the same setting of its own; without it, the step follows the bot.

What this means in practice:

• The first handoff trigger sends the Telegram alert immediately.
• If the same handoff step fires again for the same subscriber within the interval, operators do not receive another Telegram alert.
• The CRM flag, analytics event, and realtime CRM update are still emitted even during the window.
• After the interval passes, the next trigger can send a new Telegram alert again.
• Test runs are not limited: each one sends you a 🧪 [TEST] notification.

If you use multiple Human Handoff actions in different branches or nodes, each one has its own window.

When the step runs right after the client taps a button, Last message in the default notification shows that button's label.

Tips

• Place the Human Handoff action in your fallback branches — the node where the bot cannot answer the user's question.
• You can combine it with a Message node that tells the user "A human will help you shortly."
• Turning off Telegram Operator Notifications does not disable handoff in CRM. The action still flags the user and updates the CRM UI in realtime.
• Handoff does not pause the scenario. The bot continues to the Next node after signaling the handoff. If you want to pause the flow, place a Question card after the action to wait for the operator's reply.

Related pages

• Calendar Integration — Connect Google Calendar and set the workspace default calendar.
• Message Node — For question-level timeout settings.
• Actions Node — For the Human Handoff action and all other background actions.
• Variables and Tags — Full reference for var.* (session) and var.*+ (persist) variables.
• Publishing a Scenario — To make your bot live.
• Scenarios Overview — How scenarios work.

Notes / Limits

• Typing delay: Maximum 10,000ms (10 seconds).
• Per-character delay: Maximum 100ms.
• Session timeout: Allowed values: 15, 30, 60, 90, 120 minutes.
• Persist variable lifetime: Allowed values: 30, 90, 180, 365 days, or Never expire. Default: 90 days.
• Question timeout: Controlled in Message node, not here.