@pipes.bot/pipes-bot-channel 0.1.0

package/index.ts

@@ -0,0 +1,21 @@
+import { createPipesBotService } from "./src/service.js";
+import { setPipesBotRuntime } from "./src/runtime.js";
+import { pipesBotChannelPlugin } from "./src/channel.js";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+
+const plugin = {
+  id: "pipes-bot-channel",
+  name: "PipesBot Channel",
+  description: "WhatsApp channel via PipesBot managed proxy",
+  configSchema: emptyPluginConfigSchema(),
+
+  register(api: OpenClawPluginApi): void {
+    setPipesBotRuntime(api.runtime);
+    api.registerChannel({ plugin: pipesBotChannelPlugin });
+    api.registerService(createPipesBotService());
+    api.logger.info("pipes-bot-channel: registered");
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "pipes-bot-channel",
+  "channels": ["pipes-bot"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^pk_"
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "PipesBot API Key",
+      "sensitive": true,
+      "placeholder": "pk_..."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@pipes.bot/pipes-bot-channel",
+  "version": "0.1.0",
+  "description": "WhatsApp channel via PipesBot managed proxy (OpenClaw plugin)",
+  "type": "module",
+  "main": "index.ts",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "openclaw": "*",
+    "typescript": "^5.0.0"
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "openclaw.plugin.json"
+  ]
+}

package/src/channel.ts

@@ -0,0 +1,42 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+import { getConnectionStatus } from "./status-store.js";
+
+export const pipesBotChannelPlugin: ChannelPlugin = {
+  id: "pipes-bot-channel",
+
+  meta: {
+    id: "pipes-bot-channel",
+    label: "PipesBot (WhatsApp)",
+    selectionLabel: "PipesBot (WhatsApp)",
+    docsPath: "/docs/channels/pipes-bot",
+    blurb: "WhatsApp via PipesBot managed proxy",
+  },
+
+  capabilities: {
+    chatTypes: ["direct"],
+    media: true,
+  },
+
+  config: {
+    listAccountIds: () => ["default"],
+    resolveAccount: () => ({ apiKey: "configured" }),
+    isConfigured: () => true,
+  },
+
+  status: {
+    defaultRuntime: { accountId: "default", connected: false, lastError: null },
+
+    buildAccountSnapshot: ({ runtime }) => {
+      const status = getConnectionStatus();
+      return {
+        accountId: "default",
+        connected: status.connected,
+        running: !status.authFailed,
+        lastConnectedAt: status.lastConnectedAt,
+        lastError: status.authFailed
+          ? "Authentication failed -- check your pk_ API key"
+          : (status.lastError ?? runtime?.lastError ?? null),
+      };
+    },
+  },
+};

package/src/connection.ts

@@ -0,0 +1,204 @@
+import WebSocket from "ws";
+import { EventEmitter } from "node:events";
+import type { OpenClawPluginServiceContext } from "openclaw/plugin-sdk";
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const BASE_MS = 1_000;
+const MAX_MS = 120_000; // 2 min cap (user decision)
+const PING_INTERVAL_MS = 25_000;
+const PONG_TIMEOUT_MS = 50_000; // 75s total with ping interval = WS-03
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type ConnectionState = "connected" | "disconnected" | "reconnecting";
+
+type PluginLogger = OpenClawPluginServiceContext["logger"];
+
+// ── Module-level helpers ─────────────────────────────────────────────────────
+
+function computeBackoffDelay(attempt: number): number {
+  return Math.floor(Math.random() * Math.min(MAX_MS, BASE_MS * Math.pow(2, attempt)));
+}
+
+function buildWsUrl(apiKey: string): string {
+  return `wss://api.pipes.bot/ws?apiKey=${encodeURIComponent(apiKey)}`;
+}
+
+// ── PipesBotConnection ───────────────────────────────────────────────────────
+
+export class PipesBotConnection extends EventEmitter {
+  private readonly apiKey: string;
+  private readonly logger: PluginLogger;
+
+  private state: ConnectionState = "disconnected";
+  private ws: WebSocket | null = null;
+  private shouldReconnect = false;
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private pongTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(apiKey: string, logger: PluginLogger) {
+    super();
+    this.apiKey = apiKey;
+    this.logger = logger;
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  connect(): void {
+    this.shouldReconnect = true;
+    this.doConnect();
+  }
+
+  disconnect(): void {
+    // Ordered teardown -- shouldReconnect must be false before ws.close()
+    // so the close handler does not schedule a reconnect.
+    this.shouldReconnect = false;
+    this.stopHeartbeat();
+
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    if (this.ws !== null) {
+      this.ws.close(1000);
+      this.ws = null;
+    }
+
+    this.setState("disconnected");
+  }
+
+  send(message: object): boolean {
+    if (this.state !== "connected" || this.ws === null) {
+      return false;
+    }
+    this.ws.send(JSON.stringify(message));
+    return true;
+  }
+
+  getState(): ConnectionState {
+    return this.state;
+  }
+
+  // ── Private methods ────────────────────────────────────────────────────────
+
+  private doConnect(): void {
+    const ws = new WebSocket(buildWsUrl(this.apiKey), {
+      handshakeTimeout: 10_000,
+    });
+    this.ws = ws;
+
+    ws.on("unexpected-response", (_req, response) => {
+      const { statusCode } = response;
+
+      if (statusCode === 401 || statusCode === 403) {
+        // Permanent auth failure -- stop reconnecting
+        this.shouldReconnect = false;
+        this.logger.error(
+          `pipes-bot-channel: WebSocket authentication failed (HTTP ${statusCode}) -- stopping`
+        );
+        this.emit("error", new Error(`WebSocket auth failed: HTTP ${statusCode}`));
+      } else {
+        // Transient failure -- let close handler schedule reconnect
+        this.logger.warn(
+          `pipes-bot-channel: WebSocket upgrade failed (HTTP ${statusCode}) -- will reconnect`
+        );
+      }
+    });
+
+    ws.on("open", () => {
+      this.reconnectAttempts = 0;
+      this.setState("connected");
+      this.startHeartbeat(ws);
+      this.logger.info("pipes-bot-channel: WebSocket connected");
+    });
+
+    ws.on("message", (data) => {
+      try {
+        const parsed = JSON.parse(data.toString()) as object;
+        this.emit("message", parsed);
+      } catch {
+        this.logger.warn("pipes-bot-channel: received non-JSON WebSocket message -- ignoring");
+      }
+    });
+
+    ws.on("error", (err) => {
+      // Log only -- the close event fires next and handles reconnect scheduling
+      this.logger.error(`pipes-bot-channel: WebSocket error: ${err.message}`);
+    });
+
+    ws.on("close", () => {
+      this.stopHeartbeat();
+      this.ws = null;
+
+      if (this.shouldReconnect) {
+        this.scheduleReconnect();
+      } else {
+        this.setState("disconnected");
+      }
+    });
+  }
+
+  private scheduleReconnect(): void {
+    this.setState("reconnecting");
+    this.reconnectAttempts += 1;
+    const delay = computeBackoffDelay(this.reconnectAttempts);
+    this.logger.info(
+      `pipes-bot-channel: reconnect attempt ${this.reconnectAttempts} in ${delay}ms`
+    );
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.doConnect();
+    }, delay);
+  }
+
+  private setState(next: ConnectionState): void {
+    if (this.state === next) return;
+    this.state = next;
+    this.emit("state", next);
+
+    if (next === "connected" || next === "disconnected") {
+      this.logger.info(`pipes-bot-channel: state -> ${next}`);
+    }
+    // reconnecting state is logged in scheduleReconnect with attempt details
+  }
+
+  private startHeartbeat(ws: WebSocket): void {
+    this.pingTimer = setInterval(() => {
+      ws.ping();
+
+      if (this.pongTimer !== null) {
+        clearTimeout(this.pongTimer);
+      }
+      this.pongTimer = setTimeout(() => {
+        this.logger.error(
+          "pipes-bot-channel: pong timeout -- terminating dead connection"
+        );
+        // ws.terminate() forces close code 1006 (abnormal closure)
+        ws.terminate();
+      }, PONG_TIMEOUT_MS);
+    }, PING_INTERVAL_MS);
+
+    ws.on("pong", () => {
+      if (this.pongTimer !== null) {
+        clearTimeout(this.pongTimer);
+        this.pongTimer = null;
+      }
+    });
+  }
+
+  private stopHeartbeat(): void {
+    if (this.pingTimer !== null) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+    if (this.pongTimer !== null) {
+      clearTimeout(this.pongTimer);
+      this.pongTimer = null;
+    }
+  }
+}

package/src/inbound.ts

@@ -0,0 +1,245 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { buildAgentMediaPayload, toLocationContext, type NormalizedLocation } from "openclaw/plugin-sdk";
+import { getPipesBotRuntime } from "./runtime.js";
+import { downloadPipesBotMedia } from "./media.js";
+import {
+  isPipesBotMessage,
+  type PluginLogger,
+  type PipesBotContact,
+  type PipesBotMessageData,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Public export
+// ---------------------------------------------------------------------------
+
+export async function handleInbound(
+  msg: unknown,
+  opts: {
+    apiKey: string;
+    accountId: string;
+    send: (payload: object) => boolean;
+    logger: PluginLogger;
+  },
+): Promise<void> {
+  // 1. Type guard — reject anything that isn't a whatsapp_message envelope
+  if (!isPipesBotMessage(msg)) return;
+  const data = msg.data;
+
+  const core = getPipesBotRuntime();
+  const cfg = core.config.loadConfig() as OpenClawConfig;
+  const { apiKey, accountId, send, logger } = opts;
+
+  // 2. Skip unsupported message types
+  if (data.type === "unsupported") return;
+
+  // 3. Skip reaction removals (no emoji present)
+  if (data.type === "reaction" && !data.reaction?.emoji) return;
+
+  // 4. Resolve body text
+  const rawBody = resolveRawBody(data);
+  const body = rawBody;
+
+  // 5. Download media for media message types
+  const mediaPayload = await resolveMediaPayload(data, apiKey, logger, core);
+
+  // 6. Save contacts as VCF if this is a contacts message
+  const contactsPayload =
+    data.type === "contacts" && data.contacts && data.contacts.length > 0
+      ? await resolveContactsPayload(data.contacts, core)
+      : {};
+
+  // 7. Location context
+  const locationCtx = resolveLocationCtx(data);
+
+  // 8. ReplyToId (reactions only)
+  const replyToId =
+    data.type === "reaction" ? data.reaction?.messageId : undefined;
+
+  // 9. SessionKey — prefixed with accountId for multi-account safety
+  const sessionKey = `${accountId}:${data.conversationId}`;
+
+  // 10. Resolve agent route
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "pipes-bot-channel",
+    accountId,
+    peer: { kind: "direct", id: data.conversationId },
+  });
+
+  // 11. Resolve session store path
+  const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: route.agentId,
+  });
+
+  // 12. Finalize inbound context — normalizes Body, sets BodyForAgent, etc.
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: `pipes-bot-channel:${data.fromNumber}`,
+    To: `pipes-bot-channel:${data.poolNumberPhoneNumber}`,
+    SessionKey: sessionKey,
+    AccountId: accountId,
+    ChatType: "direct" as const,
+    SenderName: data.fromName ?? undefined,
+    SenderId: data.fromNumber,
+    Provider: "pipes-bot-channel",
+    Surface: "pipes-bot-channel",
+    MessageSid: data.messageId,
+    Timestamp: new Date(data.timestamp).getTime(),
+    ConversationLabel: data.fromName ?? data.fromNumber,
+    ReplyToId: replyToId,
+    OriginatingChannel: "pipes-bot-channel",
+    OriginatingTo: `pipes-bot-channel:${data.conversationId}`,
+    ...mediaPayload,
+    ...contactsPayload,
+    ...locationCtx,
+  });
+
+  // 13. Record inbound session for multi-turn context
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => {
+      logger.error(`pipes-bot-channel: session record failed: ${String(err)}`);
+    },
+  });
+
+  // 14. Dispatch to agent pipeline
+  //     Uses dispatchReplyWithBufferedBlockDispatcher — simpler than the
+  //     createReplyDispatcherWithTyping pattern because PipesBot has no
+  //     typing indicator API (typing callbacks are no-ops).
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg,
+    dispatcherOptions: {
+      deliver: async (payload) => {
+        const sent = send({
+          type: "whatsapp_reply",
+          data: {
+            conversationId: data.conversationId,
+            poolNumberId: data.poolNumberId,
+            toNumber: data.fromNumber,
+            text: payload.text ?? "",
+          },
+        });
+        if (!sent) {
+          logger.warn(
+            `pipes-bot-channel: send returned false (disconnected?) for conversation ${data.conversationId}`,
+          );
+        }
+      },
+      onError: (err, info) => {
+        logger.error(
+          `pipes-bot-channel: ${info.kind} reply failed: ${String(err)}`,
+        );
+      },
+    },
+    replyOptions: {},
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve the text body for each message type. */
+function resolveRawBody(data: PipesBotMessageData): string {
+  switch (data.type) {
+    case "text":
+      return data.body;
+    case "reaction":
+      // Emoji is guaranteed non-null here (removals are skipped upstream)
+      return data.reaction?.emoji ?? "";
+    case "location":
+    case "contacts":
+      // Body stays empty — structured data is in locationCtx / contactsPayload
+      return "";
+    default:
+      // image, audio, video, document, sticker — caption or empty
+      return data.body ?? "";
+  }
+}
+
+/** Download media for image/audio/video/document/sticker message types. */
+async function resolveMediaPayload(
+  data: PipesBotMessageData,
+  apiKey: string,
+  logger: PluginLogger,
+  _core: ReturnType<typeof getPipesBotRuntime>,
+): Promise<ReturnType<typeof buildAgentMediaPayload>> {
+  const mediaTypes: Array<
+    "image" | "audio" | "video" | "document" | "sticker"
+  > = ["image", "audio", "video", "document", "sticker"];
+  if (!mediaTypes.includes(data.type as never)) return {};
+
+  if (!data.media || data.media.unavailable || !data.media.downloadUrl) {
+    if (data.media?.unavailable) {
+      logger.warn(
+        `pipes-bot-channel: media unavailable for message ${data.messageId} — proceeding as text-only`,
+      );
+    }
+    return {};
+  }
+
+  const result = await downloadPipesBotMedia({
+    downloadUrl: data.media.downloadUrl,
+    mimeType: data.media.mimeType,
+    fileName: data.media.fileName,
+    apiKey,
+    logger,
+  });
+
+  if (!result) return {};
+
+  return buildAgentMediaPayload([
+    { path: result.path, contentType: result.contentType },
+  ]);
+}
+
+/** Save contacts array as a VCF file and return an agent media payload. */
+async function resolveContactsPayload(
+  contacts: PipesBotContact[],
+  core: ReturnType<typeof getPipesBotRuntime>,
+): Promise<ReturnType<typeof buildAgentMediaPayload>> {
+  const vcard = contacts.map(formatVCard).join("\n");
+  const saved = await core.channel.media.saveMediaBuffer(
+    Buffer.from(vcard, "utf-8"),
+    "text/vcard",
+    "inbound",
+  );
+  return buildAgentMediaPayload([
+    { path: saved.path, contentType: "text/vcard" },
+  ]);
+}
+
+/**
+ * Convert a location message to OpenClaw's structured location context fields.
+ * Returns an empty object for non-location types.
+ */
+function resolveLocationCtx(
+  data: PipesBotMessageData,
+): ReturnType<typeof toLocationContext> | Record<string, never> {
+  if (data.type !== "location" || !data.location) return {};
+  const loc: NormalizedLocation = {
+    latitude: data.location.latitude,
+    longitude: data.location.longitude,
+    name: data.location.name,
+    address: data.location.address,
+  };
+  return toLocationContext(loc);
+}
+
+/** Format a single contact as a vCard 3.0 string. */
+function formatVCard(contact: PipesBotContact): string {
+  const name = contact.name?.formatted_name ?? "Unknown";
+  const phones = (contact.phones ?? [])
+    .map((p) => `TEL;TYPE=${p.type ?? "CELL"}:${p.phone}`)
+    .join("\n");
+  const lines = ["BEGIN:VCARD", "VERSION:3.0", `FN:${name}`];
+  if (phones) lines.push(phones);
+  lines.push("END:VCARD");
+  return lines.join("\n");
+}

package/src/media.ts

@@ -0,0 +1,43 @@
+import { getPipesBotRuntime } from "./runtime.js";
+import type { PluginLogger } from "./types.js";
+
+const PIPES_BOT_API_BASE = "https://api.pipes.bot";
+
+export async function downloadPipesBotMedia(params: {
+  downloadUrl: string;
+  mimeType: string;
+  fileName?: string;
+  apiKey: string;
+  logger: PluginLogger;
+}): Promise<{ path: string; contentType: string } | null> {
+  const core = getPipesBotRuntime();
+  const absoluteUrl = `${PIPES_BOT_API_BASE}${params.downloadUrl}`;
+
+  try {
+    const fetched = await core.channel.media.fetchRemoteMedia({
+      url: absoluteUrl,
+      fetchImpl: (input, init) => {
+        const headers = new Headers((init?.headers as HeadersInit | undefined) ?? undefined);
+        headers.set("Authorization", `Bearer ${params.apiKey}`);
+        return fetch(input, { ...init, headers });
+      },
+      filePathHint: params.fileName,
+    });
+
+    const saved = await core.channel.media.saveMediaBuffer(
+      fetched.buffer,
+      fetched.contentType ?? params.mimeType,
+      "inbound",
+    );
+
+    return {
+      path: saved.path,
+      contentType: saved.contentType ?? params.mimeType,
+    };
+  } catch (err) {
+    params.logger.error(
+      `pipes-bot-channel: media download failed for ${params.downloadUrl}: ${String(err)}`,
+    );
+    return null;
+  }
+}

package/src/outbound.ts

@@ -0,0 +1,114 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import { isPipesBotReplyStatus } from "./types.js";
+import type { PluginLogger } from "./types.js";
+
+// ── Failure classification ────────────────────────────────────────────────────
+
+export type ReplyFailureKind =
+  | "SERVICE_WINDOW_EXPIRED"
+  | "RATE_LIMITED"
+  | "FORBIDDEN"
+  | "NOT_FOUND"
+  | "SEND_FAILED"
+  | "UNKNOWN";
+
+// ── Pending reply tracking ────────────────────────────────────────────────────
+
+type PendingReply = {
+  conversationId: string;
+  trackedAt: number;
+  expiresAt: number;
+};
+
+const PENDING_TTL_MS = 30_000; // 30 seconds
+
+const pendingReplies = new Map<string, PendingReply>();
+
+/**
+ * Track an outbound reply for reply_status correlation.
+ * Performs lazy eviction of expired entries on each call.
+ */
+export function trackOutboundReply(conversationId: string): void {
+  // Lazy eviction of expired entries
+  const now = Date.now();
+  for (const [key, entry] of pendingReplies) {
+    if (now > entry.expiresAt) {
+      pendingReplies.delete(key);
+    }
+  }
+
+  pendingReplies.set(conversationId, {
+    conversationId,
+    trackedAt: now,
+    expiresAt: now + PENDING_TTL_MS,
+  });
+}
+
+// ── Reply status handler ──────────────────────────────────────────────────────
+
+/**
+ * Handle a reply_status event from PipesBot.
+ * - Logs success events
+ * - Classifies and logs failure events
+ * - Enqueues agent-facing system event for SERVICE_WINDOW_EXPIRED failures
+ */
+export function handleReplyStatus(
+  msg: unknown,
+  opts: { logger: PluginLogger; core: PluginRuntime }
+): void {
+  if (!isPipesBotReplyStatus(msg)) return;
+
+  const { data } = msg;
+
+  // Look up and remove pending entry (we no longer need it after reply_status)
+  const pending = pendingReplies.get(data.conversationId);
+  pendingReplies.delete(data.conversationId);
+
+  if (data.success) {
+    opts.logger.info(
+      `pipes-bot-channel: reply delivered to ${data.conversationId} (messageId: ${data.messageId})`
+    );
+    return;
+  }
+
+  // Failure path
+  const kind = classifyReplyFailure(data.code);
+  const message = buildFailureMessage(kind, data.error);
+
+  opts.logger.error(
+    `pipes-bot-channel: reply failed for ${data.conversationId}: [${kind}] ${data.error ?? "unknown error"}`
+  );
+
+  // Enqueue agent-facing system event if we had context for this conversation
+  if (pending && data.conversationId) {
+    opts.core.system.enqueueSystemEvent(message, {
+      sessionKey: `default:${data.conversationId}`,
+    });
+  }
+}
+
+// ── Private helpers ───────────────────────────────────────────────────────────
+
+function classifyReplyFailure(code?: string): ReplyFailureKind {
+  switch (code) {
+    case "SERVICE_WINDOW_EXPIRED":
+      return "SERVICE_WINDOW_EXPIRED";
+    case "RATE_LIMITED":
+      return "RATE_LIMITED";
+    case "FORBIDDEN":
+      return "FORBIDDEN";
+    case "NOT_FOUND":
+      return "NOT_FOUND";
+    case "SEND_FAILED":
+      return "SEND_FAILED";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+function buildFailureMessage(kind: ReplyFailureKind, raw?: string): string {
+  if (kind === "SERVICE_WINDOW_EXPIRED") {
+    return "Unable to send reply: the 24-hour WhatsApp messaging window has expired. The contact must send a new message to reopen the conversation.";
+  }
+  return `Reply failed: ${raw ?? kind}`;
+}

package/src/runtime.ts

@@ -0,0 +1,12 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setPipesBotRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getPipesBotRuntime(): PluginRuntime {
+  if (!runtime) throw new Error("pipes-bot-channel: runtime not initialized");
+  return runtime;
+}

package/src/service.ts

@@ -0,0 +1,88 @@
+import type { OpenClawPluginService, OpenClawPluginServiceContext } from "openclaw/plugin-sdk";
+import { PipesBotConnection } from "./connection.js";
+import { handleInbound } from "./inbound.js";
+import { isPipesBotReplyStatus } from "./types.js";
+import { handleReplyStatus, trackOutboundReply } from "./outbound.js";
+import { getPipesBotRuntime } from "./runtime.js";
+import { updateConnectionStatus } from "./status-store.js";
+import type { ConnectionState } from "./connection.js";
+
+export function createPipesBotService(): OpenClawPluginService {
+  let connection: PipesBotConnection | null = null;
+
+  return {
+    id: "pipes-bot-channel",
+
+    start(ctx: OpenClawPluginServiceContext): void {
+      const pluginConfig = ctx.config.plugins?.entries?.["pipes-bot-channel"]
+        ?.config as { apiKey?: string } | undefined;
+
+      const apiKey = pluginConfig?.apiKey;
+
+      if (!apiKey || !apiKey.startsWith("pk_")) {
+        ctx.logger.error(
+          "pipes-bot-channel: invalid or missing pk_ API key -- not starting"
+        );
+        return;
+      }
+
+      connection = new PipesBotConnection(apiKey, ctx.logger);
+
+      connection.on("state", (state: ConnectionState) => {
+        updateConnectionStatus({
+          connected: state === "connected",
+          ...(state === "connected"
+            ? { lastConnectedAt: Date.now(), lastError: null }
+            : {}),
+        });
+      });
+
+      connection.on("error", (err: Error) => {
+        const isAuthFailure = err.message.includes("auth failed");
+        updateConnectionStatus({
+          connected: false,
+          authFailed: isAuthFailure,
+          lastError: err.message,
+        });
+        ctx.logger.error(`pipes-bot-channel: fatal connection error: ${err.message}`);
+      });
+
+      connection.on("message", (msg: object) => {
+        // Route reply_status events to outbound handler
+        if (isPipesBotReplyStatus(msg)) {
+          handleReplyStatus(msg, { logger: ctx.logger, core: getPipesBotRuntime() });
+          return;
+        }
+
+        // Route whatsapp_message events to inbound handler
+        void handleInbound(msg, {
+          apiKey,
+          accountId: "default",
+          send: (payload: object) => {
+            const sent = connection!.send(payload);
+            if (sent) {
+              // Track outbound for reply_status correlation
+              const replyData = (payload as { data?: { conversationId?: string } }).data;
+              if (replyData?.conversationId) {
+                trackOutboundReply(replyData.conversationId);
+              }
+            }
+            return sent;
+          },
+          logger: ctx.logger,
+        }).catch((err: unknown) => {
+          ctx.logger.error(`pipes-bot-channel: inbound error: ${String(err)}`);
+        });
+      });
+
+      connection.connect();
+    },
+
+    stop(ctx: OpenClawPluginServiceContext): void {
+      connection?.disconnect();
+      connection = null;
+      updateConnectionStatus({ connected: false, authFailed: false, lastError: null });
+      ctx.logger.info("pipes-bot-channel: service stopped");
+    },
+  };
+}

package/src/status-store.ts

@@ -0,0 +1,21 @@
+export type PipesBotConnectionStatus = {
+  connected: boolean;
+  authFailed: boolean;
+  lastConnectedAt: number | null;
+  lastError: string | null;
+};
+
+let _status: PipesBotConnectionStatus = {
+  connected: false,
+  authFailed: false,
+  lastConnectedAt: null,
+  lastError: null,
+};
+
+export function updateConnectionStatus(patch: Partial<PipesBotConnectionStatus>): void {
+  _status = { ..._status, ...patch };
+}
+
+export function getConnectionStatus(): PipesBotConnectionStatus {
+  return { ..._status };
+}

package/src/types.ts

@@ -0,0 +1,113 @@
+import type { OpenClawPluginServiceContext } from "openclaw/plugin-sdk";
+
+// ── PipesBot message media field ─────────────────────────────────────────────
+
+export type PipesBotMedia = {
+  mediaId?: string;
+  downloadUrl?: string;
+  mimeType: string;
+  fileName?: string;
+  byteSize: number;
+  unavailable?: boolean;
+};
+
+// ── PipesBot message location field ──────────────────────────────────────────
+
+export type PipesBotLocation = {
+  latitude: number;
+  longitude: number;
+  name?: string;
+  address?: string;
+};
+
+// ── PipesBot message contacts field ──────────────────────────────────────────
+
+export type PipesBotContact = {
+  name: { formatted_name: string };
+  phones?: Array<{ phone: string; type?: string }>;
+  emails?: Array<{ email: string; type?: string }>;
+};
+
+// ── PipesBot message reaction field ──────────────────────────────────────────
+
+export type PipesBotReaction = {
+  messageId: string;
+  emoji?: string;
+};
+
+// ── PipesBot message data (all fields, type-specific fields optional) ─────────
+
+export type PipesBotMessageData = {
+  messageId: string;
+  conversationId: string;
+  poolNumberId: string;
+  poolNumberPhoneNumber: string;
+  fromNumber: string;
+  fromName?: string;
+  text: string;
+  body: string;
+  timestamp: string;
+  label?: string;
+  type:
+    | "text"
+    | "image"
+    | "audio"
+    | "video"
+    | "document"
+    | "sticker"
+    | "location"
+    | "contacts"
+    | "reaction"
+    | "unsupported";
+  // Type-specific optional fields
+  media?: PipesBotMedia;
+  location?: PipesBotLocation;
+  contacts?: PipesBotContact[];
+  reaction?: PipesBotReaction;
+};
+
+// ── PipesBot message envelope ─────────────────────────────────────────────────
+
+export type PipesBotMessage = {
+  type: "whatsapp_message";
+  data: PipesBotMessageData;
+};
+
+// ── Type guard ────────────────────────────────────────────────────────────────
+
+export function isPipesBotMessage(msg: unknown): msg is PipesBotMessage {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    "type" in msg &&
+    (msg as { type: unknown }).type === "whatsapp_message" &&
+    "data" in msg
+  );
+}
+
+// ── PipesBot reply_status envelope ───────────────────────────────────────────
+
+export type PipesBotReplyStatus = {
+  type: "reply_status";
+  data: {
+    conversationId: string;
+    success: boolean;
+    messageId?: string; // Present on success
+    error?: string; // Present on failure
+    code?: string; // Present on failure
+  };
+};
+
+export function isPipesBotReplyStatus(msg: unknown): msg is PipesBotReplyStatus {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    "type" in msg &&
+    (msg as { type: unknown }).type === "reply_status" &&
+    "data" in msg
+  );
+}
+
+// ── PluginLogger convenience alias ────────────────────────────────────────────
+
+export type PluginLogger = OpenClawPluginServiceContext["logger"];