Summary

In addition to the existing providers, I would like to be able to use Clawdbot with Rocket.Chat

Proposed solution

Build a Rocket.Chat provider

Alternatives considered

No alternative considered

Additional context

Here's a prompt for Codex that Clawdbot came up with:

Prompt: Build Rocket.Chat Provider for Clawdbot

Context

I'm building a Rocket.Chat provider integration for Clawdbot (https://github.com/clawdbot/clawdbot). Clawdbot is a personal AI assistant gateway that currently supports Telegram, WhatsApp, Discord, Slack, Signal, and iMessage as messaging providers.

I want to add Rocket.Chat as a new provider so I can use Clawdbot at work with my work-issues Anthropic account. This needs to work WITHOUT requiring server-side changes or IT involvement — I'll authenticate with my own Rocket.Chat credentials and connect via the public API.

Goal

Create a Rocket.Chat provider that:

1. Authenticates with username/password or personal access token
2. Connects to the Realtime API (WebSocket) to receive incoming messages
3. Uses the REST API to send messages back
4. Integrates with Clawdbot's existing gateway architecture
5. Runs entirely on my local machine (no Rocket.Chat App installation needed)

Rocket.Chat API Reference

Authentication

POST /api/v1/login
Body: { "user": "username", "password": "password" }
Response: { "authToken": "...", "userId": "..." }

# Or use Personal Access Token:
Headers: X-Auth-Token, X-User-Id

REST API - Sending Messages

POST /api/v1/chat.postMessage
Headers: X-Auth-Token, X-User-Id
Body: {
  "channel": "#general" or "@username" or "roomId",
  "text": "Hello!",
  "attachments": [...] // optional
}

Realtime API - Receiving Messages

WebSocket connection to: wss://<server>/websocket

// Connect and login
{ "msg": "connect", "version": "1", "support": ["1"] }
{ "msg": "method", "method": "login", "params": [{ "resume": authToken }], "id": "1" }

// Subscribe to messages
{ "msg": "sub", "id": "unique-id", "name": "stream-room-messages", "params": ["__my_messages__", false] }

// Incoming messages arrive as:
{ "msg": "changed", "collection": "stream-room-messages", "fields": { "args": [{ "_id": "...", "msg": "...", "u": {...}, "rid": "..." }] } }

Key Endpoints

• GET /api/v1/me — Get current user info
• GET /api/v1/channels.list — List channels
• GET /api/v1/groups.list — List private groups
• GET /api/v1/dm.list — List DMs
• GET /api/v1/channels.history?roomId=... — Get message history
• POST /api/v1/chat.react — Add reaction

Clawdbot Architecture

Look at the existing provider implementations for patterns:

• src/telegram/ — Telegram bot provider (good reference for bot-style integration)
• src/web/ — WhatsApp Web provider (good reference for credential-based auth)
• src/discord/ — Discord provider
• src/slack/ — Slack provider

Key patterns to follow:

1. Provider Structure:

src/rocketchat/
  ├── index.ts          # Exports
  ├── monitor.ts        # Main message monitoring/WebSocket handler
  ├── send.ts           # Send message functions
  ├── login.ts          # Authentication
  ├── types.ts          # TypeScript types
  └── probe.ts          # Health check

2. Configuration (clawdbot.json):

{
  "rocketchat": {
    "enabled": true,
    "serverUrl": "https://chat.example.com",
    "username": "myuser",
    "password": "...",  // or use personalAccessToken
    "personalAccessToken": "...",
    "userId": "...",
    "allowFrom": ["roomId1", "roomId2"]  // optional allowlist
  }
}

3. Gateway Integration:
   The provider needs to:

• Register with the gateway server (src/gateway/server-providers.ts)
• Emit inbound messages in the standard envelope format
• Handle outbound messages from the agent

4. Inbound Message Envelope:

interface InboundEnvelope {
  provider: 'rocketchat';
  chatId: string;        // room ID
  messageId: string;
  senderId: string;
  senderName: string;
  text: string;
  timestamp: Date;
  isGroup: boolean;
  replyToMessageId?: string;
  attachments?: Attachment[];
}

5. Outbound Message Handling:

async function sendRocketChatMessage(params: {
  roomId: string;
  text: string;
  replyToMessageId?: string;
  attachments?: Attachment[];
}): Promise<{ messageId: string }>;

Implementation Steps

1. Create authentication module (login.ts)

   • Support username/password login
   • Support personal access token
   • Store and refresh auth tokens
   • Handle token expiration

2. Create WebSocket monitor (monitor.ts)

   • Connect to Realtime API
   • Authenticate over WebSocket
   • Subscribe to stream-room-messages for __my_messages__
   • Parse incoming messages into standard envelope format
   • Handle reconnection on disconnect
   • Implement typing indicators (optional)

3. Create send module (send.ts)

   • POST to /api/v1/chat.postMessage
   • Handle attachments/files
   • Support replies (threads)
   • Support reactions

4. Create probe/health check (probe.ts)

   • Call /api/v1/me to verify connection
   • Return connection status

5. Register provider in gateway

   • Add to src/gateway/server-providers.ts
   • Add config schema to src/config/types.ts
   • Add to provider list in relevant places

6. Handle edge cases:

   • Rate limiting (Rocket.Chat has rate limits)
   • Message attachments (images, files)
   • Threads/replies
   • Mentions (@user)
   • Reactions
   • Edit/delete messages
   • Group vs DM detection

Testing

1. Generate a Personal Access Token in Rocket.Chat:

   • Profile → My Account → Personal Access Tokens → Add

2. Test authentication:

curl -H "X-Auth-Token: TOKEN" -H "X-User-Id: USERID" \
  https://chat.example.com/api/v1/me

3. Test sending a message:

curl -X POST -H "X-Auth-Token: TOKEN" -H "X-User-Id: USERID" \
  -H "Content-Type: application/json" \
  -d '{"channel": "@username", "text": "Hello from API!"}' \
  https://chat.example.com/api/v1/chat.postMessage

Reference Documentation

• Rocket.Chat REST API: https://developer.rocket.chat/apidocs
• Rocket.Chat Realtime API: https://developer.rocket.chat/apidocs/realtimeapi
• Message schema: https://developer.rocket.chat/apidocs/schema-definition

Notes

• The Realtime API uses DDP (Distributed Data Protocol) over WebSocket
• You might want to use a DDP client library like ddp.js or implement raw WebSocket
• Personal Access Tokens are preferred over password auth for security
• Consider implementing reconnection logic with exponential backoff
• Rocket.Chat servers may have different API versions — target v1 API

Success Criteria

When complete, I should be able to:

1. Configure Rocket.Chat credentials in clawdbot.json
2. Start the gateway and see "Rocket.Chat: connected" in logs
3. Send a DM to myself (or a test room) and have Clawdbot respond
4. See typing indicators while Clawdbot is processing (nice to have)
5. Handle attachments in both directions (nice to have)

Good luck! Start with the simplest possible implementation (auth + receive + send text) and iterate from there.