@chat-adapter/rocketchat

Rocket.Chat adapter for Chat SDK, using the Rocket.Chat REST API and outgoing webhook integrations.

Installation

npm install @chat-adapter/rocketchat

Usage

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

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.

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

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 to create a bot user, generate a personal access token, and configure an outgoing webhook.

2. Expose your local server with ngrok

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

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