Rocket.Chat API

Next

Welcome to the Rocket.Chat API documentation! This guide is designed to help you interact effectively with Rocket.Chat’s REST API endpoints, Realtime API methods, and Livechat Widget API.

Our APIs enable you to integrate, automate, and extend Rocket.Chat, allowing you to manage workspaces, users, rooms, and applications, and to build seamless communication experiences.

Available APIs

Rocket.Chat provides the following APIs:

Rocket.Chat’s REST API

Follows REST (Representational State Transfer) principles and supports standard HTTP methods, GET, POST, PUT, and DELETE, for performing operations on various resources.

Livechat Widget API

Enables developers to integrate Omnichannel Livechat functionalities directly into their applications.

Realtime API

This allows developers to integrate Rocket.Chat’s real-time messaging and collaboration features in their applications through websockets.

Additional information

Schema definition provides an overview of the structure and fields used in Rocket.Chat schema. Deprecated endpoints and parameters provide details on deprecated and removed endpoints and parameters.

Rocket.Chat REST API

Security considerations for production environments

Securing your production environment is essential when using the Rocket.Chat REST API. Follow these guidelines to help ensure data confidentiality and prevent unauthorized access:

  • Always use the Login API exclusively over HTTPS during authentication to protect user credentials.

  • Enforce a strict token management policy that includes regular token expiration and renewal to minimize the risk of unauthorized access.

  • Carefully configure user permissions. Assigning precise access rights to endpoints is critical to prevent unauthorized actions and potential data breaches.

Rate Limiting

Rate limiting is an essential mechanism in Rocket.Chat that controls the frequency of API requests. It helps maintain server stability, prevent misuse, and ensure fair resource usage across all users. By default, rate limiting is enabled for all endpoints.

Enabling and configuring the rate limiter

To enable or modify rate limiting in your workspace:

  1. Go to Administration → Workspace → Settings → Rate Limiter → API Rate Limiter.

  2. Adjust the following settings as needed:

    • Enable Rate Limiter: Activates rate limiting for REST API endpoints.

    • Enable Rate Limiter in Development: Applies rate limiting in the development environment.

    • Default number of calls to the rate limiter: Defines the number of API calls allowed per endpoint within the configured time window.

    • Default time limit for the rate limiter (in ms): Specifies the time window (in milliseconds) used for counting requests.

  3. Click Save Changes

To disable the rate limiter, assign the api-bypass-rate-limit permission to the appropriate user role.

Additional rate limiting options

  • DDP Rate Limit: Controls the rate of requests sent or received through the DDP protocol to prevent excessive message traffic.

  • Feature Limiting: Allows you to restrict access or limit usage of specific Rocket.Chat features, providing another layer of protection against overuse.

Customizing rate limits in code

To modify or disable rate limiting for a specific API endpoint programmatically, use the .addRoute function and configure the rateLimiterOptions property within the route definition.

  • Set rateLimiterOptions: false to disable rate limiting for that endpoint.

  • Alternatively, define a custom configuration object, e.g.:

    { numRequestsAllowed: 10, intervalTimeInMS: 60000 }

    to control the number of allowed requests and the reset interval.

Response headers

When rate limiting is enabled, API responses include the following headers:

  • x-ratelimit-limit: Maximum number of calls allowed in the current window.

  • x-ratelimit-remaining: Number of remaining calls available before the limit resets.

  • x-ratelimit-reset: Time (in UTC epoch milliseconds) when the rate limit will reset.

These headers help you monitor and manage your application’s request usage in real time.

Some endpoints, such as /api/v1/users.updateOwnBasicInfo, always trigger rate limiting and cannot be customized or disabled through the administration panel.

Language-specific wrappers

Rocket.Chat does not maintain these wrappers. They are developed and supported by community contributors.

You can use the following community-maintained libraries to interact with Rocket.Chat APIs in different programming languages:

If your preferred language isn’t listed, you can submit a feature request to suggest adding new API wrappers to Rocket.Chat.