# Clawdbot Hub
Message hub component for ClawdBot — webhook processing, session management, conversation history, and multi-gateway support for Bijection
- Package: @bijectionhq/clawdbot-hub
- Category: Messaging
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/clawdbot-hub/tree/b0d9c111a9fe982b121ec0a5bca8babd80914c86
- Upstream: https://github.com/TimpiaAI/convex-clawdbot-hub/tree/007bdd11b66fbe4aab221a541217edc9372e86f0
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/clawdbot-hub
## Get the source
Bijection repository access is required. Request access at https://bijection.com/contact.
```sh
git clone https://github.com/bijectionhq/clawdbot-hub.git
cd clawdbot-hub
git checkout b0d9c111a9fe982b121ec0a5bca8babd80914c86
```
## Before using this component
Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.
## Upstream package documentation
Recorded 2026-10-23. This describes convex-clawdbot-hub; check the Bijection adaptation separately.
A Convex Component that provides message hub infrastructure for AI chatbots with webhook processing, session management, and conversation history. Handles message deduplication, configurable session scoping (per-user, per-channel, per-peer), and multi-gateway routing for WhatsApp, Telegram, Discord, Slack and custom integrations. Includes real-time subscriptions for web dashboards and TTL-based cleanup with TypeScript generics for type-safe user/channel IDs.
### Use cases
• **Building multi-platform chatbots** that need to handle messages from WhatsApp, Telegram, Discord, and Slack through a unified backend with consistent session management
• **Creating AI agents with conversation memory** that maintain context across interactions using configurable session scopes and paginated message history retrieval
• **Processing webhook-based messaging** where you need automatic deduplication, reliable message storage, and real-time updates for dashboard interfaces
• **Managing chat sessions at scale** with different scoping strategies (per-user for cross-channel bots, per-channel for group chats, per-peer for direct messages)
• **Building messaging analytics dashboards** that require real-time subscriptions to conversation data with threading support and reply context
### How it works
The component centers around the `ClawdBotHub` class which processes inbound messages through `processInbound()` with automatic deduplication based on gateway message IDs. Sessions are created and managed using configurable scopes: "user" for single user across channels, "channel" for group chats, or "peer" for user-channel pairs.
Message processing flows through HTTP actions that receive webhook payloads, then store messages with session resolution and gateway routing. The `sendOutbound()` method handles bot responses while `getMessages()` provides paginated conversation history. Real-time updates work through reactive queries like `getLatestMessages()` that automatically update dashboard interfaces.
Setup involves registering the component in `convex.config.ts`, creating wrapper functions for webhooks and queries, then registering gateways with `registerGateway()`. The component includes built-in cron jobs for cleanup using `pruneSessions()` and `pruneDedup()` to manage TTL-based data retention.
### Upstream README
# convex-clawdbot-hub
Message hub backend for ClawdBot
Webhook processing • Session management • Conversation history • Multi-gateway support
[View Demo](#-live-demo) • [Documentation](#-setup) • [API Reference](#-api-reference)
---
Message hub backend for [ClawdBot](https://clawd.bot) — webhook processing, session management, conversation history, and multi-gateway support. Built as a [Convex Component](https://docs.convex.dev/components).
## Features
- **Webhook processing** — receive and store inbound messages with automatic deduplication
- **Session management** — configurable scoping (per-user, per-channel, per-peer)
- **Conversation history** — paginated retrieval with threading and reply context
- **Multi-gateway support** — route messages from WhatsApp, Telegram, Discord, Slack, and custom gateways
- **Real-time subscriptions** — reactive queries for web dashboards
- **TTL-based pruning** — cron-friendly cleanup for sessions and dedup records
- **TypeScript generics** — type-safe user/channel IDs
## Installation
```bash
npm install convex-clawdbot-hub
```
## Setup
### 1. Register the component
```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import clawdbotHub from "convex-clawdbot-hub/convex.config";
const app = defineApp();
app.use(clawdbotHub);
export default app;
```
### 2. Create your backend functions
```ts
// convex/hub.ts
import { ClawdBotHub } from "convex-clawdbot-hub";
import { components } from "./_generated/api.js";
import { httpAction, mutation, query } from "./_generated/server.js";
import { v } from "convex/values";
const hub = new ClawdBotHub(components.clawdbotHub);
// Process inbound webhook from any ClawdBot gateway
export const webhook = httpAction(async (ctx, request) => {
const body = await request.json();
const result = await hub.processInbound(ctx, {
gateway: body.gateway,
gatewayMessageId: body.messageId,
channelId: body.channelId,
userId: body.userId,
content: body.content,
sessionScope: "peer",
});
if (!result) {
return new Response("duplicate", { status: 200 });
}
return new Response(JSON.stringify(result), {
status: 200,
headers: { "Content-Type": "application/json" },
});
});
// Send bot response
export const sendReply = mutation({
args: {
sessionId: v.string(),
gateway: v.string(),
channelId: v.string(),
userId: v.string(),
content: v.string(),
},
handler: async (ctx, args) => {
return await hub.sendOutbound(ctx, args);
},
});
// Get conversation history
export const getHistory = query({
args: { sessionId: v.string(), limit: v.optional(v.number()) },
handler: async (ctx, args) => {
return await hub.getMessages(ctx, args);
},
});
// Real-time latest messages (subscribe for live updates)
export const liveMessages = query({
args: { sessionId: v.string() },
handler: async (ctx, args) => {
return await hub.getLatestMessages(ctx, { sessionId: args.sessionId, limit: 20 });
},
});
```
### 3. Register your gateways
```ts
export const setupGateway = mutation({
args: { gatewayId: v.string(), name: v.string(), type: v.string() },
handler: async (ctx, args) => {
return await hub.registerGateway(ctx, args);
},
});
```
## API Reference
### Webhook Processing
| Method | Description |
|--------|-------------|
| `processInbound(ctx, args)` | Process inbound message with dedup and session resolution |
| `sendOutbound(ctx, args)` | Store an outbound bot/agent response |
### Session Management
| Method | Description |
|--------|-------------|
| `getOrCreateSession(ctx, { gateway, userId, channelId, scope? })` | Find or create session by scope |
| `getSession(ctx, { sessionId })` | Get session details |
| `listSessions(ctx, { userId?, gateway?, activeOnly?, limit? })` | List sessions with filters |
| `endSession(ctx, { sessionId })` | Mark session as inactive |
### Session Scopes
| Scope | Key | Use Case |
|-------|-----|----------|
| `"user"` | One session per user per gateway | Single user across channels |
| `"channel"` | One session per channel per gateway | Group chat / shared channel |
| `"peer"` | One session per user+channel pair | Default — most common for DMs |
### Conversation History
| Method | Description |
|--------|-------------|
| `getMessages(ctx, { sessionId, limit?, before?, after? })` | Paginated history |
| `getThread(ctx, { threadId, limit? })` | Get all messages in a thread |
| `getLatestMessages(ctx, { sessionId, limit? })` | Most recent N messages (reactive) |
### Gateway Management
| Method | Description |
|--------|-------------|
| `registerGateway(ctx, { gatewayId, name, type, config? })` | Register a gateway (idempotent) |
| `removeGateway(ctx, { gatewayId })` | Deactivate a gateway |
| `listGateways(ctx, { activeOnly? })` | List all gateways |
### Cleanup
```ts
// convex/crons.ts
import { cronJobs } from "convex/server";
const crons = cronJobs();
// Prune inactive sessions older than 7 days
crons.daily("prune sessions", { hourUTC: 3, minuteUTC: 0 },
internal.hub.pruneSessions);
// Clean up dedup records older than 24 hours
crons.hourly("prune dedup", { minuteUTC: 30 },
internal.hub.pruneDedup);
export default crons;
```
## TypeScript Generics
```ts
import { Id } from "./_generated/dataModel.js";
// Type-safe with your app's ID types:
const hub = new ClawdBotHub, Id<"channels">>(
components.clawdbotHub
);
// Or with string IDs:
const hub = new ClawdBotHub(components.clawdbotHub);
```
## 🚀 Live Demo
[**View the live demo →** Click here to see ClawdBot Hub in action](https://clawdbot-hub-demo.vercel.app)
## License
MIT
---