npm package: @josemaldonadojr/chat-adapter-rocketchat
Description: Rocket.Chat adapter for chat
Latest version: 0.0.1

# @chat-adapter/rocketchat

[![npm version](https://img.shields.io/npm/v/@chat-adapter/rocketchat)](https://www.npmjs.com/package/@chat-adapter/rocketchat)
[![npm downloads](https://img.shields.io/npm/dm/@chat-adapter/rocketchat)](https://www.npmjs.com/package/@chat-adapter/rocketchat)

Rocket.Chat adapter for [Chat SDK](https://chat-sdk.dev), using the [Rocket.Chat REST API](https://developer.rocket.chat/apidocs) and outgoing webhook integrations.

## Installation

```bash
npm install @chat-adapter/rocketchat
```

## Usage

```typescript
import { Chat } from "chat";
import { createRocketChatAdapter } from "@chat-adapter/rocketchat";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    rocketchat: createRocketChatAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Rocket.Chat!");
});
```

When using `createRocketChatAdapter()` without arguments, credentials are auto-detected from environment variables.

## Rocket.Chat setup

### 1. Create a bot user

1. Log in to your Rocket.Chat instance as an admin
2. Go to **Administration > Users**
3. Click **New** to create a new user
4. Set a username (e.g. `mybot`), display name, and password
5. Assign the **bot** role to the user
6. Save the user

### 2. Generate a personal access token

1. Log in as the bot user you just created
2. Go to **Profile > Personal Access Tokens** (or **My Account > Personal Access Tokens**)
3. Enter a token name and click **Add**
4. Copy the **User ID** and **Token** — you will not be able to see the token again
5. Set the following environment variables:
   - `ROCKETCHAT_USER_ID` — the bot's User ID
   - `ROCKETCHAT_TOKEN` — the personal access token

### 3. Configure an outgoing webhook

1. Log in as an admin
2. Go to **Administration > Integrations**
3. Click **New Integration** and select **Outgoing Webhook**
4. Configure the webhook:
   - **Event Trigger**: Message Sent
   - **Enabled**: True
   - **URLs**: `https://your-domain.com/api/webhooks/rocketchat`
   - **Channel**: select the channels the bot should listen in (or leave blank for all)
5. Save the integration
6. Copy the **Token** shown in the integration settings
7. Set the environment variable:
   - `ROCKETCHAT_WEBHOOK_TOKEN` — the token from step 6

### 4. Set your server URL

Set the `ROCKETCHAT_URL` environment variable to the base URL of your Rocket.Chat instance (e.g. `https://chat.example.com`).

## Configuration

All options are auto-detected from environment variables when not provided. You can call `createRocketChatAdapter()` with no arguments if the env vars are set.

| Option | Required | Description |
|--------|----------|-------------|
| `serverUrl` | No* | Base URL of the Rocket.Chat instance. Auto-detected from `ROCKETCHAT_URL` |
| `token` | No* | Personal access token for REST API auth. Auto-detected from `ROCKETCHAT_TOKEN` |
| `userId` | No* | Bot user ID for REST API auth. Auto-detected from `ROCKETCHAT_USER_ID` |
| `webhookToken` | No* | Outgoing webhook verification token. Auto-detected from `ROCKETCHAT_WEBHOOK_TOKEN` |
| `userName` | No | Bot username for mention detection. Auto-detected from `ROCKETCHAT_BOT_USERNAME` (auto-detected via `/api/v1/me` if omitted) |
| `logger` | No | Logger instance (defaults to `ConsoleLogger`) |

*Required at runtime — either via config or environment variable.

## Environment variables

```bash
ROCKETCHAT_URL=https://chat.example.com   # Base URL of the Rocket.Chat instance
ROCKETCHAT_TOKEN=...                       # Personal access token for the bot user
ROCKETCHAT_USER_ID=...                     # Bot user's ID
ROCKETCHAT_WEBHOOK_TOKEN=...               # Token from the outgoing webhook integration
ROCKETCHAT_BOT_USERNAME=mybot              # Optional — auto-detected via /api/v1/me if omitted
```

## Webhook verification

Rocket.Chat sends a `token` field in the outgoing webhook POST body. The adapter verifies that the token matches `ROCKETCHAT_WEBHOOK_TOKEN`. Requests with a missing or mismatched token are rejected with HTTP 401.

```typescript
// Next.js App Router example
import { bot } from "@/lib/bot";

export async function POST(request: Request) {
  return bot.adapters.rocketchat.handleWebhook(request);
}
```

## Features

### Messaging

| Feature | Supported |
|---------|-----------|
| Post message | Yes |
| Edit message | Yes |
| Delete message | Yes |
| Reactions | Yes (add and remove) |
| Streaming | No (Rocket.Chat has no REST streaming endpoint) |

### Rich content

| Feature | Supported |
|---------|-----------|
| Cards | Yes (rendered as formatted markdown) |
| Buttons | Yes (rendered as markdown links) |
| Tables | Yes (rendered as markdown tables) |

### Conversations

| Feature | Supported |
|---------|-----------|
| Mentions | Yes (`@username` detection) |
| DMs | Yes |
| Open DM | Yes |
| Typing indicator | No (requires WebSocket/DDP) |
| Ephemeral messages | No (server-internal only) |

### Message history

| Feature | Supported |
|---------|-----------|
| Fetch messages | Yes (paginated, timestamp-based cursors) |
| Fetch thread info | Yes |
| Fetch channel messages | Yes |
| List threads | Yes |

## Thread ID format

```
rocketchat:{roomId}:{tmid}:{roomType}
```

- `roomId` — Rocket.Chat room `_id`
- `tmid` — parent message ID for threaded replies; empty string for channel-level messages
- `roomType` — `c` (public channel), `p` (private group), `d` (DM)

Example: `rocketchat:GENERAL::c` (channel-level message in #general)

## Local development

### 1. Start Rocket.Chat with Docker

```bash
docker run -d --name rocketchat -p 3000:3000 rocket.chat
```

Open `http://localhost:3000` and complete the setup wizard. Create an admin user, then follow the [setup steps above](#rocketchat-setup) to create a bot user, generate a personal access token, and configure an outgoing webhook.

### 2. Expose your local server with ngrok

```bash
ngrok http 3001
```

Copy the ngrok HTTPS URL (e.g. `https://abc123.ngrok.io`) and update your outgoing webhook URL in Rocket.Chat to `https://abc123.ngrok.io/api/webhooks/rocketchat`.

### 3. Start your bot

```bash
ROCKETCHAT_URL=http://localhost:3000 \
ROCKETCHAT_TOKEN=your-token \
ROCKETCHAT_USER_ID=your-user-id \
ROCKETCHAT_WEBHOOK_TOKEN=your-webhook-token \
pnpm dev
```

## Troubleshooting

### Webhook not receiving messages

- Confirm the outgoing webhook integration is enabled in **Administration > Integrations**
- Check that the webhook URL is reachable from your Rocket.Chat server
- Verify that the channel filter in the webhook settings includes the channels you're testing in

### 401 Unauthorized from webhook

- Double-check that `ROCKETCHAT_WEBHOOK_TOKEN` matches the token shown in the outgoing webhook integration settings

### REST API errors (401)

- Verify `ROCKETCHAT_TOKEN` and `ROCKETCHAT_USER_ID` are correct
- Ensure the personal access token has not been revoked
- Confirm the bot user has the necessary permissions for the rooms it needs to access

### Bot not detecting mentions

- Make sure `ROCKETCHAT_BOT_USERNAME` matches the bot user's username exactly, or omit it to let the adapter auto-detect via `/api/v1/me`

## License

MIT