Rocket.Chat exposes more than one API surface. This document helps you pick the right one for your use case in under a minute.
The short answer
Use the REST API by default. It covers the widest range of operations and is the simplest to integrate.
Use the Realtime API when your application must react to events as they happen; for example, streaming new messages over a persistent connection.
Use the Livechat Widget API only to control the Livechat widget embedded on your own website.
Compare at a glance
REST API | Realtime API | Livechat Widget API | |
|---|---|---|---|
Transport | HTTPS request/response | WebSocket (DDP) | JavaScript, in the visitor's browser |
Best for | Integrations, automation, provisioning, bots that act on demand | Chat clients and apps that need live updates and event subscriptions | Customizing the Livechat widget's behavior and appearance on your site |
Authentication |
| Login method over the WebSocket connection | Runs in the widget; no workspace credentials |
Where to start |
REST API
The REST API follows standard HTTP semantics (GET, POST, PUT, DELETE) against https://<your-workspace-url>/api/v1/. It is the most complete surface: messaging, rooms, users, teams, settings, and administration are all available. Choose it for server-side integrations, scripts, provisioning and user management, webhooks-style bots, and anything that acts on demand rather than listening continuously.
Start with Authenticate a REST Client, then browse the endpoint sections in the left navigation.
Realtime API
The Realtime API communicates over WebSockets using method calls and subscriptions. It lets your application receive events the moment they happen — new messages in a room, user presence changes, typing indicators — without polling. Choose it when you are building a chat client or any application that must keep a live view of the workspace.
Livechat Widget API
The Livechat Widget API is a client-side JavaScript API for the Livechat widget you embed on your website. Use it to configure the widget, react to visitor events, and pass visitor data from your site into the conversation. It controls the widget itself; for server-side operations use the REST API.
Combining them
The surfaces are not mutually exclusive. A common pattern for bots and clients is to use the Realtime API to subscribe to events (for example, new messages) and the REST API to act on them (for example, posting a reply). The REST API is the more stable surface for write operations.
Want to extend Rocket.Chat from the inside instead of calling it from outside? Build an app with the Apps-Engine, see Build Your First Apps-Engine App.