> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rocket.Chat

> Deliver investigation findings to a Rocket.Chat channel.

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.

<Note>
  Rocket.Chat support is **outbound delivery only** (investigation reports posted to a channel). Triggering investigations from Rocket.Chat chat is not supported yet.
</Note>

***

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

1. Sign in to Rocket.Chat with the account that should post findings.
2. Open **My Account → Personal Access Tokens** (avatar menu → **My Account**).
3. Enter a token name (e.g. `opensre`) and select **Add**. Leave *Ignore Two Factor Authentication* checked unless your policy requires otherwise.
4. 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.

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

***

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

1. As an admin, open **Administration → Workspace → Integrations → New → Incoming**.
2. Enable the integration, set a name (e.g. `opensre`), pick the destination **channel**, and choose the user the messages post as.
3. 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:

```text theme={null}
/onboard
```

CLI:

```bash theme={null}
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** (system keyring, not plain `.env`), **user ID** (`ROCKETCHAT_USER_ID`), and **default channel** (`ROCKETCHAT_DEFAULT_CHANNEL`)
* Webhook mode: **webhook URL** — saved to the integration store only (`~/.opensre/integrations.json`), never written to `.env`, since the URL embeds its token

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

### Option B: Environment variables

Set in `.env`:

```bash theme={null}
# 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.                                                     |
| `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. 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.

***

## Step 4: Verify

Interactive shell:

```text theme={null}
/integrations verify rocketchat
```

Or:

```text theme={null}
/verify rocketchat
```

CLI:

```bash theme={null}
opensre integrations verify rocketchat
```

With token credentials configured, this calls Rocket.Chat's [`/api/v1/me`](https://developer.rocket.chat/apidocs/get-user-information) 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:

```text theme={null}
/investigate tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json
```

CLI:

```bash theme={null}
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.

***

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