🌐 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
UnifiedMessagecontract — 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
- 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.timingSafeEqualto 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.1rather than0.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.resolveand verifyfs.statSync().isFile(), preventing arbitrary file disclosure. - Credential Hygiene: Auto-masks sensitive tokens in logs (
[REDACTED]) and enforces.gitignorerules against credential files.
📄 License
ChannelHub is licensed under the MIT License. Maintained by TheOwlOps Team.
