telegram-mock-channel

telegram-mock-channel is an OpenClaw plugin that simulates Telegram channel behavior for local and CI tests.

It is designed for recipe/integration tests where you want Telegram semantics without external Telegram network dependencies.

What is implemented in this repository

• Standalone OpenClaw plugin package scaffold (openclaw.plugin.json, index.ts).
• In-process mock HTTP service with account-scoped state.
• MVP mock APIs:
  • POST /v1/mock/telegram/{account}/inbound/message
  • POST /v1/mock/telegram/{account}/inbound/callback_query
  • GET /v1/mock/telegram/{account}/outbound
  • POST /v1/mock/telegram/{account}/outbound/drain
  • POST /v1/mock/telegram/{account}/reset
  • GET /v1/mock/telegram/{account}/health
• Outbound queue model with per-account monotonic seq.

Current status

This repo is in MVP phase.

• Implemented: mock state store, HTTP protocol, plugin wiring, lifecycle-bound server startup.
• Pending for full parity: bridging inbound updates into OpenClaw's Telegram runtime chain and capturing editMessageText/answerCallbackQuery from Telegram adapter internals.

The code exposes setTelegramMockBridge(...) and recordOutboundEvent(...) to integrate with a host-side bridge. For OpenClaw host integration helpers, use installTelegramMockBridge(...) and recordTelegramOutboundCall(...).

Bridge into OpenClaw Telegram runtime

In the host integration layer, wire mock inbound updates into the same Telegram inbound pipeline you already use in gateway runtime.

Example integration sketch:

import {
  installTelegramMockBridge,
  recordTelegramOutboundCall,
} from "@renorzr/telegram-mock-channel";

installTelegramMockBridge(async ({ accountId, update }) => {
  // Forward to Telegram channel inbound processor in OpenClaw.
  await telegramRuntime.handleUpdate({ accountId, update });
});

function onTelegramApiCall(accountId: string, method: string, payload: Record<string, unknown>) {
  recordTelegramOutboundCall({
    accountId,
    method,
    payload,
  });
}

This lets tests inject mock inbound events, while your runtime path remains close to real Telegram channel behavior.

See docs/openclaw-host-integration.md for recommended host patch points in openclaw/openclaw.

Install

npm install

Build and test

npm run build
npm run typecheck
npm test

Run a single test file:

node --test dist/tests/state-store.test.js

Run a single test by name:

node --test --test-name-pattern "seq is isolated by account" dist/tests/state-store.test.js

Plugin usage (OpenClaw)

1. Build plugin.
2. Load plugin from compiled output directory.
3. Configure channels["telegram-mock"] in OpenClaw config.

Example config:

{
  channels: {
    "telegram-mock": {
      enabled: true,
      mock_bind: "127.0.0.1:18790",
      mode: "webhook",
      accounts: {
        default: {
          enabled: true
        }
      }
    }
  }
}

Security defaults

• Bind defaults to loopback (127.0.0.1:18790).
• Optional bearer protection via mock_api_key.
• Account state is isolated in memory.

Design doc

See telegram-mock-channel-design.md for scope and API contract details.