Rocket.Chat - OpenSRE Documentation

Overview

OpenSRE’s Rocket.Chat integration delivers agent-requested posts and scheduled reports to any channel your user or bot account can post to. Useful for teams running self-hosted or cloud Rocket.Chat workspaces. Start the interactive shell with opensre (no subcommand). Slash commands below are run from that REPL.

Rocket.Chat support is outbound delivery only. Chatting with the agent from Rocket.Chat is not supported yet. There is no gateway inbound / messaging pair for Rocket.Chat.

Prerequisites

A Rocket.Chat workspace (self-hosted or cloud) and its base URL, e.g. https://chat.example.com.
An account allowed to post in the destination channel. A dedicated bot account is recommended so messages are not attributed to a personal user.
The Personal Access Tokens feature enabled on the server (Admin → Settings → Accounts → Personal Access Tokens, on by default in most installs) — or admin access to create an incoming webhook.

Setup

Pick a mode

Mode	Credentials	Destination	Best for
Personal Access Token (recommended)	`server_url` + `auth_token` + `user_id`	Any channel, chosen per message	Dynamic channel targeting, verifiable via `/api/v1/me`
Incoming webhook	single `webhook_url`	Fixed channel chosen when the webhook is created	Simplest setup; no bot account needed

You can configure both — when both are present, delivery prefers the webhook. Incomplete token trio fails verify.

Option 1: CLI setup (recommended)

opensre integrations setup rocketchat

Interactive shell: /integrations setup rocketchat. Choose token, webhook, or both. The setup prompts for:

Token mode: Server URL (ROCKETCHAT_SERVER_URL), personal access token (ROCKETCHAT_AUTH_TOKEN in .env and ~/.opensre/credentials.json), user ID (ROCKETCHAT_USER_ID), and default channel (ROCKETCHAT_DEFAULT_CHANNEL)
Webhook mode: webhook URL — saved to the integration store (~/.opensre/integrations.json) and/or ROCKETCHAT_WEBHOOK_URL in .env; never written to the keyring (*_URL is non-keyring config). The URL often embeds a token — treat the whole URL like a password.

Credentials are also saved via upsert_integration("rocketchat", ...).

Option 2: Environment variables

# Token mode
ROCKETCHAT_SERVER_URL=https://chat.example.com
ROCKETCHAT_AUTH_TOKEN=<personal-access-token>
ROCKETCHAT_USER_ID=<user-id>
ROCKETCHAT_DEFAULT_CHANNEL=#incidents

# Webhook mode (either mode alone is enough; both may be set)
ROCKETCHAT_WEBHOOK_URL=https://chat.example.com/hooks/<id>/<token>

Variable	Description
`ROCKETCHAT_SERVER_URL`	Base URL of your Rocket.Chat server. Required for token mode.
`ROCKETCHAT_AUTH_TOKEN`	Personal access token. Required for token mode. Resolved via env then keyring.
`ROCKETCHAT_USER_ID`	User ID shown alongside the token. Required for token mode.
`ROCKETCHAT_DEFAULT_CHANNEL`	Default delivery destination (`#channel` or `@user`). Required for token-mode delivery.
`ROCKETCHAT_WEBHOOK_URL`	Incoming webhook URL. Store/env only — never keyring. Enables webhook mode on its own; preferred over token mode when both are set.

Credential resolution. Token mode: store → resolve_env_credential("ROCKETCHAT_AUTH_TOKEN") (env then keyring). Webhook mode: store → plain ROCKETCHAT_WEBHOOK_URL env — never keyring. Server URL, user id, and default channel stay plain env / store.

Credentials

Token mode: Create a Personal Access Token

Sign in to Rocket.Chat with the account that should post messages.
Open My Account → Personal Access Tokens (avatar menu → My Account).
Enter a token name (e.g. opensre) and select Add. Leave Ignore Two Factor Authentication checked unless your policy requires otherwise.
Rocket.Chat shows the token and your user ID once. Copy both — the token is your auth_token and the ID is your user_id. Treat the token like a password.

If you missed the user ID, it is also shown when you regenerate the token, or under Admin → Users for admins.

Token mode: Pick a destination channel

Messages are posted with the standard chat.postMessage REST endpoint:

Destination	Format	Example
Public/private channel	`#channel-name`	`#incidents`
Direct message to a user	`@username`	`@marcos`

Make sure the token’s account is a member of the channel (or has permission to post there).

Webhook mode: Create an incoming webhook

As an admin, open Administration → Workspace → Integrations → New → Incoming.
Enable the integration, set a name (e.g. opensre), pick the destination channel, and choose the user the messages post as.
Select Save. Rocket.Chat shows the Webhook URL (https://<server>/hooks/<id>/<token>). Copy it — treat the whole URL like a password.

Quick local test with Docker (token mode)

Requires --platform linux/amd64 on Apple Silicon (no arm64 image) and MongoDB 7.0, not 8.0 — 8.0 refuses to start under Docker Desktop’s Linux VM (“kernel versions 6.19 and newer has a known incompatibility”).

docker network create rc-net

docker run -d --name rc-mongo --network rc-net --platform linux/amd64 \
  mongo:7.0 --replSet rs0 --bind_ip_all
i=0
until docker exec rc-mongo mongosh --quiet --eval "db.runCommand('ping')" > /dev/null 2>&1; do
  i=$((i + 1))
  [ "$i" -ge 30 ] && { echo "ERROR: MongoDB never became ready" >&2; exit 1; }
  sleep 2
done
docker exec rc-mongo mongosh --eval "rs.initiate()"

docker run -d --name rc-dev --network rc-net --platform linux/amd64 -p 127.0.0.1:3201:3000 \
  -e 'MONGO_URL=mongodb://rc-mongo:27017/rocketchat?replicaSet=rs0' \
  -e 'MONGO_OPLOG_URL=mongodb://rc-mongo:27017/local?replicaSet=rs0' \
  -e 'ROOT_URL=http://localhost:3201' \
  -e 'ADMIN_USERNAME=verifyadmin' \
  -e 'ADMIN_PASS=verify-admin-pass' \
  -e 'ADMIN_EMAIL=verifyadmin@example.com' \
  -e 'OVERWRITE_SETTING_Show_Setup_Wizard=completed' \
  -e 'OVERWRITE_SETTING_Accounts_TwoFactorAuthentication_Enabled=false' \
  rocket.chat:8.5.1

The OVERWRITE_SETTING_Show_Setup_Wizard=completed and ADMIN_* variables skip the manual setup wizard. The 2FA override lets this disposable instance generate a PAT without a database change or restart.

i=0
until curl -sf -o /dev/null http://localhost:3201/api/info; do
  i=$((i + 1))
  [ "$i" -ge 40 ] && { echo "ERROR: Rocket.Chat never became ready" >&2; exit 1; }
  sleep 10
done

Log in and generate a PAT via the API. The password stays out of curl’s own argv (piped via stdin, not -d "password=..."), and the token is captured into a variable rather than printed:

RC_LOGIN=$(printf 'user=verifyadmin&password=verify-admin-pass' | curl -s -X POST http://localhost:3201/api/v1/login --data-binary @-)
RC_AUTH_TOKEN=$(echo "$RC_LOGIN" | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['authToken'])")
RC_USER_ID=$(echo "$RC_LOGIN" | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['userId'])")
unset RC_LOGIN

RC_PAT=$(printf 'tokenName=opensre-verify' | curl -s -X POST http://localhost:3201/api/v1/users.generatePersonalAccessToken \
  -H "X-Auth-Token: $RC_AUTH_TOKEN" -H "X-User-Id: $RC_USER_ID" --data-binary @- \
  | python3 -c "import json,sys;print(json.load(sys.stdin)['token'])")

export ROCKETCHAT_SERVER_URL="http://localhost:3201"
export ROCKETCHAT_AUTH_TOKEN="$RC_PAT"
export ROCKETCHAT_USER_ID="$RC_USER_ID"
export ROCKETCHAT_DEFAULT_CHANNEL="#general"
unset RC_PAT RC_AUTH_TOKEN RC_USER_ID

Verify:

opensre integrations verify rocketchat

SERVICE    │ SOURCE    │ STATUS   │ DETAIL
rocketchat │ local env │ ✓ passed │ Connected to Rocket.Chat as @verifyadmin.

Teardown:

docker rm -f rc-dev rc-mongo && docker network rm rc-net
unset ROCKETCHAT_SERVER_URL ROCKETCHAT_AUTH_TOKEN
unset ROCKETCHAT_USER_ID ROCKETCHAT_DEFAULT_CHANNEL

Rocket.Chat tools

Tool	What it does
`rocketchat_send_message`	Send a message to the default channel or an explicit `channel`

{
  "name": "rocketchat_send_message",
  "arguments": {
    "channel": "#incidents",
    "message": "DB CPU is back below 70%; keeping the incident open for 10 minutes."
  }
}

The tool resolves credentials internally from the integration store, then the same env/keyring rules as setup (PAT via resolve_env_credential; webhook URL via plain env) — the agent never sees them. In token mode an explicit channel (or the configured default_channel) is targeted via chat.postMessage; in webhook-only mode messages go to the webhook’s fixed destination, and an explicit channel returns a configuration error instead of being silently ignored. Delivery is an external side effect but does not require a separate approval. The result includes a stable status, sent, error_type, channel, and message_length shape so follow-up tool calls can tell configuration failures from Rocket.Chat delivery failures.

Scheduled deliveries (cron)

opensre cron add --kind github_pr_sweep --cron "0 9 * * 1-5" \
  --tz America/Sao_Paulo --provider rocketchat --chat-id "#ops"

--chat-id is the Rocket.Chat destination (#channel or @user). Scheduled deliveries always target that explicit destination, so they require token credentials — an incoming webhook’s destination is fixed at creation time and cannot honor --chat-id. See Cron.

Verify

opensre integrations verify rocketchat

Interactive shell: /integrations verify rocketchat or /verify rocketchat. With token credentials configured, this calls Rocket.Chat’s /api/v1/me endpoint and reports the authenticated @username. With webhook-only configuration, it runs a non-posting reachability probe against the webhook URL (a 404 means the URL or its embedded token is wrong; no message is delivered by the probe). Long messages are truncated to 4,096 characters.

Troubleshooting

/integrations verify rocketchat only calls /api/v1/me (or the webhook reachability probe), so it surfaces credential errors but cannot detect channel-routing problems. Delivery-time errors only show up when a message actually posts; they appear in OpenSRE logs as [rocketchat] post message failed: <error>.

Symptom	Fix
`Rocket.Chat auth failed: auth_token or user_id is invalid or expired.`	Regenerate the token under My Account → Personal Access Tokens and update both values.
`error-room-not-found` (delivery-time)	Check `ROCKETCHAT_DEFAULT_CHANNEL` spelling (including `#`) and membership.
`Rocket.Chat API check failed: <connection error>`	Confirm `ROCKETCHAT_SERVER_URL` includes the scheme and is reachable.
`Rocket.Chat webhook returned 404`	Re-copy the full enabled webhook URL from Administration → Integrations.
Messages never arrive, but verify passes	In token mode, confirm `ROCKETCHAT_DEFAULT_CHANNEL` is set — without it (and without a webhook), delivery is silently skipped. In webhook mode, confirm the webhook posts to the channel you expect.

Security

Prefer a dedicated bot account and Personal Access Token for OpenSRE.
Treat PAT and webhook URLs like passwords; webhook URLs are never stored in the keyring.
Store secrets in the integration store / keyring / secret manager — not in source control.

​Overview

​Prerequisites

​Setup

​Pick a mode

​Option 1: CLI setup (recommended)

​Option 2: Environment variables

​Credentials

​Token mode: Create a Personal Access Token

​Token mode: Pick a destination channel

​Webhook mode: Create an incoming webhook

​Quick local test with Docker (token mode)

​Rocket.Chat tools

​Scheduled deliveries (cron)

​Verify

​Troubleshooting

​Security

Overview

Prerequisites

Setup

Pick a mode

Option 1: CLI setup (recommended)

Option 2: Environment variables

Credentials

Token mode: Create a Personal Access Token

Token mode: Pick a destination channel

Webhook mode: Create an incoming webhook

Quick local test with Docker (token mode)

Rocket.Chat tools

Scheduled deliveries (cron)

Verify

Troubleshooting

Security