openclaw-groupme 0.0.4 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dariel Dato-on
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # openclaw-groupme
2
2
 
3
- GroupMe channel plugin for OpenClaw (GroupMe Bot API, group chats only).
3
+ An [OpenClaw](https://github.com/oddrationale/openclaw) channel plugin that brings your AI agent into GroupMe group chats. It hooks into GroupMe's Bot API via webhooks so your agent can receive messages, understand context, and reply — all within the group conversations your team (or friends) are already having. Group chats only; DMs are not supported by the GroupMe Bot API.
4
4
 
5
5
  ## Install
6
6
 
@@ -8,114 +8,417 @@ GroupMe channel plugin for OpenClaw (GroupMe Bot API, group chats only).
8
8
  openclaw plugins install openclaw-groupme
9
9
  ```
10
10
 
11
- Restart the gateway after installing the plugin.
11
+ After installing, restart the gateway so it picks up the new plugin:
12
12
 
13
- ## What this plugin needs
13
+ ```bash
14
+ openclaw gateway restart
15
+ ```
16
+
17
+ That's it — the plugin is loaded and ready to configure.
18
+
19
+ ## Prerequisites
20
+
21
+ Before you start wiring things up, make sure you have three things ready:
22
+
23
+ ### 1. A GroupMe group
24
+
25
+ Bots in GroupMe live inside groups — there's no way to DM a bot directly. If you don't have one already, create a group using the [GroupMe web app](https://web.groupme.com/) or one of the mobile apps. You can also use an existing group you're already in.
26
+
27
+ ### 2. A GroupMe access token
28
+
29
+ Head over to [dev.groupme.com](https://dev.groupme.com) to grab your access token.
30
+
31
+ **Heads up:** You must have a username and password set up on your GroupMe account to log in to the developer portal. The single sign-on options (Google, Microsoft, etc.) won't work here — only the classic email/phone + password login.
32
+
33
+ ![GroupMe developer portal login page](docs/images/dev-groupme-login.png)
34
+
35
+ Once you're logged in, your access token is displayed in the top-right corner of the page. Click on it to copy.
36
+
37
+ ![Access token location in the GroupMe developer portal](docs/images/dev-groupme-access-token.png)
38
+
39
+ > **Keep your access token secret.** This token has full access to your GroupMe account — it can post messages, join groups, manage bots, and more. Treat it like a password. Unfortunately, the only known way to revoke a compromised token is to change your GroupMe password, which isn't documented anywhere by GroupMe. So guard it carefully.
40
+
41
+ ### 3. A public HTTPS URL
42
+
43
+ GroupMe needs to reach your OpenClaw gateway over the internet to deliver messages. You'll need a public HTTPS URL that routes to your gateway's webhook endpoint.
14
44
 
15
- 1. A GroupMe bot (from https://dev.groupme.com/bots)
16
- 2. A public HTTPS URL that can reach your OpenClaw gateway webhook endpoint
17
- 3. Your GroupMe `bot_id` (required)
18
- 4. Your GroupMe `access token` (recommended, required for image uploads)
45
+ How you set this up depends entirely on your environment — a reverse proxy (Nginx, Caddy, Traefik), a Cloudflare tunnel, ngrok, Tailscale, or any number of other approaches will work. The important thing is:
19
46
 
20
- ## Step-by-step setup
47
+ - The URL must be **HTTPS** (GroupMe requires it).
48
+ - Only expose the **callback path** (e.g., `/groupme/...`) — don't open your entire gateway to the public internet.
49
+ - The domain must be **live and reachable** at setup time, because GroupMe pings the callback URL when you register a bot.
21
50
 
22
- 1. Install plugin:
51
+ We can't cover every possible network setup here, but at the end of the day you need a public `https://your-domain.com/groupme/...` URL that reaches your OpenClaw gateway.
52
+
53
+ ## Setup: Interactive Wizard (Recommended)
54
+
55
+ The interactive wizard is the easiest way to get started. It creates a new GroupMe bot, registers the callback URL, and writes all the config for you.
56
+
57
+ **1.** Run the channel setup command:
23
58
 
24
59
  ```bash
25
- openclaw plugins install openclaw-groupme
60
+ openclaw channels add
26
61
  ```
27
62
 
28
- 2. Create a GroupMe bot:
29
- - Go to https://dev.groupme.com/bots
30
- - Create/select a bot for your target group
31
- - Copy the bot's `bot_id`
32
- - Copy your GroupMe `access token`
63
+ **2.** When asked "Configure chat channels now?", select **Yes**.
64
+
65
+ **3.** Use the arrow keys to select **GroupMe** from the channel list.
66
+
67
+ **4.** Enter a **bot name**. This is the display name your bot will use in the group (e.g., `openclaw`). This name is also used for mention detection.
68
+
69
+ **5.** Paste your **GroupMe access token** when prompted.
70
+
71
+ **6.** The wizard fetches your groups from GroupMe. **Select the group** you want the bot to live in.
33
72
 
34
- 3. Configure OpenClaw:
35
- - Option A (interactive):
73
+ **7.** Choose whether to **require an @mention**:
74
+ - **Yes** The bot only responds when someone mentions it by name (e.g., "hey @openclaw, what's the weather?"). This is great for groups with multiple people where you don't want the bot jumping into every conversation.
75
+ - **No** — The bot responds to every message in the group. Perfect if you're the only human in the group and want a direct chat experience.
76
+
77
+ **8.** Enter the **public domain** that will host your callback URL. This should be the domain name (or public IP) that can reach your OpenClaw gateway — for example, `bot.example.com`. The wizard generates a secure callback URL with a random path and secret token.
78
+
79
+ **9.** The wizard registers the bot with GroupMe and writes the config. You'll see a summary of what was created.
80
+
81
+ **10.** Restart the gateway:
36
82
 
37
83
  ```bash
38
- openclaw channels add --channel groupme
84
+ openclaw gateway restart
39
85
  ```
40
86
 
41
- - Option B (manual config): add this under your OpenClaw config:
87
+ **11.** Send a test message in the GroupMe group. If everything is wired up correctly, your bot should respond. Make sure your reverse proxy or port forwarding is configured to route the callback URL to your gateway.
42
88
 
43
- ```json5
89
+ ## Setup: Non-Interactive CLI
90
+
91
+ If you already have a GroupMe bot created (maybe from the [Bots page](https://dev.groupme.com/bots) on the developer portal) and want a scriptable setup, use the CLI flags directly:
92
+
93
+ ![Bots page in the GroupMe developer portal](docs/images/dev-groupme-bots.png)
94
+
95
+ ```bash
96
+ openclaw channels add --channel groupme \
97
+ --token "YOUR_GROUPME_BOT_ID" \
98
+ --access-token "YOUR_GROUPME_ACCESS_TOKEN" \
99
+ --webhook-url "/groupme/callback?k=YOUR_SECRET"
100
+ ```
101
+
102
+ For named accounts (useful if you're running multiple bots):
103
+
104
+ ```bash
105
+ openclaw channels add --channel groupme \
106
+ --account work \
107
+ --name "Work Bot" \
108
+ --token "YOUR_GROUPME_BOT_ID" \
109
+ --access-token "YOUR_GROUPME_ACCESS_TOKEN" \
110
+ --webhook-url "/groupme/callback?k=YOUR_SECRET"
111
+ ```
112
+
113
+ | Flag | Maps to config | Description |
114
+ | ---- | -------------- | ----------- |
115
+ | `--token` | `botId` | Your GroupMe Bot ID |
116
+ | `--access-token` | `accessToken` | Your GroupMe access token |
117
+ | `--webhook-url` | `callbackUrl` | Full relative webhook URL (path + query token) |
118
+ | `--webhook-path` | `callbackUrl` | Alias for `--webhook-url` |
119
+ | `--account` | account ID | Named account identifier |
120
+ | `--name` | `name` | Display name for the account |
121
+
122
+ > **Note:** The non-interactive CLI does not prompt for `botName`, `groupId`, `requireMention`, or `publicDomain`. You can add these manually in your config file afterward, or set them via environment variables.
123
+
124
+ After adding the channel, make sure the callback URL you gave GroupMe (when you created the bot) matches what you passed to `--webhook-url`. Then restart the gateway:
125
+
126
+ ```bash
127
+ openclaw gateway restart
128
+ ```
129
+
130
+ ## Manual Config Example
131
+
132
+ If you prefer editing config files directly, here's what a complete setup looks like:
133
+
134
+ ```json
44
135
  {
45
- channels: {
46
- groupme: {
47
- enabled: true,
48
- botId: "YOUR_GROUPME_BOT_ID",
49
- accessToken: "YOUR_GROUPME_ACCESS_TOKEN",
50
- botName: "openclaw",
51
- callbackPath: "/groupme",
52
- requireMention: true
136
+ "channels": {
137
+ "groupme": {
138
+ "enabled": true,
139
+ "botName": "openclaw",
140
+ "accessToken": "YOUR_GROUPME_ACCESS_TOKEN",
141
+ "botId": "YOUR_GROUPME_BOT_ID",
142
+ "groupId": "YOUR_GROUPME_GROUP_ID",
143
+ "publicDomain": "bot.example.com",
144
+ "callbackUrl": "/groupme/e60b3e59da98950f?k=YOUR_SECRET_TOKEN",
145
+ "requireMention": true
53
146
  }
54
147
  }
55
148
  }
56
149
  ```
57
150
 
58
- 4. Point GroupMe to your webhook:
59
- - Callback URL format: `https://<your-public-domain><callbackPath>`
60
- - Example: `https://bot.example.com/groupme`
61
- - Set this URL in the GroupMe bot settings
151
+ ## Reconfiguring an Existing Setup
62
152
 
63
- 5. Restart OpenClaw gateway:
153
+ If GroupMe is already configured and you run `openclaw configure` again, you'll get a menu of targeted actions instead of repeating the full wizard:
64
154
 
65
- ```bash
66
- openclaw gateway restart
155
+ - **Skip** — leave everything as-is
156
+ - **Rotate access token** — replace the stored access token (validates the new token by fetching your groups)
157
+ - **Change group** — pick a different GroupMe group and optionally register a new bot in it
158
+ - **Regenerate callback URL** — create a new random callback path and secret token (you'll need to update the bot's callback URL in GroupMe afterward)
159
+ - **Toggle requireMention** — flip mention-required mode on or off
160
+ - **Update public domain** — change the public domain used for callback URLs
161
+ - **Full re-setup** — start from scratch with the interactive wizard
162
+
163
+ This lets you make quick adjustments — like rotating a leaked token or moving the bot to a different group — without tearing down the whole config.
164
+
165
+ ## Response Modes
166
+
167
+ ### Always respond (`requireMention: false`)
168
+
169
+ The bot replies to every message in the group. Simple and direct.
170
+
171
+ ```json
172
+ {
173
+ "channels": {
174
+ "groupme": {
175
+ "requireMention": false
176
+ }
177
+ }
178
+ }
67
179
  ```
68
180
 
69
- 6. Verify channel status:
181
+ ### Mention only (`requireMention: true`, default)
70
182
 
71
- ```bash
72
- openclaw channels status --probe
183
+ The bot only replies when someone mentions it by name. It still passively buffers recent messages so it has context when it does respond.
184
+
185
+ ```json
186
+ {
187
+ "channels": {
188
+ "groupme": {
189
+ "requireMention": true,
190
+ "historyLimit": 30
191
+ }
192
+ }
193
+ }
194
+ ```
195
+
196
+ Set `historyLimit: 0` to disable history buffering entirely.
197
+
198
+ ### How Mention Detection Works
199
+
200
+ GroupMe bots don't support native @mention entities, so this plugin uses text matching. By default, it matches the `botName` in the message text. You can add custom patterns too:
201
+
202
+ ```json
203
+ {
204
+ "channels": {
205
+ "groupme": {
206
+ "botName": "openclaw",
207
+ "mentionPatterns": [
208
+ "@openclaw",
209
+ "hey openclaw",
210
+ "oc"
211
+ ]
212
+ }
213
+ }
214
+ }
215
+ ```
216
+
217
+ Patterns are case-insensitive regular expressions, so you can get creative with matching.
218
+
219
+ ## Security
220
+
221
+ The plugin ships with some security defaults out of the box. Replay protection and rate limiting are always on — you don't need to configure anything for a solid baseline.
222
+
223
+ ### Inbound Webhook Pipeline
224
+
225
+ Every incoming webhook request goes through this gauntlet before your agent ever sees it:
226
+
227
+ 1. **Method check** — Only `POST` requests are accepted (405 for everything else)
228
+ 2. **Callback token auth** — The `k` query parameter in the callback URL is verified using timing-safe comparison
229
+ 3. **Proxy validation** — If configured, validates trusted proxy headers, allowed hosts, and HTTPS protocol
230
+ 4. **Body parsing** — 64KB size limit, 15-second timeout
231
+ 5. **Payload parsing** — Extracts the GroupMe callback data and filters out bot messages, system messages, and empty messages
232
+ 6. **Group binding** — Verifies the inbound `group_id` matches the configured `groupId`
233
+ 7. **Replay protection** — SHA-256 keyed deduplication with a sliding TTL window
234
+ 8. **Rate limiting** — Per-IP, per-sender, and global concurrency caps
235
+
236
+ ### Outbound Media Security
237
+
238
+ When the bot sends image replies, outbound media fetches are hardened with:
239
+
240
+ - SSRF guard with private-network blocking (enabled by default)
241
+ - MIME type allowlist (images only by default)
242
+ - Download size limit (15 MB)
243
+ - Request timeout (10 seconds)
244
+
245
+ ### Security Config Reference
246
+
247
+ You only need a `security` block if you want to override the defaults. Just include the fields you want to change:
248
+
249
+ ```json
250
+ {
251
+ "channels": {
252
+ "groupme": {
253
+ "security": {
254
+ "rateLimit": {
255
+ "maxRequestsPerIp": 60
256
+ },
257
+ "proxy": {
258
+ "trustedProxyCidrs": ["10.0.0.0/8"],
259
+ "allowedPublicHosts": ["bot.example.com"],
260
+ "requireHttpsProto": true
261
+ }
262
+ }
263
+ }
264
+ }
265
+ }
73
266
  ```
74
267
 
75
- 7. Send a test message in the GroupMe group:
76
- - With default settings, the bot only responds when mentioned (`requireMention: true`)
77
- - Mention either `@<botName>` or a configured mention pattern
268
+ #### Replay Protection
269
+
270
+ | Field | Type | Default | Description |
271
+ | ----- | ---- | ------- | ----------- |
272
+ | `security.replay.ttlSeconds` | number | `600` | How long (in seconds) to remember message IDs for deduplication |
273
+ | `security.replay.maxEntries` | number | `10000` | Maximum number of entries in the replay cache |
274
+
275
+ #### Rate Limiting
276
+
277
+ | Field | Type | Default | Description |
278
+ | ----- | ---- | ------- | ----------- |
279
+ | `security.rateLimit.windowMs` | number | `60000` | Sliding window size in milliseconds |
280
+ | `security.rateLimit.maxRequestsPerIp` | number | `120` | Max webhook requests per IP per window |
281
+ | `security.rateLimit.maxRequestsPerSender` | number | `60` | Max webhook requests per GroupMe sender per window |
282
+ | `security.rateLimit.maxConcurrent` | number | `8` | Max concurrent inbound message executions |
283
+
284
+ #### Media
285
+
286
+ | Field | Type | Default | Description |
287
+ | ----- | ---- | ------- | ----------- |
288
+ | `security.media.allowPrivateNetworks` | boolean | `false` | Allow fetching media from private/internal networks |
289
+ | `security.media.maxDownloadBytes` | number | `15728640` | Max download size for outbound media (bytes) |
290
+ | `security.media.requestTimeoutMs` | number | `10000` | Timeout for outbound media fetch requests (ms) |
291
+ | `security.media.allowedMimePrefixes` | string[] | `["image/"]` | Allowed MIME type prefixes for outbound media |
78
292
 
79
- ## Config reference (common fields)
293
+ #### Logging
80
294
 
81
- - `botId` (string, required): GroupMe Bot ID
82
- - `accessToken` (string): needed for image upload / media replies
83
- - `botName` (string): mention fallback name used by mention detection
84
- - `callbackPath` (string, default `/groupme`): webhook route path
85
- - `requireMention` (boolean, default `true`): require mention before responding
86
- - `mentionPatterns` (string[]): custom regex patterns that count as a mention
87
- - `allowFrom` (array of string/number): sender allowlist (`"*"` to allow all)
88
- - `textChunkLimit` (number): max outbound text chunk size (capped at 1000)
295
+ | Field | Type | Default | Description |
296
+ | ----- | ---- | ------- | ----------- |
297
+ | `security.logging.redactSecrets` | boolean | `true` | Redact callback secrets in logs and status output |
298
+ | `security.logging.logRejectedRequests` | boolean | `true` | Log rejected webhook requests |
89
299
 
90
- ## Environment variables (default account fallback)
300
+ #### Command Bypass
91
301
 
92
- For the default account only, these env vars are supported:
302
+ | Field | Type | Default | Description |
303
+ | ----- | ---- | ------- | ----------- |
304
+ | `security.commandBypass.requireAllowFrom` | boolean | `true` | Require sender to be in `allowFrom` list to use control commands |
305
+ | `security.commandBypass.requireMentionForCommands` | boolean | `false` | Require mention even for control commands |
93
306
 
94
- - `GROUPME_BOT_ID`
95
- - `GROUPME_ACCESS_TOKEN`
96
- - `GROUPME_BOT_NAME`
97
- - `GROUPME_CALLBACK_PATH`
307
+ #### Proxy Validation
98
308
 
99
- If both config and env are set, config values take precedence.
309
+ Include a `proxy` block to enable trusted-proxy validation. This is useful when your gateway sits behind a reverse proxy and you want to validate forwarded headers.
100
310
 
101
- ## Notes and limitations
311
+ | Field | Type | Default | Description |
312
+ | ----- | ---- | ------- | ----------- |
313
+ | `security.proxy.trustedProxyCidrs` | string[] | `[]` | Only trust `X-Forwarded-*` headers from these CIDRs |
314
+ | `security.proxy.allowedPublicHosts` | string[] | `[]` | Allowed values for the effective public host |
315
+ | `security.proxy.requireHttpsProto` | boolean | `false` | Require the effective protocol to be HTTPS |
316
+ | `security.proxy.rejectStatus` | number | `403` | HTTP status for proxy-policy rejections (`400`, `403`, or `404`) |
102
317
 
103
- - Group chats only (no DM channel mode)
104
- - Inbound bot/system messages are ignored
105
- - GroupMe message text limit is 1000 chars per chunk
106
- - Media replies require `accessToken` so OpenClaw can upload images to GroupMe
318
+ ## Environment Variables
319
+
320
+ For the default account, you can use environment variables instead of (or alongside) config file values. This is handy for CI/CD, Docker deployments, or anywhere you'd rather not put secrets in a config file.
321
+
322
+ | Variable | Maps to config | Description |
323
+ | -------- | -------------- | ----------- |
324
+ | `GROUPME_BOT_ID` | `botId` | GroupMe Bot ID |
325
+ | `GROUPME_ACCESS_TOKEN` | `accessToken` | GroupMe access token |
326
+ | `GROUPME_BOT_NAME` | `botName` | Bot display name |
327
+ | `GROUPME_GROUP_ID` | `groupId` | GroupMe group ID |
328
+ | `GROUPME_PUBLIC_DOMAIN` | `publicDomain` | Public domain for the callback URL |
329
+ | `GROUPME_CALLBACK_URL` | `callbackUrl` | Relative webhook URL (path + query token) |
330
+
331
+ If both a config value and an environment variable are set, the **config value wins**. Environment variables only apply to the default account — named accounts must be configured in the config file.
332
+
333
+ ## Config Reference
334
+
335
+ | Field | Type | Default | Description |
336
+ | ----- | ---- | ------- | ----------- |
337
+ | `botId` | string | — | GroupMe Bot ID |
338
+ | `accessToken` | string | — | GroupMe access token (required for image uploads and the interactive wizard) |
339
+ | `botName` | string | — | Bot display name, used for mention detection |
340
+ | `groupId` | string | — | Expected GroupMe `group_id` for inbound binding |
341
+ | `publicDomain` | string | — | Public domain where the gateway is reachable (e.g., `bot.example.com`) |
342
+ | `callbackUrl` | string | `/groupme` | Relative webhook URL including query token |
343
+ | `requireMention` | boolean | `true` | Only respond when mentioned by name |
344
+ | `historyLimit` | number | `20` | Max buffered messages per group (when `requireMention: true`) |
345
+ | `mentionPatterns` | string[] | — | Custom regex patterns for mention detection |
346
+ | `allowFrom` | array | — | Sender allowlist (`"*"` allows everyone) |
347
+ | `textChunkLimit` | number | `1000` | Max characters per outbound text chunk |
348
+ | `security` | object | — | Security overrides (see [Security](#security) section above) |
349
+
350
+ ## Callback URL Format
351
+
352
+ The `callbackUrl` stores the full relative webhook URL (path + secret query token):
353
+
354
+ ```
355
+ /groupme/e60b3e59da98950f?k=775c9958da544c73e6d97c04f884957caa174c8570889bbaa0900d6253f20bbc
356
+ ```
357
+
358
+ The full URL you register with GroupMe is your public domain + this path:
359
+
360
+ ```
361
+ https://bot.example.com/groupme/e60b3e59da98950f?k=775c9958da544c73e6d97c04f884957caa174c8570889bbaa0900d6253f20bbc
362
+ ```
363
+
364
+ ## Notes and Limitations
365
+
366
+ ### GroupMe Bot API Constraints
367
+
368
+ GroupMe bots are intentionally limited compared to full user accounts. These constraints come from the GroupMe Bot API itself, not from this plugin:
369
+
370
+ - **Group chats only** — bots cannot send or receive direct messages. Each bot is bound to a single group.
371
+ - **One group per bot** — a bot registration is tied to exactly one group. To serve multiple groups, register a separate bot (and account) for each.
372
+ - **No message history** — bots only see messages as they arrive via the callback webhook. They cannot fetch past messages from the group. (This plugin buffers recent messages locally for context when `requireMention` is enabled.)
373
+ - **No reactions** — bots cannot like or unlike messages.
374
+ - **Text and images only** — bots can post text and attach a single image per message. Other attachment types (video, files, locations) are not supported.
375
+
376
+ ### Plugin-Specific Notes
377
+
378
+ - Bot and system messages from GroupMe are automatically ignored
379
+ - GroupMe has a 1000-character limit per message — longer replies are chunked automatically
380
+ - Image replies require `accessToken` so the plugin can upload images to GroupMe's Image Service
381
+ - The interactive wizard registers the bot with GroupMe using your `publicDomain`, so **your domain must be live and reachable** during setup
382
+ - If you change your domain later, update `publicDomain` in your config and update the bot's callback URL at [dev.groupme.com/bots](https://dev.groupme.com/bots)
107
383
 
108
384
  ## Troubleshooting
109
385
 
110
- - Bot does not respond:
111
- - Confirm webhook URL is public + HTTPS and matches `callbackPath`
112
- - Confirm `botId` is correct
113
- - If `requireMention: true`, mention the bot in the message
114
- - Check `allowFrom` (if set)
115
- - Image replies fail:
116
- - Ensure `accessToken` is configured
117
- - Check runtime logs:
386
+ - **Bot doesn't respond:**
387
+ - Is your webhook URL public, HTTPS, and matching the `callbackUrl` in config?
388
+ - Does `groupId` match the actual GroupMe group ID?
389
+ - Is `botId` correct?
390
+ - If `requireMention: true`, are you mentioning the bot by name?
391
+ - Check `allowFrom` if you have a sender allowlist configured
392
+
393
+ - **Webhook returns 404 or 403:**
394
+ - Verify the `k` token in the URL matches what's in `callbackUrl`
395
+ - Check `groupId` binding
396
+ - If using proxy validation, check your `security.proxy` settings
397
+
398
+ - **Bot responds but has no context:**
399
+ - Make sure `historyLimit` is not `0`
400
+ - History buffering only applies when `requireMention: true`
401
+
402
+ - **Image replies fail:**
403
+ - Make sure `accessToken` is configured
404
+
405
+ - **Bot registration fails with "callback URL validation has failed":**
406
+ - GroupMe pings the callback domain when you register a bot
407
+ - Your public domain must be live and reachable at setup time
408
+ - Test it: `curl -I https://your-domain.com`
409
+
410
+ - **Check runtime logs:**
118
411
 
119
412
  ```bash
120
413
  openclaw channels logs --channel groupme
121
414
  ```
415
+
416
+ - **Check channel status:**
417
+
418
+ ```bash
419
+ openclaw channels status --probe
420
+ ```
421
+
422
+ ## License
423
+
424
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,7 +1,15 @@
1
1
  {
2
2
  "name": "openclaw-groupme",
3
- "version": "0.0.4",
3
+ "version": "0.4.0",
4
4
  "description": "OpenClaw GroupMe channel plugin",
5
+ "license": "MIT",
6
+ "keywords": [
7
+ "openclaw",
8
+ "groupme",
9
+ "chatbot",
10
+ "webhook",
11
+ "channel-plugin"
12
+ ],
5
13
  "repository": {
6
14
  "type": "git",
7
15
  "url": "https://github.com/oddrationale/openclaw-groupme"
@@ -11,11 +19,34 @@
11
19
  "url": "https://github.com/oddrationale/openclaw-groupme/issues"
12
20
  },
13
21
  "type": "module",
22
+ "engines": {
23
+ "node": ">=18"
24
+ },
25
+ "files": [
26
+ "index.ts",
27
+ "src/**/*.ts",
28
+ "LICENSE",
29
+ "README.md"
30
+ ],
31
+ "scripts": {
32
+ "test": "vitest run",
33
+ "typecheck": "tsc --noEmit"
34
+ },
14
35
  "dependencies": {
15
- "zod": "^4.3.6"
36
+ "zod": ">=4.3.6 <5"
37
+ },
38
+ "devDependencies": {
39
+ "openclaw": ">=2026.2.26",
40
+ "typescript": "^5.9.3",
41
+ "vitest": "^4.0.18"
16
42
  },
17
43
  "peerDependencies": {
18
- "openclaw": ">=2026.2.0"
44
+ "openclaw": ">=2026.2.26"
45
+ },
46
+ "peerDependenciesMeta": {
47
+ "openclaw": {
48
+ "optional": true
49
+ }
19
50
  },
20
51
  "openclaw": {
21
52
  "extensions": [
@@ -25,16 +56,10 @@
25
56
  "id": "groupme",
26
57
  "label": "GroupMe",
27
58
  "selectionLabel": "GroupMe (Bot API)",
28
- "docsPath": "/channels/groupme",
29
- "docsLabel": "groupme",
30
- "blurb": "GroupMe bot webhook integration (group chats only).",
31
- "order": 95,
32
- "quickstartAllowFrom": true
59
+ "blurb": "GroupMe bot webhook integration (group chats only)."
33
60
  },
34
61
  "install": {
35
- "npmSpec": "openclaw-groupme",
36
- "localPath": "extensions/groupme",
37
- "defaultChoice": "npm"
62
+ "npmSpec": "openclaw-groupme"
38
63
  }
39
64
  }
40
65
  }