Rocket.Chat

OpenSRE’s Rocket.Chat integration delivers investigation findings 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 (investigation reports posted to a channel). Triggering investigations from Rocket.Chat chat is not supported yet.

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 findings 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.

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.

Step 1 (token mode): Create a Personal Access Token

Sign in to Rocket.Chat with the account that should post findings.
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.

Step 1 (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 — the token is embedded in the URL, so treat the whole URL like a password.

Step 2 (token mode): Pick a destination channel

Findings are posted with the standard chat.postMessage REST endpoint, so the destination accepts the same formats Rocket.Chat does:

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).

Step 3: Configure the integration

Option A: Onboarding wizard (recommended)

Interactive shell:

/onboard

CLI:

opensre onboard

Choose Rocket.Chat from the integration list, then pick token, webhook, or both. The wizard prompts for:

Token mode: Server URL (ROCKETCHAT_SERVER_URL), personal access token (OS keyring via sync_env_secret, not plain .env), 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 it like a password for logging/masking.

Credentials are also saved to ~/.opensre/integrations.json via upsert_integration("rocketchat", ...).

Option B: Environment variables

Set in .env (PAT can also live in the keyring after wizard setup):

# 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 (still treat like a password when logging). Enables webhook mode on its own; preferred over token mode when both are set.

OpenSRE picks these up at startup and registers Rocket.Chat as an active integration.

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.

Step 4: Verify

Interactive shell:

/integrations verify rocketchat

Or:

/verify rocketchat

CLI:

opensre integrations 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). You can also trigger a real delivery test against a bundled fixture: Interactive shell:

/investigate tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json

CLI:

opensre investigate --input tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json

Findings should appear in the configured channel as a message with an attachment titled Investigation Complete. Long reports are truncated to 4,096 characters.

Programmatic messaging: `rocketchat_send_message` tool

When the Rocket.Chat integration is configured, OpenSRE exposes a rocketchat_send_message tool. The tool can send user-requested action messages, incident notifications, or follow-up updates to the configured default channel, or to an explicit channel when one is supplied. Ask in plain language from the interactive shell (for example: “send a Rocket.Chat message to the team that DB CPU is back below 70%”).

{
  "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 and requires 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.

Background RCA completion notifications

When the interactive shell runs investigations in background mode, Rocket.Chat can deliver the RCA summary as soon as a job finishes. Configure the integration first, then in the shell:

/background on
/background notify set rocketchat          # or: email,rocketchat
/investigate datadog

On completion the summary — root cause, top analysis, next steps, and a short stats block — is posted as plain text, capped at 4,096 characters. Token mode posts to the configured default_channel; webhook-only setups deliver to the webhook’s fixed destination. Confirm delivery with /background show <task_id>: the notify row reads rocketchat:sent, rocketchat:failed: <error>, or rocketchat:missing rocketchat integration: … when neither token credentials (with a default channel) nor a webhook is configured. A notification problem never fails the investigation itself. See Background investigations for the full command set.

Watchdog alarms

The process watchdog (/watch, opensre watchdog) can send threshold alarms to Rocket.Chat instead of Telegram:

/watch <pid> --max-cpu 80 --provider rocketchat --chat-id "#alerts"

CLI:

opensre watchdog --pid <pid> --max-cpu 80 --provider rocketchat --chat-id "#alerts"

--chat-id overrides the configured default_channel (token mode) or is optional in webhook-only mode (the webhook’s destination is fixed). Alarms require token credentials with a resolvable channel, or a configured incoming webhook — the same rule as scheduled deliveries. Cooldown suppresses repeat alarms for the same threshold (--cooldown, default 5 minutes).

Scheduled deliveries (cron)

With token credentials configured (Steps 1–4), Rocket.Chat can receive recurring reports: Interactive shell:

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

CLI:

opensre cron add --kind daily_summary --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 for task kinds and scheduler daemon setup.

Troubleshooting

/integrations verify rocketchat only calls /api/v1/me, so it surfaces credential errors but cannot detect channel-routing problems. Delivery-time errors only show up when an investigation actually posts; they appear in OpenSRE logs as [rocketchat] post message failed: <error>. Rocket.Chat auth failed: auth_token or user_id is invalid or expired. The token was revoked or the user ID does not match the token’s account. Regenerate the token under My Account → Personal Access Tokens and update both values. error-room-not-found (delivery-time) The channel in ROCKETCHAT_DEFAULT_CHANNEL does not exist or the token’s account cannot see it. Check the spelling (including the # prefix) and make sure the account is a member of the channel. Rocket.Chat API check failed: <connection error> ROCKETCHAT_SERVER_URL is wrong or unreachable from the machine running OpenSRE. Confirm the URL opens in a browser and includes the scheme (https://). Rocket.Chat webhook returned 404; the URL looks invalid. The webhook was deleted, disabled, or the URL was copied incompletely. Open Administration → Integrations, confirm the incoming webhook is enabled, and copy the full URL again. Findings never arrive, but verify passes /api/v1/me only confirms token credentials and the webhook probe only confirms reachability; neither tests a real delivery. In token mode, confirm ROCKETCHAT_DEFAULT_CHANNEL is set — without it (and without a webhook), delivery is silently skipped (logged as rocketchat delivery: skipped). In webhook mode, confirm the webhook is enabled and posts to the channel you expect.

Overview

LLM providers

Observability and incidents

Cloud, code, and collaboration

Messaging

Data and workflow systems

Prerequisites

Pick a mode

Step 1 (token mode): Create a Personal Access Token

Step 1 (webhook mode): Create an incoming webhook

Step 2 (token mode): Pick a destination channel

Step 3: Configure the integration

Option A: Onboarding wizard (recommended)

Option B: Environment variables

Step 4: Verify

Programmatic messaging: `rocketchat_send_message` tool

Background RCA completion notifications

Watchdog alarms

Scheduled deliveries (cron)

Troubleshooting

​Prerequisites

​Pick a mode

​Step 1 (token mode): Create a Personal Access Token

​Step 1 (webhook mode): Create an incoming webhook

​Step 2 (token mode): Pick a destination channel

​Step 3: Configure the integration

​Option A: Onboarding wizard (recommended)

​Option B: Environment variables

​Step 4: Verify

​Programmatic messaging: rocketchat_send_message tool

​Background RCA completion notifications

​Watchdog alarms

​Scheduled deliveries (cron)

​Troubleshooting

Prerequisites

Pick a mode

Step 1 (token mode): Create a Personal Access Token

Step 1 (webhook mode): Create an incoming webhook

Step 2 (token mode): Pick a destination channel

Step 3: Configure the integration

Option A: Onboarding wizard (recommended)

Option B: Environment variables

Step 4: Verify

Programmatic messaging: `rocketchat_send_message` tool

Background RCA completion notifications

Watchdog alarms

Scheduled deliveries (cron)

Troubleshooting