@theowlops/channelhub

🌐 ChannelHub

The Universal Multi-Channel Messaging SDK for AI Agents, Autonomous Systems & Microservices

English | Tiếng Việt | 中文

One SDK, every inbox. ChannelHub unifies Zalo, Telegram, Messenger, TikTok, Discord, Slack, WhatsApp/SMS (Twilio), Email, GitHub and Calendar behind a single, strongly-typed UnifiedMessage contract — with a built-in MCP server, a live web dashboard, and zero heavy runtime dependencies. Write your agent's communication logic once; run it everywhere.

📖 Table of Contents

• Why ChannelHub?
• Channel Capability Matrix
• Performance Benchmarks
• How It Works Deep Dive
• Installation
• Quick Start (Zero-Config)
• Channel Adapters
  • 🎵 TikTok for Business · 💬 Messenger · 🔵 Zalo · ✈️ Telegram · 📱 Twilio · 🎮 Discord / 💼 Slack
• Advanced Engine Features
• Rich Media, Stickers & GIFs
• SmartStreamer for LLMs
• CLI Toolkit
• Model Context Protocol (MCP) Server
• Live Dashboard
• Security Hardening
• License

✨ Why ChannelHub?

📊 Channel Capability Matrix

⚡ Performance Benchmarks

Measured on standard development hardware (Bun v1.4.2 / Node v26.3 runtime, x64 Windows 11). Run bun run bench to reproduce locally:

# Execute the benchmark suite
bun run bench

🔬 How It Works Deep Dive

                              ┌──────────────────────────────────────────┐
                              │            Your Application /            │
                              │           AI Agent Framework             │
                              └────────────────────┬─────────────────────┘
                                                   │
                                                   ▼
                              ┌──────────────────────────────────────────┐
                              │                ChannelHub                │
                              │          (Core Event Engine)             │
                              └─────────┬──────────┬──────────┬──────────┘
                                        │          │          │
                     ┌──────────────────┴──┐       │       ┌──┴──────────────────┐
                     ▼                     ▼       ▼       ▼                     ▼
             ┌───────────────┐     ┌───────────────┐   ┌───────────────┐ ┌───────────────┐
             │ TikTok        │     │ Messenger     │   │ Zalo          │ │ Telegram /    │
             │ Business      │     │ Adapter       │   │ Adapter       │ │ Discord/Slack │
             └───────┬───────┘     └───────┬───────┘   └───────┬───────┘ └───────┬───────┘
                     │                     │                   │                 │
                     ▼                     ▼                   ▼                 ▼
             TikTok Business       Meta Graph API      zca-js Web API      Bot Gateways &
             Messaging API         Resumable Upload    & OA v3 API         REST Webhooks

1. Unified Message Protocol (UnifiedMessage)

Every incoming payload — regardless of originating protocol (TikTok Webhook, Telegram Polling, Discord WebSocket, Meta Graph API) — is normalized into an immutable, cross-platform standard representation:

export interface UnifiedMessage {
  id: string;               // Normalized message identifier
  channel: ChannelType;     // "tiktok" | "zalo" | "telegram" | "discord" | "slack" | "messenger"
  sender: {
    id: string;
    name?: string;
    username?: string;
    avatarUrl?: string;
    isBot?: boolean;
  };
  chat: {
    id: string;
    type: "dm" | "group" | "channel";
    title?: string;
  };
  content: {
    text: string;
    attachments?: MediaAttachment[];
    replyToId?: string;
  };
  raw: unknown;             // Original vendor payload preserved for platform-specific access
  timestamp: number;
}

2. The MessageContext Lifecycle

When an event occurs, ChannelHub constructs a MessageContext wrapper around the event. This decouples message reply logic from the underlying protocol:

• Calling await ctx.reply("Hello") automatically resolves the originating channel, routes through the target adapter, manages rate-limiting queues, and emits typing indicators.
• Calling await ctx.sendMedia({ type: "image", source: "./image.png" }) validates local paths against directory traversal, detects MIME headers, and handles chunked file uploading seamlessly.

📦 Installation

# Bun (Recommended)
bun add @theowlops/channelhub

# NPM
npm install @theowlops/channelhub

# PNPM
pnpm add @theowlops/channelhub

# Yarn
yarn add @theowlops/channelhub

🚀 Quick Start (Zero-Config)

Get started in 3 simple steps. ChannelHub handles all the boilerplate for you!

Step 1: Scaffold your project

Run the interactive init command in an empty folder:

mkdir my-bot && cd my-bot
npx @theowlops/channelhub init

(This automatically creates .env, bot.ts, and package.json for you).

Step 2: Add your tokens

Open the newly created .env file and paste your bot tokens (e.g., from @BotFather for Telegram).

Step 3: Run your Bot & Diagnose

Install dependencies and start the bot:

bun install  # or npm install
bun bot.ts   # or npx tsx bot.ts

Not working? ChannelHub comes with a built-in doctor to check your environment and tokens. Run:

npx @theowlops/channelhub doctor

Or skip scaffolding entirely and wire a bot + live dashboard by hand:

import { ChannelHub, TelegramChannelAdapter } from "@theowlops/channelhub";

const hub = new ChannelHub();
hub.register(new TelegramChannelAdapter({ botToken: process.env.TELEGRAM_BOT_TOKEN }));

hub.onMessage(async (ctx) => {
  await ctx.reply(`Echo: ${ctx.message.content.text}`);
});

await hub.dashboard(); // 📊 live dashboard → http://127.0.0.1:8790
await hub.startAll();

🔌 Channel Adapters

🎵 TikTok for Business & Shop

Supports TikTok Business Messaging API v1.3. Handles inbound webhooks with timing-safe HMAC-SHA256 signature verification and replay prevention.

import { TikTokBusinessAdapter } from "@theowlops/channelhub/channels/tiktok";

const tiktok = new TikTokBusinessAdapter({
  appId: "YOUR_TIKTOK_APP_ID",
  clientSecret: "YOUR_TIKTOK_CLIENT_SECRET",
  accessToken: "YOUR_TIKTOK_ACCESS_TOKEN",
  maxWebhookAgeSeconds: 300 // Replay attack protection (default 300s)
});

// In your HTTP server (Fastify, Express, Bun.serve)
app.post("/webhook/tiktok", async (req, res) => {
  const verified = await tiktok.handleWebhook(req.rawBody, req.headers["tiktok-signature"]);
  if (!verified) return res.status(401).send("Unauthorized");
  return res.status(200).send("OK");
});

💬 Meta Messenger Adapter

ChannelHub provides two native Messenger integrations:

1. Meta Graph API (Official Page Bot) Supports webhook challenge verification, permissions discovery, and large file support.

import { MessengerChannelAdapter } from "@theowlops/channelhub/channels/messenger";

const messenger = new MessengerChannelAdapter({
  pageAccessToken: "EAA...",
  verifyToken: "custom_webhook_secret",
  appSecret: "facebook_app_secret",
  autoSubscribePage: true, // Automatically subscribe to webhook events
});

2. Personal Profile Adapter (Playwright Stealth) Automates your personal Facebook account. Uses a persistent browser context to emulate human behavior and bypass Meta security checkpoints.

import { MessengerPersonalAdapter } from "@theowlops/channelhub/channels/messenger";

// Run 'channelhub login:messenger' first to generate cookies!
const personal = new MessengerPersonalAdapter({
  headless: true,
  maxMessagesPerMinute: 15,
  humanTypingDelayMs: 40,
});

🔵 Zalo Adapter

Supports reverse-engineered Web API (zca-js) personal sessions and Official Account (OA) v3 OpenAPI. Includes anti-ban jitter algorithms and automatic quote object generation.

import { ZaloChannelAdapter } from "@theowlops/channelhub/channels/zalo";

const zalo = new ZaloChannelAdapter({
  credentialsPath: "./credentials.json", // Auto-captured session
  minDelayMs: 300,
  maxDelayMs: 800
});

✈️ Telegram Adapter

Lightweight bot integration via Telegram Bot API with native webhook and polling dispatchers.

import { TelegramChannelAdapter } from "@theowlops/channelhub/channels/telegram";

const telegram = new TelegramChannelAdapter({
  botToken: "123456:ABC-DEF..."
});

📱 Twilio Adapter

Omnichannel adapter for WhatsApp, SMS, MMS, and RCS via Twilio API. Supports timing-safe HMAC-SHA1 signature verification for webhooks.

import { TwilioChannelAdapter } from "@theowlops/channelhub/channels/twilio";

const twilio = new TwilioChannelAdapter({
  accountSid: "AC...",
  authToken: "YOUR_TWILIO_AUTH_TOKEN",
  phoneNumber: "whatsapp:+14155238886" // Or standard SMS number
});

🎮 Discord & 💼 Slack Adapters

import { DiscordChannelAdapter } from "@theowlops/channelhub/channels/discord";
import { SlackChannelAdapter } from "@theowlops/channelhub/channels/slack";

const discord = new DiscordChannelAdapter({ botToken: "DISCORD_TOKEN" });
const slack = new SlackChannelAdapter({ botToken: "xoxb-...", signingSecret: "..." });

⚡ Advanced Engine Features

1. Onion Middleware Pipeline (hub.use)

Express / Koa-style middleware pipeline allows intercepting, modifying, or short-circuiting message dispatching:

// Rate limiting or authentication middleware
hub.use(async (ctx, next) => {
  if (ctx.message.content.text.includes("DROP_ME")) {
    return; // Short-circuit, halts pipeline
  }
  await next(); // Proceed to downstream handlers
});

2. Human Handoff & Takeover (ctx.handoff)

Temporarily mute automated bot responses in a specific chat when human customer support steps in:

hub.on("message", async (ctx) => {
  if (ctx.message.content.text === "talk to human") {
    // Pause bot in this chat for 30 minutes
    ctx.handoff(30 * 60 * 1000, "Human agent takeover");
    await ctx.reply("Connecting you to a human agent. Bot muted for 30 minutes.");
    return;
  }
});

// Resume bot manually:
// ctx.resume() or hub.handoff.resume(channel, chatId);

3. Lock-free Multi-Core Rate Limiter (SharedTokenBucketLimiter)

Synchronize rate limits across multiple Node/Bun Worker Threads using SharedArrayBuffer and CPU Atomics:

• Throughput: ~3,700,000 ops/second (nano-second memory latency).
• Zero Redis Dependency: Pure in-memory zero-cost synchronization on a single machine.

import { SharedTokenBucketLimiter } from "@theowlops/channelhub/core";

const limiter = new SharedTokenBucketLimiter(100, 20); // 100 capacity, 20 refills/sec
if (limiter.tryAcquire(1)) {
  // Dispatched safely within provider quota
}

🎨 Rich Media, Stickers & GIFs

ChannelHub normalizes rich media transmission across all platforms:

// 1. Send Images / Files via URL or Local Path
await ctx.sendMedia({
  type: "image",
  source: "https://example.com/art.png",
  caption: "Concept Art"
});

// 2. Send Large Videos (Meta Resumable Upload up to 100MB)
await ctx.sendMedia({
  type: "video",
  source: "/var/media/demo_video.mp4"
});

// 3. Send Native Stickers
// Supports Telegram file_id, Zalo sticker ID, or Messenger sticker ID
await ctx.sendSticker("369239263222822");

// 4. Send Animated GIFs
await ctx.sendGif("https://media.giphy.com/media/cat.gif", "Cat Dancing");

🌊 SmartStreamer for LLMs

LLMs generate responses token by token. Direct API calls per token hit rate limits. SmartStreamer batches tokens adaptively:

• Editable Channels (Discord, Telegram): Streams first chunk, then edits the message at throttled intervals (updateIntervalMs: 800).
• Non-Editable Channels (Zalo, Messenger, TikTok): Accumulates tokens and flushes them chunk by chunk on sentence boundaries (., !, ?, \n) while emitting typing signals.

import { SmartStreamer } from "@theowlops/channelhub/core";

const streamer = new SmartStreamer(ctx, {
  chunkSentences: true,
  updateIntervalMs: 800
});

// Pipe tokens directly from OpenAI / Anthropic / Local LLM
for await (const chunk of llmTokenStream) {
  await streamer.write(chunk);
}
await streamer.end();

🛠️ CLI Toolkit

ChannelHub includes a built-in CLI (channelhub) to streamline project scaffolding, account authentication, and environment troubleshooting:

🤖 Model Context Protocol (MCP) Server

ChannelHub ships with a standalone stdio JSON-RPC MCP server. Connect your AI agent directly to all your chat channels with zero boilerplate.

Starting the Daemon

channelhub-mcp

Claude Desktop / Hermes Agent Config

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "channelhub": {
      "command": "bun",
      "args": ["run", "channelhub-mcp"]
    }
  }
}

Available MCP Tools (30+)

📊 Live Dashboard

A built-in, zero-dependency web dashboard for your bot traffic — no database, no external service, one line of code:

await hub.dashboard(); // 📊 → http://127.0.0.1:8790 — that's it

The page auto-refreshes every 5 seconds; GET /api/stats returns the same JSON snapshot for your own tooling. Non-default port, auth and persistence are optional flags on the same call:

await hub.dashboard({
  port: 3000,                          // default 8790, binds 127.0.0.1
  // host: "0.0.0.0",                  // expose beyond localhost — requires apiKey
  apiKey: process.env.DASHBOARD_KEY,   // or CHANNELHUB_DASHBOARD_KEY env
  dataFile: "./channelhub-stats.json", // persist stats across restarts
});

Prefer explicit control? new DashboardBridge(hub, options) + await start() is exactly equivalent.

Security model: the HTML page is static and public; all data flows through GET /api/stats. On the default loopback binding no key is needed. When host is set beyond loopback without an apiKey, the API fails closed (401 for every request). With apiKey (or the CHANNELHUB_DASHBOARD_KEY env), a timing-safe Bearer check protects the endpoint — the page prompts for the key and keeps it in sessionStorage.

🛡 Security Hardening

• HMAC-SHA256 & Timing-Safe Verification: All inbound webhooks (TikTok, Messenger, Slack) verify cryptographic signatures via crypto.timingSafeEqual to thwart timing attacks.
• Anti-Replay Attack Protection: Webhook deliveries outside the allowed time window (default 300s) are immediately discarded.
• Zero Token Leak in URLs: Authentication tokens are strictly transmitted in HTTP headers (Access-Token, Authorization: Bearer), never in URL query strings.
• Localhost Loopback Default: Webhook bridge and dashboard default to 127.0.0.1 rather than 0.0.0.0.
• DoS Payload Limits: Enforces a strict 1MB JSON body size ceiling before socket termination.
• Path Traversal Guard: All file uploads run through path.resolve and verify fs.statSync().isFile(), preventing arbitrary file disclosure.
• Credential Hygiene: Auto-masks sensitive tokens in logs ([REDACTED]) and enforces .gitignore rules against credential files.

📄 License

ChannelHub is licensed under the MIT License. Maintained by TheOwlOps Team.