{"id":48213337,"url":"https://github.com/alexwoo-awso/openclaw-rocketchat","last_synced_at":"2026-04-25T12:01:58.976Z","repository":{"id":338854380,"uuid":"1159366784","full_name":"alexwoo-awso/openclaw-rocketchat","owner":"alexwoo-awso","description":"OpenClaw channel plugin for Rocket.Chat — DDP/REST, DMs, groups, threads, media, multi-account","archived":false,"fork":false,"pushed_at":"2026-04-25T10:07:56.000Z","size":702,"stargazers_count":13,"open_issues_count":2,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-25T11:27:55.642Z","etag":null,"topics":["ai-assistant","channel-plugin","chatbot","ddp","npm-package","openclaw","rocketchat","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexwoo-awso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T16:38:49.000Z","updated_at":"2026-04-25T10:08:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alexwoo-awso/openclaw-rocketchat","commit_stats":null,"previous_names":["alexwoo-awso/openclaw-rocketchat"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/alexwoo-awso/openclaw-rocketchat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwoo-awso%2Fopenclaw-rocketchat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwoo-awso%2Fopenclaw-rocketchat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwoo-awso%2Fopenclaw-rocketchat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwoo-awso%2Fopenclaw-rocketchat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexwoo-awso","download_url":"https://codeload.github.com/alexwoo-awso/openclaw-rocketchat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwoo-awso%2Fopenclaw-rocketchat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32261124,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","channel-plugin","chatbot","ddp","npm-package","openclaw","rocketchat","typescript"],"created_at":"2026-04-04T18:53:16.981Z","updated_at":"2026-04-25T12:01:58.936Z","avatar_url":"https://github.com/alexwoo-awso.png","language":"TypeScript","funding_links":[],"categories":["Configuration"],"sub_categories":["Messaging Channels"],"readme":"# OpenClaw Rocket.Chat Plugin\n\nChannel plugin for connecting OpenClaw to [Rocket.Chat](https://rocket.chat/) instances.\n\n**npm package:** `@alexwoo-awso/openclaw-rocketchat`\n\n## Features\n\n- Direct messages, channels, private groups, and threads\n- Media/file upload and download\n- Mention-gated channel behavior, `onmessage`, and `onchar` trigger modes\n- Conversation windows for follow-up messages after a mention or trigger\n- Multi-account support\n- Pairing-based DM access control\n- Block streaming with configurable coalescing\n- DDP WebSocket realtime monitoring with auto-reconnect\n\n## Setup\n\n### Authentication methods\n\nThe plugin supports both Rocket.Chat auth paths:\n\n- **Personal Access Token (PAT):** configure `authToken` + `userId`\n- **Username/password login:** configure `username` + `password`\n\nPAT is usually the better choice when your Rocket.Chat plan exposes Personal Access Tokens. Username/password works on plans where PAT is unavailable.\n\n### Secret storage\n\nPrefer environment variables for secrets instead of committing them into `openclaw.json`.\n\nOpenClaw can load env vars from:\n\n- the gateway process environment\n- `~/.openclaw/.env`\n\n### Base URL\n\nUse the Rocket.Chat server base URL, for example:\n\n- `https://chat.example.com`\n\nDo not use `/api/v1` in config examples unless you want to; the plugin strips a trailing slash and also normalizes a trailing `/api/v1`.\n\n### Important config rules\n\n- The bot user must already be a member of channels or private groups you want it to monitor.\n- Only the **default** Rocket.Chat account can read `ROCKETCHAT_*` environment variables.\n- Config values override env vars **field by field**.\n- If you define `channels.rocketchat.accounts`, the top-level `channels.rocketchat` values still act as shared defaults for those named accounts unless a per-account value overrides them.\n- A Rocket.Chat account is considered configured when it has `baseUrl` plus either `authToken` + `userId` or `username` + `password`.\n\n### Option A: Default account from environment variables\n\nPAT:\n\n```bash\nexport ROCKETCHAT_URL=https://chat.example.com\nexport ROCKETCHAT_AUTH_TOKEN=your-personal-access-token\nexport ROCKETCHAT_USER_ID=your-user-id\n```\n\nUsername/password:\n\n```bash\nexport ROCKETCHAT_URL=https://chat.example.com\nexport ROCKETCHAT_USERNAME=openclaw-bot\nexport ROCKETCHAT_PASSWORD=your-password\n```\n\n### Option B: Default account in `openclaw.json`\n\nPAT:\n\n```json\n{\n  \"channels\": {\n    \"rocketchat\": {\n      \"enabled\": true,\n      \"baseUrl\": \"https://chat.example.com\",\n      \"authToken\": \"your-personal-access-token\",\n      \"userId\": \"your-user-id\"\n    }\n  }\n}\n```\n\nUsername/password:\n\n```json\n{\n  \"channels\": {\n    \"rocketchat\": {\n      \"enabled\": true,\n      \"baseUrl\": \"https://chat.example.com\",\n      \"username\": \"openclaw-bot\",\n      \"password\": \"your-password\"\n    }\n  }\n}\n```\n\n### Option C: Multi-account config\n\nNamed accounts are config-only. `ROCKETCHAT_*` env vars do not apply to them.\n\nThis example also shows shared top-level defaults inherited by each account:\n\n```yaml\nchannels:\n  rocketchat:\n    enabled: true\n    chatmode: oncall\n    conversationWindowMinutes: 10\n    groupPolicy: allowlist\n    accounts:\n      primary:\n        baseUrl: https://chat.example.com\n        authToken: token-1\n        userId: user-1\n        allowFrom: [\"@admin\"]\n      secondary:\n        baseUrl: https://other-chat.example.com\n        username: openclaw-bot\n        password: secret\n        chatmode: onchar\n        oncharPrefixes: [\"!\"]\n        rooms:\n          GENERAL_ROOM_ID:\n            conversationWindowMinutes: 20\n```\n\n## Configuration Reference\n\nThe same account-level options can be set either:\n\n- at `channels.rocketchat.*` for the default/shared config\n- at `channels.rocketchat.accounts.\u003caccountId\u003e.*` for a named account\n\n### Authentication and connection\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `enabled` | boolean | Enables or disables the channel or account. Default is enabled. |\n| `name` | string | Optional display name for the account in CLI/UI lists. |\n| `baseUrl` | string | Rocket.Chat base URL such as `https://chat.example.com`. |\n| `authToken` | string | Personal Access Token. |\n| `userId` | string | Rocket.Chat user ID paired with `authToken`. |\n| `username` | string | Username for login auth instead of PAT. |\n| `password` | string | Password for login auth instead of PAT. |\n\n### Inbound trigger behavior\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `chatmode` | string | `oncall`, `onmessage`, or `onchar`. |\n| `oncharPrefixes` | string[] | Prefixes that trigger `chatmode: onchar`. Default: `\"\u003e\"` and `\"!\"`. |\n| `requireMention` | boolean | Mention gate for groups/channels when `chatmode` does not force behavior. |\n| `conversationWindowMinutes` | number | Keeps a room active for follow-up messages after a valid mention/trigger. `0` or unset disables it. |\n| `rooms.\u003croomId\u003e.conversationWindowMinutes` | number | Per-room override for the conversation window. |\n\nBehavior notes:\n\n- Direct messages are not mention-gated.\n- `chatmode: oncall` effectively requires a mention in channels/groups.\n- `chatmode: onmessage` effectively disables mention gating in channels/groups.\n- `chatmode: onchar` accepts channel/group messages that start with a configured prefix, and strips that prefix before sending the message to OpenClaw.\n- Conversation windows only relax the mention/trigger requirement; they do not bypass access-control policy.\n\n### Access control\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `dmPolicy` | string | DM policy: `pairing`, `allowlist`, `open`, or `disabled`. Default: `pairing`. |\n| `allowFrom` | array | Allowed DM senders as Rocket.Chat user IDs, `user:ID`, `rocketchat:ID`, plain usernames, or `@username`. |\n| `groupPolicy` | string | Group/channel policy: `allowlist`, `open`, or `disabled`. Default: `allowlist`. |\n| `groupAllowFrom` | array | Allowed senders in channels/private groups. |\n\nImportant:\n\n- If `dmPolicy` is `open`, `allowFrom` must include `\"*\"` or schema validation fails.\n- `allowFrom` and `groupAllowFrom` comparisons are case-insensitive for usernames.\n\n### Outbound reply behavior\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `textChunkLimit` | number | Maximum characters per outbound text message. Default: `4000`. |\n| `chunkMode` | string | Outbound chunking mode: `length` or `newline`. |\n| `blockStreaming` | boolean | Enables or disables block streaming for this channel/account. |\n| `blockStreamingCoalesce.minChars` | number | Minimum buffered characters before a streamed block reply is flushed. |\n| `blockStreamingCoalesce.idleMs` | number | Idle timeout before a buffered streamed block reply is flushed. |\n| `responsePrefix` | string | Optional outbound reply prefix override for this channel/account. |\n| `markdown` | object | Standard OpenClaw markdown configuration for this channel/account. |\n\nCurrent streaming defaults for Rocket.Chat:\n\n- `blockStreamingCoalesce.minChars`: `1500`\n- `blockStreamingCoalesce.idleMs`: `1000`\n\nDelivery notes:\n\n- Long text replies are split into sequential Rocket.Chat messages.\n- `chunkMode: newline` splits more aggressively than `chunkMode: length`.\n- If media upload fails and the media source was an `http://` or `https://` URL, the plugin falls back to sending the URL as text.\n\n### Miscellaneous\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `configWrites` | boolean | Allows channel-initiated config writes. |\n| `capabilities` | string[] | Optional capability tags used for agent/runtime guidance. |\n\n## Sending Messages\n\n```bash\n# Send to a room id directly\nopenclaw send --channel rocketchat --to ROOM_ID \"Hello\"\n\n# Send to a room id with an explicit prefix\nopenclaw send --channel rocketchat --to channel:ROOM_ID \"Hello\"\n\n# Send to a user\nopenclaw send --channel rocketchat --to @username \"Hello\"\nopenclaw send --channel rocketchat --to user:USER_ID \"Hello\"\n```\n\nAccepted `--to` formats:\n\n- `ROOM_ID`\n- `channel:ROOM_ID`\n- `@username`\n- `user:USER_ID`\n- `rocketchat:USER_ID`\n\nWhen sending to a user, the plugin creates or reuses a Rocket.Chat DM room for that user.\n\n## Architecture\n\n- DDP WebSocket for realtime inbound messages\n- Rocket.Chat REST API for login, sending messages, uploads, user lookup, and room lookup\n- Threads are sent with Rocket.Chat `tmid`\n- Room types handled: channels (`c`), private groups (`p`), direct messages (`d`), and livechat (`l`)\n\n## Troubleshooting\n\n- No replies in channels:\n  - make sure the bot user is in the room\n  - `chatmode: oncall` requires a mention unless a conversation window is active\n  - `chatmode: onchar` requires a configured prefix such as `!hello`\n  - `chatmode: onmessage` replies to accepted channel/group messages without a mention\n- Auth problems:\n  - PAT mode needs both `authToken` and `userId`\n  - login mode needs both `username` and `password`\n  - the plugin logs in through `/api/v1/login` when using username/password and can log in again later if needed\n  - env vars only apply to the default account\n- Base URL problems:\n  - use the server base URL, not a deep REST path\n  - trailing `/` and `/api/v1` are normalized away\n\nSecurity review notes for scanner findings and manual audits are tracked in `SECURITY.md`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexwoo-awso%2Fopenclaw-rocketchat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexwoo-awso%2Fopenclaw-rocketchat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexwoo-awso%2Fopenclaw-rocketchat/lists"}