openclaw-custom-channel 2026.2.26

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { createCustomChannelPlugin } from "./src/channel.js";
+import { setCustomRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "custom",
+  name: "Custom",
+  description: "Custom channel plugin for OpenClaw - webhook-based chat and group chat",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setCustomRuntime(api.runtime);
+    api.registerChannel({ plugin: createCustomChannelPlugin() });
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "openclaw-custom-channel",
+  "version": "2026.2.26",
+  "description": "Custom channel plugin for OpenClaw - webhook-based integration for chat and group chat",
+  "type": "module",
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "channel": {
+      "id": "custom",
+      "label": "Custom",
+      "selectionLabel": "Custom (Webhook)",
+      "docsPath": "/channels/custom",
+      "docsLabel": "custom",
+      "blurb": "Connect your own chat backend via webhook for direct and group messages.",
+      "order": 95
+    },
+    "install": {
+      "npmSpec": "openclaw-custom-channel",
+      "localPath": "extensions/custom",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,79 @@
+/**
+ * Account resolution: reads config from channels.custom,
+ * merges per-account overrides, falls back to environment variables.
+ */
+
+import type { CustomChannelConfig, ResolvedCustomAccount } from "./types.js";
+
+const CHANNEL_ID = "custom";
+
+function getChannelConfig(cfg: unknown): CustomChannelConfig | undefined {
+  const channels = (cfg as Record<string, unknown>)?.channels as Record<string, unknown> | undefined;
+  return channels?.[CHANNEL_ID] as CustomChannelConfig | undefined;
+}
+
+function parseAllowedUserIds(raw: string | string[] | undefined): string[] {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.filter(Boolean).map(String);
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export function listAccountIds(cfg: unknown): string[] {
+  const channelCfg = getChannelConfig(cfg);
+  if (!channelCfg) return [];
+
+  const ids = new Set<string>();
+
+  const hasBaseToken = channelCfg.token || process.env.CUSTOM_CHANNEL_TOKEN;
+  if (hasBaseToken) {
+    ids.add("default");
+  }
+
+  if (channelCfg.accounts) {
+    for (const id of Object.keys(channelCfg.accounts)) {
+      ids.add(id);
+    }
+  }
+
+  return Array.from(ids);
+}
+
+export function resolveAccount(
+  cfg: unknown,
+  accountId?: string | null,
+): ResolvedCustomAccount {
+  const channelCfg = getChannelConfig(cfg) ?? {};
+  const id = accountId || "default";
+
+  const accountOverride = channelCfg.accounts?.[id] ?? {};
+
+  const envToken = process.env.CUSTOM_CHANNEL_TOKEN ?? "";
+  const envIncomingUrl = process.env.CUSTOM_CHANNEL_INCOMING_URL ?? "";
+  const envAllowFrom = process.env.CUSTOM_CHANNEL_ALLOW_FROM ?? "";
+  const envBotName = process.env.OPENCLAW_BOT_NAME ?? "OpenClaw";
+
+  return {
+    accountId: id,
+    enabled: accountOverride.enabled ?? channelCfg.enabled ?? true,
+    token: accountOverride.token ?? channelCfg.token ?? envToken,
+    incomingUrl:
+      accountOverride.incomingUrl ?? channelCfg.incomingUrl ?? envIncomingUrl,
+    webhookPath:
+      accountOverride.webhookPath ?? channelCfg.webhookPath ?? "/webhook/custom",
+    dmPolicy:
+      accountOverride.dmPolicy ?? channelCfg.dmPolicy ?? "allowlist",
+    allowedUserIds: parseAllowedUserIds(
+      accountOverride.allowFrom ?? channelCfg.allowFrom ?? envAllowFrom,
+    ),
+    rateLimitPerMinute:
+      accountOverride.rateLimitPerMinute ??
+      channelCfg.rateLimitPerMinute ??
+      30,
+    botName: accountOverride.botName ?? channelCfg.botName ?? envBotName,
+    allowInsecureSsl:
+      accountOverride.allowInsecureSsl ?? channelCfg.allowInsecureSsl ?? false,
+  };
+}

package/src/channel.ts

@@ -0,0 +1,391 @@
+/**
+ * Custom Channel Plugin for OpenClaw.
+ *
+ * Webhook-based integration supporting direct chat and group chat.
+ * Adapt webhook payload format and client.sendMessage to your backend API.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import {
+  DEFAULT_ACCOUNT_ID,
+  setAccountEnabledInConfigSection,
+  registerPluginHttpRoute,
+  buildChannelConfigSchema,
+} from "openclaw/plugin-sdk";
+import { z } from "zod";
+import { listAccountIds, resolveAccount } from "./accounts.js";
+import { sendMessage } from "./client.js";
+import { getCustomRuntime } from "./runtime.js";
+import type { ResolvedCustomAccount } from "./types.js";
+import { createWebhookHandler } from "./webhook-handler.js";
+
+const CHANNEL_ID = "custom";
+
+const CustomConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    token: z.string().optional(),
+    incomingUrl: z.string().url().optional(),
+    webhookPath: z.string().optional(),
+    dmPolicy: z.enum(["open", "allowlist", "pairing", "disabled"]).optional(),
+    allowFrom: z.union([z.string(), z.array(z.string())]).optional(),
+    rateLimitPerMinute: z.number().optional(),
+    botName: z.string().optional(),
+    allowInsecureSsl: z.boolean().optional(),
+  })
+  .passthrough();
+
+const CustomChannelConfigSchema = buildChannelConfigSchema(CustomConfigSchema);
+
+const activeRouteUnregisters = new Map<string, () => void>();
+
+export function createCustomChannelPlugin() {
+  return {
+    id: CHANNEL_ID,
+
+    meta: {
+      id: CHANNEL_ID,
+      label: "Custom",
+      selectionLabel: "Custom (Webhook)",
+      detailLabel: "Custom (Webhook)",
+      docsPath: "/channels/custom",
+      blurb: "Connect your own chat backend via webhook for direct and group messages",
+      order: 95,
+    },
+
+    capabilities: {
+      chatTypes: ["direct" as const, "group" as const],
+      media: true,
+      threads: false,
+      reactions: false,
+      edit: false,
+      unsend: false,
+      reply: false,
+      effects: false,
+      blockStreaming: false,
+    },
+
+    reload: { configPrefixes: [`channels.${CHANNEL_ID}`] },
+
+    configSchema: CustomChannelConfigSchema,
+
+    config: {
+      listAccountIds: (cfg: unknown) => listAccountIds(cfg),
+      resolveAccount: (cfg: unknown, accountId?: string | null) =>
+        resolveAccount(cfg, accountId),
+      defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+      setAccountEnabled: ({
+        cfg,
+        accountId,
+        enabled,
+      }: {
+        cfg: unknown;
+        accountId: string;
+        enabled: boolean;
+      }) =>
+        setAccountEnabledInConfigSection({
+          cfg: cfg as OpenClawConfig,
+          sectionKey: CHANNEL_ID,
+          accountId,
+          enabled,
+          allowTopLevel: true,
+        }),
+    },
+
+    pairing: {
+      idLabel: "customUserId",
+      normalizeAllowEntry: (entry: string) => entry.toLowerCase().trim(),
+      notifyApproval: async ({
+        cfg,
+        id,
+      }: {
+        cfg: unknown;
+        id: string;
+      }) => {
+        const account = resolveAccount(cfg);
+        if (!account.incomingUrl) return;
+        await sendMessage(
+          account.incomingUrl,
+          "OpenClaw: your access has been approved.",
+          id,
+          account.allowInsecureSsl,
+        );
+      },
+    },
+
+    security: {
+      resolveDmPolicy: ({
+        cfg,
+        accountId,
+        account,
+      }: {
+        cfg: unknown;
+        accountId?: string | null;
+        account: ResolvedCustomAccount;
+      }) => {
+        const resolvedAccountId =
+          accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+        const channelCfg = (cfg as Record<string, unknown>)?.channels?.[
+          CHANNEL_ID
+        ] as Record<string, unknown> | undefined;
+        const useAccountPath = Boolean(channelCfg?.accounts?.[resolvedAccountId]);
+        const basePath = useAccountPath
+          ? `channels.${CHANNEL_ID}.accounts.${resolvedAccountId}.`
+          : `channels.${CHANNEL_ID}.`;
+        return {
+          policy: account.dmPolicy ?? "allowlist",
+          allowFrom: account.allowedUserIds,
+          policyPath: `${basePath}dmPolicy`,
+          allowFromPath: basePath,
+          approveHint: "openclaw pairing approve custom <code>",
+          normalizeEntry: (raw: string) => raw.toLowerCase().trim(),
+        };
+      },
+      collectWarnings: ({ account }: { account: ResolvedCustomAccount }) => {
+        const warnings: string[] = [];
+        if (!account.token && account.dmPolicy !== "open") {
+          warnings.push(
+            "- Custom: token not configured. Consider adding token for webhook validation.",
+          );
+        }
+        if (!account.incomingUrl) {
+          warnings.push(
+            "- Custom: incomingUrl not configured. The bot cannot send replies.",
+          );
+        }
+        if (account.dmPolicy === "open") {
+          warnings.push(
+            '- Custom: dmPolicy="open" allows any user to message the bot. Consider "allowlist" for production.',
+          );
+        }
+        if (
+          account.dmPolicy === "allowlist" &&
+          account.allowedUserIds.length === 0
+        ) {
+          warnings.push(
+            '- Custom: dmPolicy="allowlist" with empty allowFrom blocks all senders. Add users or set dmPolicy="open".',
+          );
+        }
+        return warnings;
+      },
+    },
+
+    messaging: {
+      normalizeTarget: (target: string) => {
+        const trimmed = target.trim();
+        if (!trimmed) return undefined;
+        return trimmed.replace(/^custom:/i, "").trim();
+      },
+      targetResolver: {
+        looksLikeId: (id: string) => {
+          const trimmed = id?.trim();
+          if (!trimmed) return false;
+          return /^custom:/i.test(trimmed) || trimmed.length > 0;
+        },
+        hint: "<userId> or <groupId>",
+      },
+    },
+
+    directory: {
+      self: async () => null,
+      listPeers: async () => [],
+      listGroups: async () => [],
+    },
+
+    outbound: {
+      deliveryMode: "gateway" as const,
+      textChunkLimit: 2000,
+
+      sendText: async ({
+        to,
+        text,
+        accountId,
+        account: ctxAccount,
+      }: {
+        to: string;
+        text: string;
+        accountId?: string | null;
+        account?: ResolvedCustomAccount;
+      }) => {
+        const account: ResolvedCustomAccount =
+          ctxAccount ?? resolveAccount({}, accountId);
+
+        if (!account.incomingUrl) {
+          throw new Error("Custom channel incoming URL not configured");
+        }
+
+        const ok = await sendMessage(
+          account.incomingUrl,
+          text,
+          to,
+          account.allowInsecureSsl,
+        );
+        if (!ok) {
+          throw new Error("Failed to send message to Custom channel");
+        }
+        return { channel: CHANNEL_ID, messageId: `custom-${Date.now()}`, chatId: to };
+      },
+
+      sendMedia: async ({
+        to,
+        mediaUrl,
+        accountId,
+        account: ctxAccount,
+      }: {
+        to: string;
+        mediaUrl?: string;
+        accountId?: string | null;
+        account?: ResolvedCustomAccount;
+      }) => {
+        const account: ResolvedCustomAccount =
+          ctxAccount ?? resolveAccount({}, accountId);
+
+        if (!account.incomingUrl) {
+          throw new Error("Custom channel incoming URL not configured");
+        }
+        if (!mediaUrl) {
+          throw new Error("No media URL provided");
+        }
+
+        const { sendFileUrl } = await import("./client.js");
+        const ok = await sendFileUrl(
+          account.incomingUrl,
+          mediaUrl,
+          to,
+          account.allowInsecureSsl,
+        );
+        if (!ok) {
+          throw new Error("Failed to send media to Custom channel");
+        }
+        return { channel: CHANNEL_ID, messageId: `custom-${Date.now()}`, chatId: to };
+      },
+    },
+
+    gateway: {
+      startAccount: async (ctx: {
+        cfg: unknown;
+        accountId: string;
+        account: ResolvedCustomAccount;
+        log?: { info?: (msg: string) => void; warn?: (msg: string) => void };
+      }) => {
+        const { cfg, accountId, log } = ctx;
+        const account = resolveAccount(cfg, accountId);
+
+        if (!account.enabled) {
+          log?.info?.(`Custom account ${accountId} is disabled, skipping`);
+          return { stop: () => {} };
+        }
+
+        if (!account.token && account.dmPolicy !== "open") {
+          log?.warn?.(
+            `Custom account ${accountId} has no token; webhook validation disabled`,
+          );
+        }
+        if (!account.incomingUrl) {
+          log?.warn?.(
+            `Custom account ${accountId} incomingUrl not configured; replies will fail`,
+          );
+        }
+        if (
+          account.dmPolicy === "allowlist" &&
+          account.allowedUserIds.length === 0
+        ) {
+          log?.warn?.(
+            `Custom account ${accountId} dmPolicy=allowlist but empty allowFrom; refusing to start`,
+          );
+          return { stop: () => {} };
+        }
+
+        log?.info?.(
+          `Starting Custom channel (account: ${accountId}, path: ${account.webhookPath})`,
+        );
+
+        const handler = createWebhookHandler({
+          account,
+          deliver: async (msg) => {
+            const rt = getCustomRuntime();
+            const currentCfg = await rt.config.loadConfig();
+
+            const targetTo = msg.groupId ?? msg.from;
+
+            const msgCtx = {
+              Body: msg.body,
+              From: msg.from,
+              To: account.botName,
+              SessionKey: msg.sessionKey,
+              AccountId: account.accountId,
+              OriginatingChannel: CHANNEL_ID,
+              OriginatingTo: targetTo,
+              ChatType: msg.chatType,
+              SenderName: msg.senderName,
+            };
+
+            await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+              ctx: msgCtx,
+              cfg: currentCfg,
+              dispatcherOptions: {
+                deliver: async (payload: { text?: string; body?: string }) => {
+                  const text = payload?.text ?? payload?.body;
+                  if (text && account.incomingUrl) {
+                    await sendMessage(
+                      account.incomingUrl,
+                      text,
+                      targetTo,
+                      account.allowInsecureSsl,
+                      msg.chatType === "group" ? "group" : "direct",
+                    );
+                  }
+                },
+                onReplyStart: () => {
+                  log?.info?.(`Agent reply started for ${msg.from}`);
+                },
+              },
+            });
+          },
+          log,
+        });
+
+        const routeKey = `${accountId}:${account.webhookPath}`;
+        const prevUnregister = activeRouteUnregisters.get(routeKey);
+        if (prevUnregister) {
+          log?.info?.(`Deregistering stale route before re-registering: ${account.webhookPath}`);
+          prevUnregister();
+          activeRouteUnregisters.delete(routeKey);
+        }
+
+        const unregister = registerPluginHttpRoute({
+          path: account.webhookPath,
+          pluginId: CHANNEL_ID,
+          accountId: account.accountId,
+          log: (msg: string) => log?.info?.(msg),
+          handler,
+        });
+        activeRouteUnregisters.set(routeKey, unregister);
+
+        log?.info?.(`Registered HTTP route: ${account.webhookPath} for Custom channel`);
+
+        return {
+          stop: () => {
+            log?.info?.(`Stopping Custom channel (account: ${accountId})`);
+            if (typeof unregister === "function") unregister();
+            activeRouteUnregisters.delete(routeKey);
+          },
+        };
+      },
+
+      stopAccount: async (ctx: { accountId: string; log?: { info?: (msg: string) => void } }) => {
+        ctx.log?.info?.(`Custom account ${ctx.accountId} stopped`);
+      },
+    },
+
+    agentPrompt: {
+      messageToolHints: () => [
+        "",
+        "### Custom Channel",
+        "Adapt formatting hints to your backend. Default: plain text.",
+        "Use JSON payload for outbound: { to, text, chatType }.",
+        "",
+      ],
+    },
+  };
+}

package/src/client.ts

@@ -0,0 +1,113 @@
+/**
+ * HTTP client for sending messages to your custom backend.
+ *
+ * Sends JSON payload to the incomingUrl. Adapt the payload format to match
+ * your backend's API (e.g. { to, text } or { userId, message }).
+ */
+
+import * as http from "node:http";
+import * as https from "node:https";
+
+const MIN_SEND_INTERVAL_MS = 200;
+let lastSendTime = 0;
+
+export interface SendPayload {
+  to: string;
+  text: string;
+  chatType?: "direct" | "group";
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function doPost(url: string, body: string, allowInsecureSsl: boolean): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    let parsedUrl: URL;
+    try {
+      parsedUrl = new URL(url);
+    } catch {
+      reject(new Error(`Invalid URL: ${url}`));
+      return;
+    }
+    const transport = parsedUrl.protocol === "https:" ? https : http;
+
+    const req = transport.request(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(body),
+        },
+        timeout: 30_000,
+        rejectUnauthorized: !allowInsecureSsl,
+      },
+      (res) => {
+        res.on("data", () => {});
+        res.on("end", () => {
+          resolve(res.statusCode === 200 || res.statusCode === 201);
+        });
+      },
+    );
+
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("Request timeout"));
+    });
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Send a text message to the custom backend.
+ * Payload format: { to, text, chatType }. Adjust to match your API.
+ */
+export async function sendMessage(
+  incomingUrl: string,
+  text: string,
+  to: string,
+  allowInsecureSsl = false,
+  chatType: "direct" | "group" = "direct",
+): Promise<boolean> {
+  const now = Date.now();
+  const elapsed = now - lastSendTime;
+  if (elapsed < MIN_SEND_INTERVAL_MS) {
+    await sleep(MIN_SEND_INTERVAL_MS - elapsed);
+  }
+
+  const payload: SendPayload = { to, text, chatType };
+  const body = JSON.stringify(payload);
+
+  try {
+    const ok = await doPost(incomingUrl, body, allowInsecureSsl);
+    lastSendTime = Date.now();
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Send media (file URL) to the custom backend.
+ * Extend payload as needed for your API.
+ */
+export async function sendFileUrl(
+  incomingUrl: string,
+  fileUrl: string,
+  to: string,
+  allowInsecureSsl = false,
+): Promise<boolean> {
+  const payload = { to, fileUrl, chatType: "direct" as const };
+  const body = JSON.stringify(payload);
+
+  try {
+    const ok = await doPost(incomingUrl, body, allowInsecureSsl);
+    lastSendTime = Date.now();
+    return ok;
+  } catch {
+    return false;
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,19 @@
+/**
+ * Plugin runtime singleton.
+ * Stores the PluginRuntime from api.runtime (set during register()).
+ */
+
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setCustomRuntime(r: PluginRuntime): void {
+  runtime = r;
+}
+
+export function getCustomRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Custom channel runtime not initialized - plugin not registered");
+  }
+  return runtime;
+}

package/src/security.ts

@@ -0,0 +1,114 @@
+/**
+ * Security: token validation, rate limiting, input sanitization, user allowlist.
+ */
+
+import * as crypto from "node:crypto";
+
+export type DmAuthorizationResult =
+  | { allowed: true }
+  | { allowed: false; reason: "disabled" | "allowlist-empty" | "not-allowlisted" };
+
+export function validateToken(received: string, expected: string): boolean {
+  if (!received || !expected) return false;
+  const key = "openclaw-token-cmp";
+  const a = crypto.createHmac("sha256", key).update(received).digest();
+  const b = crypto.createHmac("sha256", key).update(expected).digest();
+  return crypto.timingSafeEqual(a, b);
+}
+
+export function checkUserAllowed(userId: string, allowedUserIds: string[]): boolean {
+  if (allowedUserIds.length === 0) return false;
+  return allowedUserIds.includes(userId);
+}
+
+export function authorizeUserForDm(
+  userId: string,
+  dmPolicy: "open" | "allowlist" | "pairing" | "disabled",
+  allowedUserIds: string[],
+): DmAuthorizationResult {
+  if (dmPolicy === "disabled") {
+    return { allowed: false, reason: "disabled" };
+  }
+  if (dmPolicy === "open") {
+    return { allowed: true };
+  }
+  if (allowedUserIds.length === 0) {
+    return { allowed: false, reason: "allowlist-empty" };
+  }
+  if (!checkUserAllowed(userId, allowedUserIds)) {
+    return { allowed: false, reason: "not-allowlisted" };
+  }
+  return { allowed: true };
+}
+
+export function sanitizeInput(text: string): string {
+  const dangerousPatterns = [
+    /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?)/gi,
+    /you\s+are\s+now\s+/gi,
+    /system:\s*/gi,
+    /<\|.*?\|>/g,
+  ];
+
+  let sanitized = text;
+  for (const pattern of dangerousPatterns) {
+    sanitized = sanitized.replace(pattern, "[FILTERED]");
+  }
+
+  const maxLength = 4000;
+  if (sanitized.length > maxLength) {
+    sanitized = sanitized.slice(0, maxLength) + "... [truncated]";
+  }
+
+  return sanitized;
+}
+
+export class RateLimiter {
+  private requests = new Map<string, number[]>();
+  private limit: number;
+  private windowMs: number;
+  private lastCleanup = 0;
+  private cleanupIntervalMs: number;
+
+  constructor(limit = 30, windowSeconds = 60) {
+    this.limit = limit;
+    this.windowMs = windowSeconds * 1000;
+    this.cleanupIntervalMs = this.windowMs * 5;
+  }
+
+  check(userId: string): boolean {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+
+    if (now - this.lastCleanup > this.cleanupIntervalMs) {
+      this.cleanup(windowStart);
+      this.lastCleanup = now;
+    }
+
+    let timestamps = this.requests.get(userId);
+    if (timestamps) {
+      timestamps = timestamps.filter((ts) => ts > windowStart);
+    } else {
+      timestamps = [];
+    }
+
+    if (timestamps.length >= this.limit) {
+      this.requests.set(userId, timestamps);
+      return false;
+    }
+
+    timestamps.push(now);
+    this.requests.set(userId, timestamps);
+    return true;
+  }
+
+  private cleanup(windowStart: number): void {
+    for (const [userId, timestamps] of this.requests) {
+      const active = timestamps.filter((ts) => ts > windowStart);
+      if (active.length === 0) {
+        this.requests.delete(userId);
+      } else {
+        this.requests.set(userId, active);
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Type definitions for the Custom channel plugin.
+ *
+ * Adapt these types to match your backend's webhook payload and config.
+ */
+
+/** Raw channel config from openclaw.json channels.custom */
+export interface CustomChannelConfig {
+  enabled?: boolean;
+  token?: string;
+  incomingUrl?: string;
+  webhookPath?: string;
+  dmPolicy?: "open" | "allowlist" | "pairing" | "disabled";
+  allowFrom?: string | string[];
+  rateLimitPerMinute?: number;
+  botName?: string;
+  allowInsecureSsl?: boolean;
+  accounts?: Record<string, CustomAccountRaw>;
+}
+
+/** Raw per-account config (overrides base config) */
+export interface CustomAccountRaw {
+  enabled?: boolean;
+  token?: string;
+  incomingUrl?: string;
+  webhookPath?: string;
+  dmPolicy?: "open" | "allowlist" | "pairing" | "disabled";
+  allowFrom?: string | string[];
+  rateLimitPerMinute?: number;
+  botName?: string;
+  allowInsecureSsl?: boolean;
+}
+
+/** Fully resolved account config with defaults applied */
+export interface ResolvedCustomAccount {
+  accountId: string;
+  enabled: boolean;
+  token: string;
+  incomingUrl: string;
+  webhookPath: string;
+  dmPolicy: "open" | "allowlist" | "pairing" | "disabled";
+  allowedUserIds: string[];
+  rateLimitPerMinute: number;
+  botName: string;
+  allowInsecureSsl: boolean;
+}
+
+/**
+ * Webhook payload format from your backend.
+ * Customize fields to match your chat system's webhook schema.
+ */
+export interface CustomWebhookPayload {
+  token?: string;
+  userId: string;
+  userName?: string;
+  groupId?: string;
+  groupName?: string;
+  text: string;
+  chatType?: "direct" | "group";
+}

package/src/webhook-handler.ts

@@ -0,0 +1,204 @@
+/**
+ * Inbound webhook handler for the Custom channel.
+ *
+ * Expects JSON body with: { userId, userName?, groupId?, groupName?, text, chatType? }
+ * Optional: token for validation.
+ *
+ * Customize parsePayload() to match your backend's webhook format.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  validateToken,
+  authorizeUserForDm,
+  sanitizeInput,
+  RateLimiter,
+} from "./security.js";
+import type { CustomWebhookPayload, ResolvedCustomAccount } from "./types.js";
+
+const rateLimiters = new Map<string, RateLimiter>();
+
+function getRateLimiter(account: ResolvedCustomAccount): RateLimiter {
+  let rl = rateLimiters.get(account.accountId);
+  if (!rl) {
+    rl = new RateLimiter(account.rateLimitPerMinute);
+    rateLimiters.set(account.accountId, rl);
+  }
+  return rl;
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    const maxSize = 1_048_576;
+
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > maxSize) {
+        req.destroy();
+        reject(new Error("Request body too large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+function parsePayload(body: string): CustomWebhookPayload | null {
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(body) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  const userId = String(parsed.userId ?? "").trim();
+  const text = String(parsed.text ?? "").trim();
+
+  if (!userId || !text) return null;
+
+  const chatType =
+    parsed.chatType === "group" ? "group" : "direct";
+  const groupId = parsed.groupId ? String(parsed.groupId) : undefined;
+  const groupName = parsed.groupName ? String(parsed.groupName) : undefined;
+
+  return {
+    token: parsed.token ? String(parsed.token) : undefined,
+    userId,
+    userName: parsed.userName ? String(parsed.userName) : undefined,
+    groupId,
+    groupName,
+    text,
+    chatType,
+  };
+}
+
+function respond(res: ServerResponse, statusCode: number, body: Record<string, unknown>): void {
+  res.writeHead(statusCode, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+export interface WebhookHandlerDeps {
+  account: ResolvedCustomAccount;
+  /** Deliver to agent; replies are sent via dispatcherOptions.deliver inside. */
+  deliver: (msg: {
+    body: string;
+    from: string;
+    senderName: string;
+    chatType: string;
+    sessionKey: string;
+    accountId: string;
+    groupId?: string;
+    groupName?: string;
+  }) => Promise<void>;
+  log?: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+  };
+}
+
+export function createWebhookHandler(deps: WebhookHandlerDeps) {
+  const { account, deliver, log } = deps;
+  const rateLimiter = getRateLimiter(account);
+
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (req.method !== "POST") {
+      respond(res, 405, { error: "Method not allowed" });
+      return;
+    }
+
+    let body: string;
+    try {
+      body = await readBody(req);
+    } catch (err) {
+      log?.error?.("Failed to read request body", err);
+      respond(res, 400, { error: "Invalid request body" });
+      return;
+    }
+
+    const payload = parsePayload(body);
+    if (!payload) {
+      respond(res, 400, { error: "Missing required fields (userId, text)" });
+      return;
+    }
+
+    if (account.token && payload.token && !validateToken(payload.token, account.token)) {
+      log?.warn?.(`Invalid token from ${req.socket?.remoteAddress}`);
+      respond(res, 401, { error: "Invalid token" });
+      return;
+    }
+
+    const auth = authorizeUserForDm(
+      payload.userId,
+      account.dmPolicy,
+      account.allowedUserIds,
+    );
+    if (!auth.allowed) {
+      if (auth.reason === "disabled") {
+        respond(res, 403, { error: "DMs are disabled" });
+        return;
+      }
+      if (auth.reason === "allowlist-empty") {
+        log?.warn?.("Custom channel allowlist is empty while dmPolicy=allowlist");
+        respond(res, 403, {
+          error: "Allowlist is empty. Configure allowFrom or use dmPolicy=open.",
+        });
+        return;
+      }
+      log?.warn?.(`Unauthorized user: ${payload.userId}`);
+      respond(res, 403, { error: "User not authorized" });
+      return;
+    }
+
+    if (!rateLimiter.check(payload.userId)) {
+      log?.warn?.(`Rate limit exceeded for user: ${payload.userId}`);
+      respond(res, 429, { error: "Rate limit exceeded" });
+      return;
+    }
+
+    const cleanText = sanitizeInput(payload.text);
+    if (!cleanText) {
+      respond(res, 200, { ok: true });
+      return;
+    }
+
+    const preview = cleanText.length > 100 ? `${cleanText.slice(0, 100)}...` : cleanText;
+    log?.info?.(`Message from ${payload.userName ?? payload.userId} (${payload.userId}): ${preview}`);
+
+    respond(res, 200, { ok: true, message: "Processing..." });
+
+    const sessionKey = payload.groupId
+      ? `custom-${payload.groupId}-${payload.userId}`
+      : `custom-${payload.userId}`;
+
+    try {
+      await deliver({
+        body: cleanText,
+        from: payload.userId,
+        senderName: payload.userName ?? payload.userId,
+        chatType: payload.chatType ?? "direct",
+        sessionKey,
+        accountId: account.accountId,
+        groupId: payload.groupId,
+        groupName: payload.groupName,
+      });
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      log?.error?.(`Failed to process message: ${errMsg}`);
+      if (account.incomingUrl) {
+        const { sendMessage } = await import("./client.js");
+        await sendMessage(
+          account.incomingUrl,
+          "Sorry, an error occurred while processing your message.",
+          payload.groupId ?? payload.userId,
+          account.allowInsecureSsl,
+          payload.chatType ?? "direct",
+        );
+      }
+    }
+  };
+}