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 +21 -0
- package/README.md +373 -70
- package/package.json +36 -11
- package/src/accounts.ts +51 -23
- package/src/channel.ts +163 -16
- package/src/config-schema.ts +73 -3
- package/src/groupme-api.ts +98 -0
- package/src/history.ts +54 -0
- package/src/inbound.ts +129 -23
- package/src/monitor.ts +285 -33
- package/src/normalize.ts +1 -9
- package/src/onboarding.ts +413 -38
- package/src/parse.ts +32 -33
- package/src/policy.ts +5 -2
- package/src/rate-limit.ts +128 -0
- package/src/replay-cache.ts +71 -0
- package/src/security.ts +457 -0
- package/src/send.ts +237 -51
- package/src/types.ts +98 -1
- package/.github/workflows/publish-npm.yml +0 -30
- package/openclaw.plugin.json +0 -9
- package/src/monitor.test.ts +0 -186
- package/src/normalize.test.ts +0 -43
- package/src/parse.test.ts +0 -162
- package/src/policy.test.ts +0 -23
- package/src/send.test.ts +0 -153
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
|
-
|
|
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
|
-
|
|
11
|
+
After installing, restart the gateway so it picks up the new plugin:
|
|
12
12
|
|
|
13
|
-
|
|
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
|
+

|
|
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
|
+

|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
60
|
+
openclaw channels add
|
|
26
61
|
```
|
|
27
62
|
|
|
28
|
-
2
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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
|
-
|
|
35
|
-
-
|
|
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
|
|
84
|
+
openclaw gateway restart
|
|
39
85
|
```
|
|
40
86
|
|
|
41
|
-
|
|
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
|
-
|
|
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
|
+

|
|
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
|
-
|
|
49
|
-
accessToken: "YOUR_GROUPME_ACCESS_TOKEN",
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
66
|
-
|
|
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
|
-
|
|
181
|
+
### Mention only (`requireMention: true`, default)
|
|
70
182
|
|
|
71
|
-
|
|
72
|
-
|
|
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
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
293
|
+
#### Logging
|
|
80
294
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
-
|
|
300
|
+
#### Command Bypass
|
|
91
301
|
|
|
92
|
-
|
|
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
|
-
|
|
95
|
-
- `GROUPME_ACCESS_TOKEN`
|
|
96
|
-
- `GROUPME_BOT_NAME`
|
|
97
|
-
- `GROUPME_CALLBACK_PATH`
|
|
307
|
+
#### Proxy Validation
|
|
98
308
|
|
|
99
|
-
|
|
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
|
-
|
|
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
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
|
111
|
-
-
|
|
112
|
-
-
|
|
113
|
-
-
|
|
114
|
-
-
|
|
115
|
-
-
|
|
116
|
-
|
|
117
|
-
-
|
|
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
|
|
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": "
|
|
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.
|
|
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
|
-
"
|
|
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
|
}
|