openclaw-groupme 0.0.1

package/README.md

@@ -0,0 +1,121 @@
+# openclaw-groupme
+
+GroupMe channel plugin for OpenClaw (GroupMe Bot API, group chats only).
+
+## Install
+
+```bash
+openclaw plugins install openclaw-groupme
+```
+
+Restart the gateway after installing the plugin.
+
+## What this plugin needs
+
+1. A GroupMe bot (from https://dev.groupme.com/bots)
+2. A public HTTPS URL that can reach your OpenClaw gateway webhook endpoint
+3. Your GroupMe `bot_id` (required)
+4. Your GroupMe `access token` (recommended, required for image uploads)
+
+## Step-by-step setup
+
+1. Install plugin:
+
+```bash
+openclaw plugins install openclaw-groupme
+```
+
+2. Create a GroupMe bot:
+   - Go to https://dev.groupme.com/bots
+   - Create/select a bot for your target group
+   - Copy the bot's `bot_id`
+   - Copy your GroupMe `access token`
+
+3. Configure OpenClaw:
+   - Option A (interactive):
+
+```bash
+openclaw channels add --channel groupme
+```
+
+   - Option B (manual config): add this under your OpenClaw config:
+
+```json5
+{
+  channels: {
+    groupme: {
+      enabled: true,
+      botId: "YOUR_GROUPME_BOT_ID",
+      accessToken: "YOUR_GROUPME_ACCESS_TOKEN",
+      botName: "openclaw",
+      callbackPath: "/groupme",
+      requireMention: true
+    }
+  }
+}
+```
+
+4. Point GroupMe to your webhook:
+   - Callback URL format: `https://<your-public-domain><callbackPath>`
+   - Example: `https://bot.example.com/groupme`
+   - Set this URL in the GroupMe bot settings
+
+5. Restart OpenClaw gateway:
+
+```bash
+openclaw gateway restart
+```
+
+6. Verify channel status:
+
+```bash
+openclaw channels status --probe
+```
+
+7. Send a test message in the GroupMe group:
+   - With default settings, the bot only responds when mentioned (`requireMention: true`)
+   - Mention either `@<botName>` or a configured mention pattern
+
+## Config reference (common fields)
+
+- `botId` (string, required): GroupMe Bot ID
+- `accessToken` (string): needed for image upload / media replies
+- `botName` (string): mention fallback name used by mention detection
+- `callbackPath` (string, default `/groupme`): webhook route path
+- `requireMention` (boolean, default `true`): require mention before responding
+- `mentionPatterns` (string[]): custom regex patterns that count as a mention
+- `allowFrom` (array of string/number): sender allowlist (`"*"` to allow all)
+- `textChunkLimit` (number): max outbound text chunk size (capped at 1000)
+
+## Environment variables (default account fallback)
+
+For the default account only, these env vars are supported:
+
+- `GROUPME_BOT_ID`
+- `GROUPME_ACCESS_TOKEN`
+- `GROUPME_BOT_NAME`
+- `GROUPME_CALLBACK_PATH`
+
+If both config and env are set, config values take precedence.
+
+## Notes and limitations
+
+- Group chats only (no DM channel mode)
+- Inbound bot/system messages are ignored
+- GroupMe message text limit is 1000 chars per chunk
+- Media replies require `accessToken` so OpenClaw can upload images to GroupMe
+
+## Troubleshooting
+
+- Bot does not respond:
+  - Confirm webhook URL is public + HTTPS and matches `callbackPath`
+  - Confirm `botId` is correct
+  - If `requireMention: true`, mention the bot in the message
+  - Check `allowFrom` (if set)
+- Image replies fail:
+  - Ensure `accessToken` is configured
+- Check runtime logs:
+
+```bash
+openclaw channels logs --channel groupme
+```

package/index.ts

@@ -0,0 +1,17 @@
+import type { ChannelPlugin, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { groupmePlugin } from "./src/channel.js";
+import { setGroupMeRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "groupme",
+  name: "GroupMe",
+  description: "GroupMe channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setGroupMeRuntime(api.runtime);
+    api.registerChannel({ plugin: groupmePlugin as ChannelPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "groupme",
+  "channels": ["groupme"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "openclaw-groupme",
+  "version": "0.0.1",
+  "description": "OpenClaw GroupMe channel plugin",
+  "type": "module",
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "groupme",
+      "label": "GroupMe",
+      "selectionLabel": "GroupMe (Bot API)",
+      "docsPath": "/channels/groupme",
+      "docsLabel": "groupme",
+      "blurb": "GroupMe bot webhook integration (group chats only).",
+      "order": 95,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@openclaw/groupme",
+      "localPath": "extensions/groupme",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,139 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type {
+  CoreConfig,
+  GroupMeAccountConfig,
+  GroupMeConfig,
+  ResolvedGroupMeAccount,
+} from "./types.js";
+
+const ENV_BOT_ID = "GROUPME_BOT_ID";
+const ENV_ACCESS_TOKEN = "GROUPME_ACCESS_TOKEN";
+const ENV_BOT_NAME = "GROUPME_BOT_NAME";
+const ENV_CALLBACK_PATH = "GROUPME_CALLBACK_PATH";
+
+function readTrimmed(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function listConfiguredAccountIds(cfg: CoreConfig): string[] {
+  const accounts = cfg.channels?.groupme?.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return [];
+  }
+
+  const ids = new Set<string>();
+  for (const key of Object.keys(accounts)) {
+    const normalized = normalizeAccountId(key);
+    if (normalized) {
+      ids.add(normalized);
+    }
+  }
+
+  return [...ids];
+}
+
+function resolveAccountConfig(
+  cfg: CoreConfig,
+  accountId: string,
+): GroupMeAccountConfig | undefined {
+  const accounts = cfg.channels?.groupme?.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return undefined;
+  }
+
+  if (Object.hasOwn(accounts, accountId)) {
+    return accounts[accountId];
+  }
+
+  const hit = Object.keys(accounts).find((key) => normalizeAccountId(key) === accountId);
+  return hit ? accounts[hit] : undefined;
+}
+
+function mergeAccountConfig(cfg: CoreConfig, accountId: string): GroupMeAccountConfig {
+  const raw = (cfg.channels?.groupme ?? {}) as GroupMeConfig;
+  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
+  const account =
+    accountId === DEFAULT_ACCOUNT_ID ? {} : (resolveAccountConfig(cfg, accountId) ?? {});
+
+  return {
+    ...base,
+    ...account,
+  };
+}
+
+export function listGroupMeAccountIds(cfg: CoreConfig): string[] {
+  const ids = new Set<string>([DEFAULT_ACCOUNT_ID]);
+  for (const id of listConfiguredAccountIds(cfg)) {
+    ids.add(id);
+  }
+
+  const ordered = [...ids].toSorted((a, b) => a.localeCompare(b));
+  if (ordered[0] !== DEFAULT_ACCOUNT_ID) {
+    ordered.unshift(DEFAULT_ACCOUNT_ID);
+    return Array.from(new Set(ordered));
+  }
+  return ordered;
+}
+
+export function resolveDefaultGroupMeAccountId(cfg: CoreConfig): string {
+  const configuredDefault = readTrimmed(cfg.channels?.groupme?.defaultAccount);
+  if (configuredDefault) {
+    return normalizeAccountId(configuredDefault);
+  }
+
+  return DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveGroupMeAccount(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+}): ResolvedGroupMeAccount {
+  const normalizedRequested = normalizeAccountId(params.accountId);
+  const accountId =
+    normalizedRequested || resolveDefaultGroupMeAccountId(params.cfg) || DEFAULT_ACCOUNT_ID;
+
+  const merged = mergeAccountConfig(params.cfg, accountId);
+  const baseEnabled = params.cfg.channels?.groupme?.enabled !== false;
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+
+  const isDefaultAccount = accountId === DEFAULT_ACCOUNT_ID;
+  const botId =
+    readTrimmed(merged.botId) ||
+    (isDefaultAccount ? readTrimmed(process.env[ENV_BOT_ID]) : undefined) ||
+    "";
+  const accessToken =
+    readTrimmed(merged.accessToken) ||
+    (isDefaultAccount ? readTrimmed(process.env[ENV_ACCESS_TOKEN]) : undefined) ||
+    "";
+  const botName =
+    readTrimmed(merged.botName) ||
+    (isDefaultAccount ? readTrimmed(process.env[ENV_BOT_NAME]) : undefined) ||
+    undefined;
+  const callbackPath =
+    readTrimmed(merged.callbackPath) ||
+    (isDefaultAccount ? readTrimmed(process.env[ENV_CALLBACK_PATH]) : undefined) ||
+    undefined;
+
+  const config: GroupMeAccountConfig = {
+    ...merged,
+    botId,
+    accessToken,
+    botName,
+    callbackPath,
+  };
+
+  return {
+    accountId,
+    name: readTrimmed(merged.name),
+    enabled,
+    configured: Boolean(botId),
+    botId,
+    accessToken,
+    config,
+  };
+}

package/src/channel.ts

@@ -0,0 +1,294 @@
+import {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  missingTargetError,
+  registerPluginHttpRoute,
+  setAccountEnabledInConfigSection,
+  type ChannelPlugin,
+} from "openclaw/plugin-sdk";
+import type { CoreConfig, GroupMeProbe, ResolvedGroupMeAccount } from "./types.js";
+import {
+  listGroupMeAccountIds,
+  resolveDefaultGroupMeAccountId,
+  resolveGroupMeAccount,
+} from "./accounts.js";
+import { GroupMeConfigSchema } from "./config-schema.js";
+import { createGroupMeWebhookHandler } from "./monitor.js";
+import {
+  normalizeGroupMeAllowEntry,
+  normalizeGroupMeTarget,
+  looksLikeGroupMeTargetId,
+} from "./normalize.js";
+import { groupmeOnboardingAdapter } from "./onboarding.js";
+import { getGroupMeRuntime } from "./runtime.js";
+import { GROUPME_MAX_TEXT_LENGTH, sendGroupMeMedia, sendGroupMeText } from "./send.js";
+
+const CHANNEL_ID = "groupme" as const;
+
+const meta = {
+  id: CHANNEL_ID,
+  label: "GroupMe",
+  selectionLabel: "GroupMe (Bot API)",
+  docsPath: "/channels/groupme",
+  docsLabel: "groupme",
+  blurb: "GroupMe bot webhook integration (group chats only).",
+  aliases: ["gm"],
+  order: 95,
+  quickstartAllowFrom: true,
+};
+
+export const groupmePlugin: ChannelPlugin<ResolvedGroupMeAccount, GroupMeProbe> = {
+  id: CHANNEL_ID,
+  meta,
+  onboarding: groupmeOnboardingAdapter,
+  capabilities: {
+    chatTypes: ["group"],
+    media: true,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.groupme"] },
+  configSchema: buildChannelConfigSchema(GroupMeConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listGroupMeAccountIds(cfg as CoreConfig),
+    resolveAccount: (cfg, accountId) =>
+      resolveGroupMeAccount({ cfg: cfg as CoreConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultGroupMeAccountId(cfg as CoreConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: CHANNEL_ID,
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: CHANNEL_ID,
+        accountId,
+        clearBaseFields: [
+          "name",
+          "botId",
+          "accessToken",
+          "botName",
+          "callbackPath",
+          "mentionPatterns",
+          "requireMention",
+          "allowFrom",
+          "textChunkLimit",
+          "responsePrefix",
+        ],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      botId: account.botId ? "***" : "",
+      callbackPath: account.config.callbackPath,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveGroupMeAccount({ cfg: cfg as CoreConfig, accountId }).config.allowFrom ?? []).map(
+        (entry) => String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => normalizeGroupMeAllowEntry(String(entry)))
+        .filter((entry): entry is string => Boolean(entry)),
+  },
+  groups: {
+    resolveRequireMention: ({ cfg, accountId }) => {
+      const account = resolveGroupMeAccount({
+        cfg: cfg as CoreConfig,
+        accountId,
+      });
+      return account.config.requireMention ?? true;
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getGroupMeRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: GROUPME_MAX_TEXT_LENGTH,
+    resolveTarget: ({ to }) => {
+      const normalized = normalizeGroupMeTarget(to?.trim() ?? "");
+      if (!normalized) {
+        return {
+          ok: false,
+          error: missingTargetError("GroupMe", "<group-id>"),
+        };
+      }
+
+      return {
+        ok: true,
+        to: normalized,
+      };
+    },
+    sendText: async ({ cfg, to, text, accountId }) => {
+      const result = await sendGroupMeText({
+        cfg: cfg as CoreConfig,
+        to,
+        text,
+        accountId,
+      });
+      return {
+        channel: CHANNEL_ID,
+        messageId: result.messageId,
+        timestamp: result.timestamp,
+      };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, accountId }) => {
+      if (!mediaUrl?.trim()) {
+        throw new Error("GroupMe media send requires a mediaUrl");
+      }
+
+      const result = await sendGroupMeMedia({
+        cfg: cfg as CoreConfig,
+        to,
+        text,
+        mediaUrl,
+        accountId,
+      });
+      return {
+        channel: CHANNEL_ID,
+        messageId: result.messageId,
+        timestamp: result.timestamp,
+      };
+    },
+  },
+  messaging: {
+    normalizeTarget: normalizeGroupMeTarget,
+    targetResolver: {
+      looksLikeId: (raw) => looksLikeGroupMeTargetId(raw),
+      hint: "<group-id>",
+    },
+  },
+  resolver: {
+    resolveTargets: async ({ inputs, kind }) => {
+      return inputs.map((input) => {
+        const normalized = normalizeGroupMeTarget(input);
+        if (!normalized) {
+          return {
+            input,
+            resolved: false,
+            note: "empty target",
+          };
+        }
+
+        return {
+          input,
+          resolved: true,
+          id: normalized,
+          name: normalized,
+          note: kind === "user" ? "GroupMe bots are group-only" : undefined,
+        };
+      });
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveGroupMeAccount({
+        cfg: cfg as CoreConfig,
+        accountId,
+      });
+      const q = query?.trim().toLowerCase() ?? "";
+      return (account.config.allowFrom ?? [])
+        .map((entry) => normalizeGroupMeAllowEntry(String(entry)))
+        .filter((entry): entry is string => Boolean(entry) && entry !== "*")
+        .filter((entry) => (q ? entry.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "user", id }) as const);
+    },
+    listGroups: async () => [],
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      callbackPath: snapshot.webhookPath ?? null,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastInboundAt: snapshot.lastInboundAt ?? null,
+      lastOutboundAt: snapshot.lastOutboundAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      botId: account.botId ? "***" : "",
+      tokenSource: account.accessToken ? "configured" : "none",
+      webhookPath: account.config.callbackPath ?? "/groupme",
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      mode: "webhook",
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      if (!account.configured) {
+        throw new Error(
+          `GroupMe is not configured for account "${account.accountId}" (missing botId).`,
+        );
+      }
+
+      const callbackPath = account.config.callbackPath?.trim() || "/groupme";
+      const unregister = registerPluginHttpRoute({
+        path: callbackPath,
+        fallbackPath: "/groupme",
+        handler: createGroupMeWebhookHandler({
+          account,
+          config: ctx.cfg as CoreConfig,
+          runtime: ctx.runtime,
+          statusSink: (patch) => ctx.setStatus({ accountId: account.accountId, ...patch }),
+        }),
+        pluginId: CHANNEL_ID,
+        accountId: account.accountId,
+        log: (message) => ctx.log?.info(message),
+      });
+
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        mode: "webhook",
+        webhookPath: callbackPath,
+        lastStartAt: Date.now(),
+        lastError: null,
+      });
+
+      ctx.log?.info(`[${account.accountId}] GroupMe webhook listening on ${callbackPath}`);
+
+      if (ctx.abortSignal.aborted) {
+        unregister();
+        return;
+      }
+
+      await new Promise<void>((resolve) => {
+        ctx.abortSignal.addEventListener(
+          "abort",
+          () => {
+            unregister();
+            resolve();
+          },
+          { once: true },
+        );
+      });
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,29 @@
+import { BlockStreamingCoalesceSchema, MarkdownConfigSchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+export const GroupMeAccountSchemaBase = z
+  .object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    botId: z.string().optional(),
+    accessToken: z.string().optional(),
+    botName: z.string().optional(),
+    callbackPath: z.string().optional(),
+    mentionPatterns: z.array(z.string()).optional(),
+    requireMention: z.boolean().optional().default(true),
+    allowFrom: z.array(allowFromEntry).optional(),
+    markdown: MarkdownConfigSchema,
+    textChunkLimit: z.number().int().positive().optional(),
+    blockStreaming: z.boolean().optional(),
+    blockStreamingCoalesce: BlockStreamingCoalesceSchema.optional(),
+    responsePrefix: z.string().optional(),
+    mediaMaxMb: z.number().positive().optional(),
+  })
+  .strict();
+
+export const GroupMeConfigSchema = GroupMeAccountSchemaBase.extend({
+  accounts: z.record(z.string(), GroupMeAccountSchemaBase.optional()).optional(),
+  defaultAccount: z.string().optional(),
+}).strict();