# Rocket Chat > This is comprehensive documentation for Rocket.Chat REST API, WebSocket API, webhooks, and integrations. --- # Rocket.Chat Documentation This is comprehensive documentation for Rocket.Chat REST API, WebSocket API, webhooks, and integrations. ## Table of Contents 1. REST API Reference 2. Webhooks Guide 3. Authentication Methods 4. WebSocket/Real-Time API 5. Integrations and Apps 6. Administration Guide 7. Quick Start Guide --- ## REST API Reference ### Base URL All API requests should be made to: `https://your-server.com/api/v1/` ### Authentication Most endpoints require authentication headers: ```bash X-Auth-Token: X-User-Id: ``` ### Login Endpoint POST /api/v1/login Content-Type: application/json { "user": "username", "password": "password" } Response: { "status": "success", "data": { "userId": "user_id", "authToken": "auth_token" } } ### Users API #### Create User POST /api/v1/users.create X-Auth-Token: X-User-Id: Content-Type: application/json { "name": "User Name", "email": "user@example.com", "password": "password", "username": "username" } #### List Users GET /api/v1/users.list?count=100&offset=0 X-Auth-Token: X-User-Id: #### Get User Info GET /api/v1/users.info?username=username X-Auth-Token: X-User-Id: #### Update User POST /api/v1/users.update X-Auth-Token: X-User-Id: Content-Type: application/json { "userId": "target_user_id", "data": { "name": "New Name", "email": "new@example.com" } } #### Delete User POST /api/v1/users.delete X-Auth-Token: X-User-Id: Content-Type: application/json { "userId": "user_to_delete" } ### Channels API #### Create Channel POST /api/v1/channels.create X-Auth-Token: X-User-Id: Content-Type: application/json { "name": "channel-name", "topic": "Channel topic", "members": ["user1", "user2"] } #### List Channels GET /api/v1/channels.list?count=100&offset=0 X-Auth-Token: X-User-Id: #### Get Channel Info GET /api/v1/channels.info?roomName=channel-name X-Auth-Token: X-User-Id: #### Join Channel POST /api/v1/channels.join X-Auth-Token: X-User-Id: Content-Type: application/json { "roomId": "channel_id" } #### Leave Channel POST /api/v1/channels.leave X-Auth-Token: X-User-Id: Content-Type: application/json { "roomId": "channel_id" } #### Add Members POST /api/v1/channels.addAll X-Auth-Token: X-User-Id: Content-Type: application/json { "roomId": "channel_id", "activeUsersOnly": true } #### Archive Channel POST /api/v1/channels.archive X-Auth-Token: X-User-Id: Content-Type: application/json { "roomId": "channel_id" } ### Messages API #### Send Message POST /api/v1/chat.postMessage X-Auth-Token: X-User-Id: Content-Type: application/json { "roomId": "room_id", "text": "Hello world" } #### Update Message POST /api/v1/chat.update X-Auth-Token: X-User-Id: Content-Type: application/json { "roomId": "room_id", "msgId": "message_id", "text": "Updated text" } #### Delete Message POST /api/v1/chat.delete X-Auth-Token: X-User-Id: Content-Type: application/json { "roomId": "room_id", "msgId": "message_id" } #### Get Message History GET /api/v1/channels.history?roomId=room_id&count=50 X-Auth-Token: X-User-Id: #### Search Messages GET /api/v1/chat.search?roomId=room_id&searchText=keyword X-Auth-Token: X-User-Id: ### Reactions API #### Add Reaction POST /api/v1/chat.react X-Auth-Token: X-User-Id: Content-Type: application/json { "messageId": "message_id", "emoji": ":+1:" } #### Remove Reaction POST /api/v1/chat.removeReaction X-Auth-Token: X-User-Id: Content-Type: application/json { "messageId": "message_id", "emoji": ":+1:" } --- ## Webhooks ### Incoming Webhooks Incoming webhooks allow external systems to post messages to Rocket.Chat. URL Format: https://your-server.com/hooks/webhook_id/webhook_token Example Payload: { "text": "Message from external system", "channel": "#general", "username": "bot", "attachments": [ { "title": "Attachment", "text": "Attachment text" } ] } Example cURL: curl -X POST https://rocket.example.com/hooks/abc123/xyz789 \ -H "Content-Type: application/json" \ -d '{ "text": "Hello", "channel": "#general" }' ### Outgoing Webhooks Outgoing webhooks trigger when certain events occur in Rocket.Chat. Create via API: POST /api/v1/integrations.create X-Auth-Token: X-User-Id: Content-Type: application/json { "type": "webhook-outgoing", "name": "Webhook Name", "enabled": true, "event": "message", "urls": ["https://external-system.com/webhook"], "triggerWords": ["keyword"] } --- ## Authentication Methods ### Token-Based Auth GET /api/v1/me X-Auth-Token: X-User-Id: ### Personal Access Tokens POST /api/v1/users.generatePersonalAccessToken X-Auth-Token: X-User-Id: Content-Type: application/json { "tokenName": "bot-token" } ### OAuth2 Authorization Code Flow for third-party apps. ### LDAP LDAP credentials are validated against configured LDAP server. ### SAML SAML authentication for enterprise SSO. ### JWT JSON Web Token authentication with server secret key. --- ## WebSocket/Real-Time API ### Connection ws://your-server.com/socket.io/?EIO=4&transport=websocket ### Subscribe to Room { "msg": "sub", "name": "room-messages", "params": ["room_id", false] } ### Send Message via WebSocket { "msg": "method", "method": "sendMessage", "params": [{ "_id": "unique_id", "rid": "room_id", "msg": "Message text", "ts": 1234567890 }], "id": 1 } ### Listen for Messages Messages received via WebSocket in this format: { "msg": "added", "collection": "rocketchat_message", "id": "message_id", "fields": { "_id": "message_id", "rid": "room_id", "msg": "Message text", "u": { "_id": "user_id", "username": "username" }, "ts": 1234567890 } } --- ## Integrations API ### Create Integration POST /api/v1/integrations.create X-Auth-Token: X-User-Id: Content-Type: application/json { "type": "webhook-incoming", "name": "Integration Name", "enabled": true } ### List Integrations GET /api/v1/integrations.list?count=100 X-Auth-Token: X-User-Id: ### Update Integration POST /api/v1/integrations.update X-Auth-Token: X-User-Id: Content-Type: application/json { "id": "integration_id", "name": "Updated Name", "enabled": true } ### Delete Integration POST /api/v1/integrations.remove X-Auth-Token: X-User-Id: Content-Type: application/json { "id": "integration_id" } --- ## Error Handling All endpoints return errors in this format: { "success": false, "error": "Error message", "errorType": "error-type" } Common error codes: - error-user-not-authenticated: Missing/invalid auth token - error-user-not-authorized: User lacks permission - error-room-not-found: Room/channel not found - error-user-not-found: User not found - error-invalid-file: File upload failed - error-too-many-requests: Rate limit exceeded --- ## Rate Limiting Default rate limits: - General endpoints: 120 requests per minute - Authentication: 10 requests per minute - File uploads: 3 per minute --- ## File Uploads ### Upload File POST /api/v1/rooms.upload X-Auth-Token: X-User-Id: Content-Type: multipart/form-data file: roomId: room_id description: File description --- ## Statistics API ### Server Statistics GET /api/v1/statistics X-Auth-Token: X-User-Id: Response includes: - totalRooms - totalUsers - totalChannels - totalMessages - totalConnectedUsers --- ## Admin API ### Get Server Info GET /api/v1/info X-Auth-Token: X-User-Id: ### Bulk Create Users POST /api/v1/users.bulkCreate X-Auth-Token: X-User-Id: Content-Type: multipart/form-data csv: ### Reset Password POST /api/v1/users.resetPassword X-Auth-Token: X-User-Id: Content-Type: application/json { "userId": "user_id", "password": "new_password" } --- ## Python Integration Example ```python import requests class RocketChatBot: def __init__(self, server_url, username, password): self.server_url = server_url self.session = requests.Session() response = self.session.post( f"{server_url}/api/v1/login", json={"user": username, "password": password} ) data = response.json()["data"] self.session.headers.update({ "X-Auth-Token": data["authToken"], "X-User-Id": data["userId"] }) def send_message(self, room_id, text): return self.session.post( f"{self.server_url}/api/v1/chat.postMessage", json={"roomId": room_id, "text": text} ).json() def get_messages(self, room_id, count=50): return self.session.get( f"{self.server_url}/api/v1/channels.history", params={"roomId": room_id, "count": count} ).json() # Usage bot = RocketChatBot("https://chat.example.com", "bot", "password") bot.send_message("room_id", "Hello!") ``` --- ## Node.js Integration Example ```javascript const axios = require('axios'); class RocketChatClient { constructor(serverUrl, username, password) { this.serverUrl = serverUrl; this.client = axios.create({ baseURL: serverUrl }); } async authenticate(username, password) { const response = await this.client.post('/api/v1/login', { user: username, password: password }); const { userId, authToken } = response.data.data; this.client.defaults.headers['X-Auth-Token'] = authToken; this.client.defaults.headers['X-User-Id'] = userId; return { userId, authToken }; } async sendMessage(roomId, text) { return await this.client.post('/api/v1/chat.postMessage', { roomId, text }); } async getMessages(roomId, count = 50) { return await this.client.get('/api/v1/channels.history', { params: { roomId, count } }); } } // Usage (async () => { const client = new RocketChatClient('https://chat.example.com', 'bot', 'password'); await client.authenticate('bot', 'password'); await client.sendMessage('room_id', 'Hello!'); })(); ``` --- ## Deployment ### Docker Compose ```yaml version: '3' services: rocketchat: image: rocketchat/rocket.chat:latest environment: - MONGO_URL=mongodb://mongo:27017/rocketchat - ROOT_URL=https://chat.example.com ports: - "3000:3000" depends_on: - mongo mongo: image: mongo:5.0 volumes: - mongo_data:/data/db volumes: mongo_data: ``` ### Kubernetes Use Helm charts available at https://github.com/RocketChat/helm-charts --- ## Best Practices 1. Use personal access tokens for integrations (not user passwords) 2. Always use HTTPS for production deployments 3. Implement rate limiting in your integration code 4. Log all API requests for debugging 5. Validate webhook payloads before processing 6. Use environment variables for secrets 7. Implement error handling and retries 8. Monitor API quota usage --- ## Resources - Official Documentation: https://docs.rocket.chat/ - API Reference: https://developer.rocket.chat/reference/api - GitHub Repository: https://github.com/RocketChat/Rocket.Chat - Community Forums: https://forums.rocket.chat/ - Docker Hub: https://hub.docker.com/r/rocketchat/rocket.chat --- Generated: 2026-02-04 Source: https://docs.rocket.chat/ and https://developer.rocket.chat/