Skip to main content
Agent skill

Telegram E2e Userbot

Prove user-visible OpenClaw Telegram behavior on Telegram's Test Server with Convex-leased team credentials; drive real-user turns and record messages, edits, deletions, reactions, typing, or rich content.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Telegram E2e Userbot when an AI agent needs a reusable SKILL.md workflow for this job: Prove user-visible OpenClaw Telegram behavior on Telegram's Test Server with Convex-leased team credentials; drive real-user turns and record messages, edits, deletions, reactions, typing, or rich content.

When not to use it

Skip Telegram E2e Userbot when the task is outside the creativity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/telegram-e2e-userbot
# Save SKILL.md to ~/.claude/skills/telegram-e2e-userbot/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/telegram-e2e-userbot/SKILL.md. For a shared project, commit the folder at .claude/skills/telegram-e2e-userbot/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Telegram E2e Userbot skill for this task: Use Telegram E2e Userbot when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptinferred

    The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Telegram E2E (Userbot)

Prove the requested behavior as a dedicated Telegram Test Server user. TDLib records edits, deletions, reactions, and typing that a second bot cannot observe. For visual claims, also inspect actual Telegram client screenshots; a reconstructed chat image or event log is not visual proof.

Each Convex credential contains one SUT bot and an independent authorization for the QA user. The runner owns that lease through readiness, proof, and cleanup. Pool creation, account authorization repair, and credential publication remain owner-only. Reversible test-chat setup with the leased QA user is ordinary proof work; preserve shared fixtures and other runs.

## 1. Prepare

Run from the OpenClaw checkout and ref under test, using its repository skill:

```bash TELEGRAM_E2E_SKILL_DIR="${TELEGRAM_E2E_SKILL_DIR:-$PWD/.agents/skills/telegram-e2e-userbot}" export TELEGRAM_E2E_SKILL_DIR ```

Verify `node`, `uv`, and a dependency-ready runtime for the exact ref before leasing a credential. The runner uses built `dist/entry.js`; `--source-gateway` uses the repository's development launcher when a dependency-ready source run is appropriate. It runs core and the Telegram plugin from TypeScript source; other plugins, including the model provider, use built output when it exists, so rebuild before claiming their changes. The live run must not implicitly install or build. Only the `mock` backend needs `scripts/e2e/mock-openai-server.mjs`.

Convex access can come from either:

- An existing authenticated CLI with access to the published broker deployment. From `qa/convex-credential-broker`, discovery tries `convex`, then `bunx --no-install convex`, then `npx --offline --no --ignore-scripts convex`. Each launcher gets one 15-second `env --deployment <broker> get` lookup for the CI secret. The helper uses the repository's existing broker binding; no local `CONVEX_DEPLOYMENT`, project-selection file, or dashboard lookup is needed. The secret stays in process memory. - Both `OPENCLAW_QA_CONVEX_SITE_URL` and `OPENCLAW_QA_CONVEX_SECRET_CI`, supplied privately to the doctor or runner process by the existing credential owner.

Check available launchers, existing authentication, and broker-project access before declaring credentials missing. An authenticated launcher with no CI variable needs broker configuration, not another login. Ask the user for authentication only when no existing launcher can authenticate and the broker pair is unavailable. Do not install or log in on the user's behalf. A timeout or network failure is not evidence that credentials are missing. Bun's `--no-install` missing-binary error means that launcher is unavailable; discovery continues to the next installed launcher.

The standalone doctor needs no local HTTP listener, Gateway build, or model backend: it checks the leased TDLib user and calls Telegram’s official Test Bot API directly over HTTPS. The full scenario still needs local networking for its Gateway and Test Bot API adapter (including hold/reject controls), plus the mock provider when selected. A passing doctor does not qualify those local services.

For a full scenario on shared hosts, select two unused ports and pass them explicitly; the runner does not read port environment variables:

```bash : "${TELEGRAM_GATEWAY_PORT:?set an unused Gateway port}" : "${TELEGRAM_MOCK_PORT:?set an unused provider port}" ```

## 2. Select the proof

Read [the verification map](features/README.md), then only the recipe for the behavior under test. Prefer a DM; use groups for group policy, mentions, commands, group topics, or reactions. For a group-topic proof without a prepared forum, `--create-forum` gives the scenario a run-owned topic that cleanup deletes. A generic success turn does not prove formatting, media, timing, or lifecycle behavior.

Extend the harness when its current actions or recorder fields cannot expose the claim. Scenario `command` actions can inspect the leased TDLib state, private credential file, Test Bot API proxy, and Gateway state. Use the [runtime reference](features/runtime-reference.md) for timed scenarios, forums, photo/reply actions, non-default backends, manual operation, or failed-run recovery.

## 3. Check readiness and run

The scenario checks its actual user, bot, transport, and selected chat on its own lease before starting the Gateway. DMs do not depend on unrelated groups. Group runs verify bot membership, privacy, and tester text permissions, preserving a suitable selected group or preparing a run-owned one when needed. Readiness from a released lease never qualifies a later run.

For a standalone diagnostic, use:

```bash node "$TELEGRAM_E2E_SKILL_DIR/scripts/telegram-test-doctor.mjs" ```

Require `ok: true`, `botApiTransport: "direct-https"`, and `botApiProxy: false`. The doctor defaults to DM readiness; `--chat <target>` checks a selected group through the same direct Test Bot API route. It releases its diagnostic lease and does not start product proof. Preserve setup failures and repair their cause before trying again; rotating unchanged credentials to hunt for a pass is not a repair.

Create a durable proof directory outside runner scratch:

```bash TELEGRAM_E2E_PROOF_DIR="$(mktemp -d /tmp/telegram-e2e-proof.XXXXXX)" node "$TELEGRAM_E2E_SKILL_DIR/scripts/run-mock-sut-user-e2e.mjs" \ --gateway-port "$TELEGRAM_GATEWAY_PORT" --mock-port "$TELEGRAM_MOCK_PORT" \ --dm --text 'Please answer with OPENCLAW_E2E_OK only.' \ --record "$TELEGRAM_E2E_PROOF_DIR/events.ndjson" \ --output "$TELEGRAM_E2E_PROOF_DIR/summary.json" ```

The runner owns the lease, proxy, fresh Gateway, provider, user actions, recorder, and teardown. Recording captures facts and rejects probe assertions such as `--expect` and `--any-sut-reply`. A send-confirmation timeout can follow an accepted send: preserve observed events and reconcile them, rather than blindly resending.

## 4. Judge and clean up

Start at the sent action in `summary.json`; judge only later events from the selected SUT. Use raw TDLib `messageId` within the same user's chat, not another account's Bot API receipt, to connect edits and deletions. Require a provider request when the path should reach the model; native commands may produce none.

Report the sanitized command, sent action, relevant timeline rows, provider request count, and the claim those facts prove. Inspect `test-group.json` or the summary's `testForum`/`testDmTopic` when setup ran; fixture evidence is not message proof. Keep credentials, identities, and private paths out of shared logs, screenshots, and reports.

Completion requires the claimed Telegram evidence, no runner-owned processes or listeners, released lease, removed credential scratch, and readable proof files. Cancellation or lease loss stops new work and joins owned consumers. Unconfirmed cleanup is a failure: preserve the private recovery state and use the [runtime recovery instructions](features/runtime-reference.md#retained-run-recovery). Keep explicit proof directories until the review or reproduction no longer needs them.

Intended uses

  • Use Telegram E2e Userbot when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.