Rocket.Chat
Integrates Drupal with Rocket.Chat, providing configuration management, API client, livechat widget embedding, and group chat channel functionality.
rocket_chat
Install
composer require 'drupal/rocket_chat:^3.0'
composer require 'drupal/rocket_chat:8.x-2.5'
Overview
The Rocket.Chat module enables Drupal sites to integrate with Rocket.Chat, an open-source team chat platform. This comprehensive integration module provides multiple components for different use cases.
The main module handles connection configuration and credentials management for communicating with a Rocket.Chat server instance. The API submodule provides a complete PHP client library for the Rocket.Chat REST API, allowing programmatic management of channels, users, messages, and more.
For visitor engagement, the Livechat submodule embeds the Rocket.Chat Omnichannel (Livechat 2.0) widget on your Drupal site, enabling real-time customer support. For community sites, the Group integration submodule connects Drupal groups (from the Group module) with Rocket.Chat channels, automatically creating channels for groups and synchronizing membership.
The module requires a Rocket.Chat server instance (version 1.0.0+) behind a TLS reverse proxy. All communication with Rocket.Chat occurs through authenticated REST API calls using admin credentials configured in Drupal.
Features
- Connect Drupal to a Rocket.Chat server with URL and admin credential configuration
- Complete PHP API client for Rocket.Chat REST API supporting authentication, channels, groups, users, and messaging
- Embed Rocket.Chat Livechat (Omnichannel 2.0) widget on any page via a configurable block
- Integrate Drupal Group module with Rocket.Chat channels - automatically create and manage group chat channels
- Synchronize group membership with Rocket.Chat channel membership (add/remove users automatically)
- Support for both public channels and private groups in Rocket.Chat
- Cache management for channels, groups, and users with automatic refresh
- Field type for storing channel names on group entities
- Embedded iframe display of group chat channels for authenticated members
- API testing page for developers to execute arbitrary REST API calls
Use Cases
Customer Support with Livechat
Enable the Livechat submodule and place the LiveChatBlock in your theme's footer region. Configure agents in your Rocket.Chat Omnichannel settings. Site visitors will see a chat widget they can use to communicate with support staff in real-time.
Community Group Chat
For community sites using the Group module, enable the rocket_chat_group submodule. Add the Channel field to your group types and place the Rocket Chat Group Channel block on group pages. Group members will automatically be added to corresponding Rocket.Chat channels, enabling team communication within each group.
Intranet Team Communication
Configure the module with your organization's Rocket.Chat server. Use the Group integration to create chat channels for departments or project teams. Members see an embedded chat iframe on group pages, facilitating quick team discussions without leaving the Drupal site.
API Development and Testing
Enable the rocket_chat_api_test submodule during development to experiment with Rocket.Chat API calls. Access /apitest to execute various API methods and inspect responses, helping developers understand the API before building custom integrations.
Custom Rocket.Chat Integration
Use the rocket_chat_api submodule's classes in custom code. Instantiate ApiClient with Drupal8Config to authenticate, then call methods like channelsCreate(), postMessage(), or usersList() to build custom functionality. The Channel and User element classes provide object-oriented interfaces for managing these entities.
Tips
- Place the Livechat block in the footer region for best performance - it loads asynchronously and won't block page rendering
- Use 'Rebuild Rocketchat Cache' after making changes directly in Rocket.Chat to ensure Drupal has current data
- Channel names are automatically sanitized - spaces become underscores and special characters are URL encoded
- For private groups, set the Drupal group type to 'closed_group' - the module will create private Rocket.Chat groups instead of public channels
- The API test page at /apitest is invaluable for understanding API responses before building custom integrations
- Cached channel and user data automatically refreshes after 7 days, but you can force refresh anytime from the settings page
Technical Details
Admin Pages 2
/admin/config/rocket_chat
Configure the connection to your Rocket.Chat server instance. This page allows you to set the server URL and admin credentials used for API authentication. The module validates the connection when saving settings.
/apitest
Developer tool for testing Rocket.Chat REST API calls directly from Drupal. Allows executing arbitrary GET or POST requests to the API and viewing responses. Useful for debugging and exploring API functionality.
Permissions 1
Hooks 5
hook_ENTITY_TYPE_insert (group_content)
Triggers when a user is added to a Drupal group. Automatically invites the user to the corresponding Rocket.Chat channel.
hook_ENTITY_TYPE_update (group_content)
Triggers when group content is updated. Processes membership changes in Rocket.Chat.
hook_ENTITY_TYPE_delete (group_content)
Triggers when a user is removed from a Drupal group. Removes the user from the corresponding Rocket.Chat channel.
hook_theme
Implements hook_theme to register the rocketChatChannelBlock template for rendering embedded chat.
hook_help
Provides help text for the Rocket.Chat configuration page.
Troubleshooting 5
Ensure you have logged into your Rocket.Chat instance from the UI at least once to establish a session. Also verify the Livechat block is placed in an active region and the server URL is correctly configured.
Verify your Rocket.Chat server URL is correct and uses HTTPS. The server must be behind a TLS reverse proxy. Check that the server is accessible from your Drupal server and responding to /api/info endpoint.
This indicates the API configuration is incomplete. Verify both admin username and password are entered correctly at /admin/config/rocket_chat and that the credentials have admin privileges on the Rocket.Chat server.
Ensure the Channel field has a value entered for the group. Click 'Rebuild Groups Channels' on the configuration page to force synchronization. Check Drupal logs for any API error messages.
The module automatically creates users in Rocket.Chat if they don't exist. Verify the admin credentials have permission to create users. Check that user emails are unique as Rocket.Chat uses email for user matching.
Security Notes 6
- Admin credentials are stored in Drupal configuration - protect your config export files
- The module requires admin-level API access to Rocket.Chat for full functionality including user creation
- Authentication tokens are stored in Drupal's state system, not exported with configuration
- Only grant 'administer rocketchat configuration' permission to trusted administrators
- The Rocket.Chat server must use HTTPS - the module only supports TLS-encrypted connections
- User passwords created in Rocket.Chat are randomly generated 512-byte hex strings - users should authenticate via SSO or OAuth rather than direct login