Rocket.Chat
Integra Drupal con Rocket.Chat, proporcionando gestión de configuración, cliente API, incrustación del widget de livechat y funcionalidad de canales de chat grupal.
rocket_chat
Install
composer require 'drupal/rocket_chat:^3.0'
composer require 'drupal/rocket_chat:8.x-2.5'
Overview
El módulo Rocket.Chat permite a los sitios Drupal integrarse con Rocket.Chat, una plataforma de chat de equipo de código abierto. Este módulo de integración completo proporciona múltiples componentes para diferentes casos de uso.
El módulo principal gestiona la configuración de conexión y la gestión de credenciales para comunicarse con una instancia de servidor Rocket.Chat. El submódulo API proporciona una biblioteca cliente PHP completa para la API REST de Rocket.Chat, permitiendo la gestión programática de canales, usuarios, mensajes y más.
Para la interacción con visitantes, el submódulo Livechat incrusta el widget Rocket.Chat Omnichannel (Livechat 2.0) en tu sitio Drupal, habilitando soporte al cliente en tiempo real. Para sitios comunitarios, el submódulo de integración con Group conecta grupos de Drupal (del módulo Group) con canales de Rocket.Chat, creando automáticamente canales para grupos y sincronizando la membresía.
El módulo requiere una instancia de servidor Rocket.Chat (versión 1.0.0+) detrás de un proxy inverso TLS. Toda la comunicación con Rocket.Chat ocurre a través de llamadas API REST autenticadas usando credenciales de administrador configuradas en Drupal.
Features
- Conectar Drupal a un servidor Rocket.Chat con configuración de URL y credenciales de administrador
- Cliente API PHP completo para la API REST de Rocket.Chat que soporta autenticación, canales, grupos, usuarios y mensajería
- Incrustar el widget Rocket.Chat Livechat (Omnichannel 2.0) en cualquier página mediante un bloque configurable
- Integrar el módulo Group de Drupal con canales de Rocket.Chat - crear y gestionar automáticamente canales de chat grupal
- Sincronizar la membresía de grupo con la membresía de canales de Rocket.Chat (agregar/eliminar usuarios automáticamente)
- Soporte para canales públicos y grupos privados en Rocket.Chat
- Gestión de caché para canales, grupos y usuarios con actualización automática
- Tipo de campo para almacenar nombres de canal en entidades de grupo
- Visualización de iframe incrustado de canales de chat grupal para miembros autenticados
- Página de prueba de API para desarrolladores para ejecutar llamadas API REST arbitrarias
Use Cases
Soporte al cliente con Livechat
Habilita el submódulo Livechat y coloca el LiveChatBlock en la región del pie de página de tu tema. Configura agentes en los ajustes Omnichannel de tu Rocket.Chat. Los visitantes del sitio verán un widget de chat que pueden usar para comunicarse con el personal de soporte en tiempo real.
Chat grupal comunitario
Para sitios comunitarios que usan el módulo Group, habilita el submódulo rocket_chat_group. Agrega el campo Channel a tus tipos de grupo y coloca el bloque Rocket Chat Group Channel en las páginas de grupo. Los miembros del grupo serán agregados automáticamente a los canales de Rocket.Chat correspondientes, habilitando la comunicación del equipo dentro de cada grupo.
Comunicación de equipo en intranet
Configura el módulo con el servidor Rocket.Chat de tu organización. Usa la integración con Group para crear canales de chat para departamentos o equipos de proyecto. Los miembros ven un iframe de chat incrustado en las páginas de grupo, facilitando discusiones rápidas del equipo sin salir del sitio Drupal.
Desarrollo y prueba de API
Habilita el submódulo rocket_chat_api_test durante el desarrollo para experimentar con llamadas a la API de Rocket.Chat. Accede a /apitest para ejecutar varios métodos de API e inspeccionar respuestas, ayudando a los desarrolladores a entender la API antes de construir integraciones personalizadas.
Integración personalizada de Rocket.Chat
Usa las clases del submódulo rocket_chat_api en código personalizado. Instancia ApiClient con Drupal8Config para autenticar, luego llama métodos como channelsCreate(), postMessage() o usersList() para construir funcionalidad personalizada. Las clases de elementos Channel y User proporcionan interfaces orientadas a objetos para gestionar estas entidades.
Tips
- Coloca el bloque Livechat en la región del pie de página para mejor rendimiento - se carga de forma asíncrona y no bloqueará el renderizado de la página
- Usa 'Reconstruir caché de Rocketchat' después de hacer cambios directamente en Rocket.Chat para asegurar que Drupal tenga datos actuales
- Los nombres de canal se sanitizan automáticamente - los espacios se convierten en guiones bajos y los caracteres especiales se codifican con URL
- Para grupos privados, establece el tipo de grupo de Drupal a 'closed_group' - el módulo creará grupos privados de Rocket.Chat en lugar de canales públicos
- La página de prueba de API en /apitest es invaluable para entender las respuestas de la API antes de construir integraciones personalizadas
- Los datos de canales y usuarios en caché se actualizan automáticamente después de 7 días, pero puedes forzar la actualización en cualquier momento desde la página de configuración
Technical Details
Admin Pages 2
/admin/config/rocket_chat
Configura la conexión a tu instancia de servidor Rocket.Chat. Esta página te permite establecer la URL del servidor y las credenciales de administrador utilizadas para la autenticación API. El módulo valida la conexión al guardar la configuración.
/apitest
Herramienta para desarrolladores para probar llamadas a la API REST de Rocket.Chat directamente desde Drupal. Permite ejecutar solicitudes GET o POST arbitrarias a la API y ver las respuestas. Útil para depuración y exploración de la funcionalidad de la API.
Permissions 1
Hooks 5
hook_ENTITY_TYPE_insert (group_content)
Se activa cuando un usuario es agregado a un grupo de Drupal. Invita automáticamente al usuario al canal de Rocket.Chat correspondiente.
hook_ENTITY_TYPE_update (group_content)
Se activa cuando el contenido del grupo es actualizado. Procesa cambios de membresía en Rocket.Chat.
hook_ENTITY_TYPE_delete (group_content)
Se activa cuando un usuario es eliminado de un grupo de Drupal. Elimina al usuario del canal de Rocket.Chat correspondiente.
hook_theme
Implementa hook_theme para registrar la plantilla rocketChatChannelBlock para renderizar el chat incrustado.
hook_help
Proporciona texto de ayuda para la página de configuración de Rocket.Chat.
Troubleshooting 5
Asegúrate de haber iniciado sesión en tu instancia de Rocket.Chat desde la interfaz de usuario al menos una vez para establecer una sesión. También verifica que el bloque Livechat esté colocado en una región activa y que la URL del servidor esté correctamente configurada.
Verifica que la URL de tu servidor Rocket.Chat sea correcta y use HTTPS. El servidor debe estar detrás de un proxy inverso TLS. Comprueba que el servidor sea accesible desde tu servidor Drupal y responda al endpoint /api/info.
Esto indica que la configuración de la API está incompleta. Verifica que tanto el nombre de usuario como la contraseña del administrador estén ingresados correctamente en /admin/config/rocket_chat y que las credenciales tengan privilegios de administrador en el servidor Rocket.Chat.
Asegúrate de que el campo Channel tenga un valor ingresado para el grupo. Haz clic en 'Reconstruir canales de grupos' en la página de configuración para forzar la sincronización. Revisa los logs de Drupal para cualquier mensaje de error de API.
El módulo crea automáticamente usuarios en Rocket.Chat si no existen. Verifica que las credenciales de administrador tengan permiso para crear usuarios. Comprueba que los correos electrónicos de usuario sean únicos ya que Rocket.Chat usa el correo electrónico para emparejar usuarios.
Security Notes 6
- Las credenciales de administrador se almacenan en la configuración de Drupal - protege tus archivos de exportación de configuración
- El módulo requiere acceso API a nivel de administrador de Rocket.Chat para funcionalidad completa incluyendo creación de usuarios
- Los tokens de autenticación se almacenan en el sistema de estado de Drupal, no se exportan con la configuración
- Solo otorga el permiso 'administer rocketchat configuration' a administradores de confianza
- El servidor Rocket.Chat debe usar HTTPS - el módulo solo soporta conexiones cifradas con TLS
- Las contraseñas de usuario creadas en Rocket.Chat son cadenas hexadecimales de 512 bytes generadas aleatoriamente - los usuarios deben autenticarse vía SSO u OAuth en lugar de inicio de sesión directo