Rocket.Chat API Wrapper

Common errors

• AttributeError: 'dict' object has no attribute 'json'

  cause Attempting to call `.json()` on the result of an API method after upgrading to v2.0.0 or later. Methods now directly return the JSON-parsed response.
  fix Remove the `.json()` call. The API method already returns the dictionary or list directly. Example: Change `rocket.me().json()` to `rocket.me()`.

• rocketchat_API.rocketchat.RocketChatAPIException: Unauthorized

  cause Incorrect username, password, or authentication token, or an invalid Rocket.Chat server URL/port.
  fix Double-check your `ROCKETCHAT_USER`, `ROCKETCHAT_PASS` (or `ROCKETCHAT_AUTH_TOKEN`), `ROCKETCHAT_HOST`, `ROCKETCHAT_SCHEME`, and `ROCKETCHAT_PORT` environment variables or settings passed to `RocketChatAPI`. Verify network connectivity to the Rocket.Chat server.

• rocketchat_API.rocketchat.RocketChatAPIException: User not found

  cause Attempting to access information or perform an action for a user that does not exist on the Rocket.Chat instance or for whom the authenticated user lacks permissions.
  fix Verify the username or user ID is correct. Ensure the user associated with the API credentials has the necessary permissions to view or interact with the target user.

• TypeError: addUserToRole() got an unexpected keyword argument 'role_name'

  cause Calling `addUserToRole` (or `removeUserFromRole`) with `role_name` after upgrading to v2.1.0, which changed the parameter to `role_id`.
  fix Update the method call to use `role_id` instead of `role_name`. You may need to fetch the `_id` of the role first via the roles API.

• rocketchat_API.rocketchat.RocketChatAPIException: MethodNotFound

  cause Attempting to call an API method that either does not exist, has been removed from the Rocket.Chat API (or the library wrapper), or the user lacks permissions for.
  fix Consult the `rocketchat-api` library documentation and Rocket.Chat API documentation for the correct method name and available endpoints. If a method was deprecated, look for an alternative.

Warnings

• breaking Starting with v3.0.0, the library's exception handling was reworked. Exceptions now carry more detailed error information. Code relying on generic exception catching or checking specific exception attributes might need updates.
  Fix: Catch `RocketApiException` and access error details via its attributes (e.g., `e.error`). Update any conditional logic that inspects exception messages to use these new attributes for robustness.
• breaking In v2.1.0, several API method signatures changed. `rooms_upload` was removed. `addUserToRole` and `removeUserFromRole` now require `role_id` instead of `role_name`. `users_create_token` no longer accepts `username` but requires a `secret` parameter.
  Fix: Review calls to affected methods and update parameters accordingly. For `users_create_token`, pass the `secret` value. For role management, ensure you're passing the `role_id`.
• breaking As of v2.0.0, API methods no longer return the raw `requests` response object directly. Instead, they return the JSON body of the response, often as a dictionary or list. Calling `.json()` on the return value will result in an `AttributeError`.
  Fix: Remove `.json()` calls from the end of API method invocations. The methods directly return the parsed JSON response. For example, change `rocket.me().json()` to `rocket.me()`.
• gotcha When providing a custom port for the Rocket.Chat instance, ensure it is passed as an integer in the `settings` dictionary during `RocketChatAPI` initialization, even if read from environment variables (which are strings).
  Fix: Convert the port string to an integer before passing it to the `RocketChatAPI` constructor, e.g., `port=int(os.environ.get('ROCKETCHAT_PORT', 443))`.

Install

• pip install rocketchat-api Install latest version

Imports

• RocketChatAPI

  from rocketchat_API.rocketchat import RocketChatAPI

Quickstart

Initializes the RocketChatAPI client using environment variables for credentials and connects to a Rocket.Chat instance. It then demonstrates fetching the current user's information and sending a public message. Ensure you replace 'your_username' and 'your_password' with actual credentials or set the corresponding environment variables.

import os
from rocketchat_API.rocketchat import RocketChatAPI

# Configure connection details and credentials via environment variables for security
ROCKETCHAT_SCHEME = os.environ.get('ROCKETCHAT_SCHEME', 'https')
ROCKETCHAT_HOST = os.environ.get('ROCKETCHAT_HOST', 'demo.rocket.chat')
ROCKETCHAT_PORT = os.environ.get('ROCKETCHAT_PORT', '443') # Note: Port should be string for consistent config
ROCKETCHAT_USER = os.environ.get('ROCKETCHAT_USER', 'your_username')
ROCKETCHAT_PASS = os.environ.get('ROCKETCHAT_PASS', 'your_password')

rocket = RocketChatAPI(settings={
    'scheme': ROCKETCHAT_SCHEME,
    'host': ROCKETCHAT_HOST,
    'port': int(ROCKETCHAT_PORT), # Ensure port is int if expected by library
    'username': ROCKETCHAT_USER,
    'password': ROCKETCHAT_PASS
})

# Example: Get information about the current user
try:
    me_info = rocket.me().json()
    print(f"Logged in as: {me_info.get('username')}")
except Exception as e:
    print(f"Error connecting or authenticating: {e}")

# Example: Send a direct message
try:
    if me_info and 'username' in me_info:
        # Replace 'otheruser' with a valid Rocket.Chat username to send a message to
        response = rocket.chat_post_message(room_id='GENERAL', text='Hello from rocketchat-api!').json()
        print(f"Message sent status: {response.get('success')}")
except Exception as e:
    print(f"Error sending message: {e}")