Telegram Bot Onboarding

telegram-bot-onboarding Skill

First 30–60 seconds with a user: the /start hero + menu, /help, empty-state copy, follow-up sequences, and the Mini App graduation decision. For microcopy/error/loading UX rules, see telegram-bot-ux-rules. For flow patterns (wizard, branching, etc.), see telegram-bot-flow-patterns.

Built for the agntdev pipeline. See agnt-cli-builder for the build loop.

1. Onboarding — first 30–60 seconds

Onboarding has a clock: segment or lose the user. After 60s of unclear choice, drop-off is steep.

Step 1: /start sends a hero + 3–5 menu buttons

bot.command("start", async (ctx) => {
  ctx.session.step = "menu";
  await ctx.reply(
    "👋 Welcome to Bookings.\n\n" +
    "What brings you here?",
    {
      reply_markup: menuKeyboard([
        { text: "📅 Book a slot", data: "menu:book" },
        { text: "📋 My bookings", data: "menu:my" },
        { text: "❓ How it works", data: "menu:help" },
      ]),
    },
  );
});

Rules:

• Hero ≤ 6 lines. No walls of text.
• 3–5 buttons max. More than 5 = decision paralysis.
• Wording matches user intent. "Book a slot" not "Schedule resource reservation".
• Emoji to disambiguate, not decorate.
• One primary CTA (📅 Book) + one secondary (📋 My bookings) + one help escape (❓ How it works).

Step 2: Branch into the chosen intent

Use Flow Pattern B (Branching menu) from telegram-bot-flow-patterns.

Step 3: /help always exists

bot.command("help", async (ctx) => {
  await ctx.reply(
    "📖 How to use this bot:\n\n" +
    "• /start — Main menu\n" +
    "• /book — Book a slot\n" +
    "• /cancel — Cancel a pending flow\n" +
    "• /my — View your bookings\n\n" +
    "Need more help? Reply to this message.",
  );
});

Step 4: Empty state for first-run features

If a feature has no data for this user, show an empty state, not a silent message.

bot.command("my", async (ctx) => {
  const bookings = await db.getBookings(ctx.from.id);
  if (bookings.length === 0) {
    await ctx.reply(
      "📋 You have no bookings yet.\n\n" +
      "Tap 📅 Book to schedule one.",
      {
        reply_markup: inlineKeyboard([[
          inlineButton("📅 Book now", "menu:book"),
        ]]),
      },
    );
    return;
  }
  // ... render bookings list
});

Step 5: Easy exit + frequency caps

For follow-up sequences:

• Stop button always on automated messages.
• Frequency cap: ≤ 1 automated message per 12h per user unless they replied.
• Quiet hours: don't follow up at night in user's timezone.

Sequences and onboarding copy rules

• Easy exit always: include "Stop" button or instructions like "Reply STOP to pause".
• Frequency caps: no more than 1 automated message per 12 hours per user unless they replied.
• Quiet hours: don't follow up at night in the user's timezone.
• Light personalization: avoid repeated identical messages; vary slightly.

2. Mini App graduation — when to upgrade from inline keyboards

Inline keyboards hit a ceiling. Graduate to a Telegram Mini App (embedded web view) when any of these thresholds is hit:

When none of these apply, stay on inline keyboards — they're cheaper to build, render faster, and don't require web hosting.

Decision

Need >50 items that change frequently?
├── Yes → Mini App
└── No → Inline keyboards
Multi-select with Apply semantics?
├── Yes → Mini App
└── No → Inline keyboards
Need full audit trail of user interactions?
├── Yes → Mini App
└── No → Inline keyboards
Anything else (≤50 items, simple choices, real-time feedback)?
└── Inline keyboards (default)

Web App button

The bridge between inline keyboards and Mini App:

inlineKeyboard([[
  webAppButton("🛒 Open shop", "https://shop.example.com/twa"),
]])

User taps → Mini App opens → user interacts in the embedded web view → app sends a message back via sendMessage on close. Use for: catalog browse, settings panels, checkout, dashboards.

Quick Reference

Cross-references

• telegram-bot-flow-patterns — branching menu pattern, linear wizard, search-then-pick
• telegram-bot-ui — menuKeyboard, inlineKeyboard, webAppButton
• telegram-bot-ux-rules — microcopy, button labels, error/loading UX
• telegram-bot-api-rich-messages — Rich Messages, Checklists