Skip to content

feat(telegram): offer BotFather web app flow next to the chat flow in onboarding#100540

Merged
steipete merged 1 commit into
mainfrom
claude/vigilant-sanderson-8ee746
Jul 6, 2026
Merged

feat(telegram): offer BotFather web app flow next to the chat flow in onboarding#100540
steipete merged 1 commit into
mainfrom
claude/vigilant-sanderson-8ee746

Conversation

@steipete

@steipete steipete commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Closes #100538

What Problem This Solves

Telegram onboarding only describes the chat-command way to get a bot token: DM @Botfather, run /newbot, copy the token. Telegram now ships an official web-based flow — the BotFather web app (Mini App) at https://t.me/BotFather?startapp — which runs in every Telegram client including web.telegram.org. Neither openclaw onboard telegram nor the docs quick-setup mention it, so users who prefer a UI (or are on Telegram Web, where the chat flow is clumsy) never find it.

Why This Change Was Made

Surfaces the web flow next to the existing chat flow without changing any behavior: one new help line in the setup wizard's token help (all three wizard locales), and the docs quick-setup step now presents both flows. Both paths end the same way — the user pastes a token — so the wizard structure, config surface, and token validation are untouched.

Deeper integration via Telegram managed bots (Bot API 9.6+ t.me/newbot/... deep link + getManagedBotToken, fully removing token copy-paste) is intentionally out of scope; it needs a product decision about operating a manager bot and token custody — context and API details are in #100538.

User Impact

Users setting up the Telegram channel see both token-creation paths in openclaw onboard telegram and in the docs, and can create their bot entirely from a web UI. The BotFather toggles accordion in the docs also points at the web app as the GUI alternative for settings like /setprivacy.

Evidence

  • Wizard help line source: Telegram's documented BotFather Mini App deep link (https://core.telegram.org/bots/features).
  • Focused tests (local, via node scripts/run-vitest.mjs): src/wizard/i18n/index.test.ts 5 passed (includes the shipped-locale key-parity check covering the new tokenHelpWebApp key in en/zh-CN/zh-TW) and extensions/telegram/src/setup-surface.test.ts 12 passed.
  • oxfmt --check and oxlint clean on the touched files; git diff --check clean.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation channel: telegram Channel integration: telegram size: XS maintainer Maintainer-authored PR labels Jul 6, 2026
@clawsweeper

clawsweeper Bot commented Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed July 5, 2026, 10:07 PM ET / 02:07 UTC.

Summary
The PR adds a BotFather web app token-creation hint to Telegram onboarding help in all wizard locales and updates the Telegram docs quick setup and BotFather toggles copy.

PR surface: Source +6, Docs +6. Total +12 across 5 files.

Reproducibility: not applicable. this is a docs/onboarding-copy enhancement rather than a bug. Current main source inspection does show the requested web app pointer is absent from the Telegram setup help and quick setup docs.

Review metrics: none identified.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #100538
Summary: This PR is the candidate implementation for the linked Telegram onboarding feature request; the linked issue should remain the canonical problem statement until the PR lands or is closed.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Add redacted real behavior proof showing the Telegram onboarding token-help output after the change.

Proof guidance:

  • [P1] Needs real behavior proof before merge: The PR body only reports focused tests/lint; it still needs a terminal screenshot, copied live output, or recording from a real openclaw onboard telegram run showing the new line, with private data redacted. Updating the PR body should trigger re-review, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

  • [P1] The PR body reports focused tests/lint but does not include after-fix real behavior proof showing the new onboarding help output from a real setup run.

Maintainer options:

  1. Decide the mitigation before merge
    Merge the narrow setup-copy/docs update after a real onboarding-output proof or maintainer proof override, while leaving full managed-bot auto-provisioning as a separate product decision under [Feature]: Telegram onboarding: offer BotFather web app flow next to the chat flow #100538.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

  • [P1] No repair lane is appropriate because there is no actionable code defect; the remaining blocker is contributor real behavior proof or maintainer proof override, with protected-label handling left to humans.

Security
Cleared: Cleared: the diff only adds docs/onboarding copy and a static Telegram deep link, with no dependency, workflow, credential, config, or code-execution surface changed.

Review details

Best possible solution:

Merge the narrow setup-copy/docs update after a real onboarding-output proof or maintainer proof override, while leaving full managed-bot auto-provisioning as a separate product decision under #100538.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a docs/onboarding-copy enhancement rather than a bug. Current main source inspection does show the requested web app pointer is absent from the Telegram setup help and quick setup docs.

Is this the best way to solve the issue?

Yes, with proof still needed: adding one owner-local wizard help line plus matching docs copy is the narrowest maintainable solution for discoverability. The heavier managed-bot provisioning alternative belongs in a separate product decision because it changes token custody and setup shape.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against d095f4755339.

Label changes

Label changes:

  • add P3: This is a low-risk Telegram onboarding/docs discoverability improvement with limited blast radius and no runtime behavior change.
  • add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
  • add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body only reports focused tests/lint; it still needs a terminal screenshot, copied live output, or recording from a real openclaw onboard telegram run showing the new line, with private data redacted. Updating the PR body should trigger re-review, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

  • P3: This is a low-risk Telegram onboarding/docs discoverability improvement with limited blast radius and no runtime behavior change.
  • rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body only reports focused tests/lint; it still needs a terminal screenshot, copied live output, or recording from a real openclaw onboard telegram run showing the new line, with private data redacted. Updating the PR body should trigger re-review, or a maintainer can comment @clawsweeper re-review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed

PR surface:

Source +6, Docs +6. Total +12 across 5 files.

View PR surface stats
Area Files Added Removed Net
Source 4 6 0 +6
Tests 0 0 0 0
Docs 1 7 1 +6
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 5 13 1 +12

What I checked:

  • Current main lacks the requested pointer: On current main, Telegram quick setup still says to chat with @Botfather and run /newbot, while getTelegramTokenHelpLines() only returns the chat-flow lines, env tip, docs link, and website link; rg found no existing startapp or BotFather web app setup pointer in the affected setup/docs surfaces. (extensions/telegram/src/setup-core.ts:20, d095f4755339)
  • PR patch is narrow and owner-boundary-local: The patch adds one setup helper translation key call in the Telegram plugin setup helper, adds the key to all three wizard locales, and updates the public Telegram docs page; it does not change token validation, config shape, runtime routing, or Telegram transport behavior. (extensions/telegram/src/setup-core.ts:20, 392b30599f6f)
  • Entry point and caller checked: telegramSetupWizard.credentials[0].helpLines consumes getTelegramTokenHelpLines(), so the new helper line is on the actual setup wizard token-help surface rather than a dead helper. (extensions/telegram/src/setup-surface.ts:52, d095f4755339)
  • Locale parity coverage exists: src/wizard/i18n/index.test.ts compares every supported wizard locale key set to English, which would catch adding wizard.telegram.tokenHelpWebApp to only one shipped locale. (src/wizard/i18n/index.test.ts:55, d095f4755339)
  • Docs routing checked: pnpm docs:list identifies channels/telegram.md as the relevant Telegram channel page, and docs/AGENTS.md says source docs are the maintained English docs for the published Mintlify site. Public docs: docs/channels/telegram.md. (docs/channels/telegram.md:1, d095f4755339)
  • External link contract checked: Telegram's t.me/BotFather?startapp page returns a Telegram launch page for verified @Botfather with tg://resolve?domain=BotFather&startapp, and Telegram's official Mini Apps docs describe Mini Apps as launchable inside Telegram.

Likely related people:

  • steipete: Live PR metadata shows steipete authored this PR and merged recent adjacent docs/Telegram work; local shallow blame also attributes the current Telegram setup helper and docs setup lines to commit 65aec96, though the shallow history limits confidence in original ownership. (role: recent area contributor-adjacent reviewer/merger and current-line history candidate; confidence: medium; commits: 65aec9644069, 7e7fc0075e3c; files: extensions/telegram/src/setup-core.ts, extensions/telegram/src/setup-surface.ts, docs/channels/telegram.md)
  • scoootscooob: Commit 7e7fc00 recently touched docs/channels/telegram.md and Telegram source/tests as part of channel behavior documentation and runtime work. (role: recent adjacent Telegram/docs contributor; confidence: medium; commits: 7e7fc0075e3c; files: docs/channels/telegram.md, extensions/telegram/src/bot-message-context.ts)
  • moeedahmed: Commit 0e0f0b1 recently changed Telegram source and tests, making them a plausible adjacent routing candidate for Telegram setup-surface review even though this PR is copy-only. (role: recent Telegram source contributor; confidence: low; commits: 0e0f0b16cd6b; files: extensions/telegram/src/bot-message-context.ts, extensions/telegram/src/bot-message-context.typing.test.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot mentioned this pull request Jul 6, 2026
Closed
@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jul 6, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jul 6, 2026
Closed
@steipete
steipete merged commit 037ad2b into main Jul 6, 2026
149 of 159 checks passed
@steipete
steipete deleted the claude/vigilant-sanderson-8ee746 branch July 6, 2026 06:48
vincentkoc added a commit to zhangqueping/openclaw that referenced this pull request Jul 6, 2026
@vincentkoc
Merge remote-tracking branch 'origin/main' into maint/pr-98095-review
c025cdb 
* origin/main: (1287 commits)
  fix(android): block loopback canvas navigation (openclaw#99874)
  fix(hooks): suppress unhandled stdout/stderr stream errors in gmail watcher (openclaw#100519)
  fix(memory-core): guard qmd mcporter JSON.parse against non-JSON stdout (openclaw#98381)
  fix(build): fall back to tsx for build TypeScript scripts (openclaw#91262)
  feat(skills): suggest saving detected reusable workflows by default (openclaw#95477) (openclaw#100692)
  docs(changelog): remove generated release-note entries
  feat(telegram): offer BotFather web app flow in setup help and docs (openclaw#100540)
  fix(ios): unify Talk and Settings row typography on one branded detail row (openclaw#100515)
  feat(gateway): add persisted crash-loop breaker and fatal-config exit contract
  refactor(macos): lock and unify PortGuardian tunnel record persistence so concurrent app instances cannot lose orphan records (openclaw#100601)
  fix: stop reconnecting on protocol mismatch (openclaw#98414)
  fix(maint): reuse recent hosted gates after rebase (openclaw#100663)
  fix(ui): reopen web terminals without stale content (openclaw#100665)
  fix(browser): diagnose empty WSL2 Chrome replies (openclaw#100590)
  fix(ios): chat snaps back to bottom when scrolling to top via status-bar tap (openclaw#100502)
  Treat already-compacted CLI compaction as no-op (openclaw#99136)
  docs(changelog): remove direct main fix entry
  fix(feishu): strip internal tool-trace banners from outbound text (openclaw#98705)
  fix(message): thread --limit through to CLI formatter and surface provider pagination hints (openclaw#99089)
  fix(voyage): close response body stream when batch output JSONL parsing throws (openclaw#98840)
  ...

# Conflicts:
#	extensions/memory-wiki/package.json
@github-actions github-actions Bot mentioned this pull request Jul 6, 2026
Open
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 6, 2026
@steipete
feat(telegram): offer BotFather web app flow in setup help and docs (o…
cdf47cf 
…penclaw#100540)
giodl73-repo pushed a commit to giodl73-repo/openclaw that referenced this pull request Jul 8, 2026
@steipete @giodl73-repo
feat(telegram): offer BotFather web app flow in setup help and docs (o…
56f1b46 
…penclaw#100540)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

channel: telegram Channel integration: telegram docs Improvements or additions to documentation maintainer Maintainer-authored PR P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. size: XS status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Feature]: Telegram onboarding: offer BotFather web app flow next to the chat flow

1 participant

@steipete