Skip to main content

Rocket.Chat smart home integration, free and open source

Rocket.Chat integration for Gladys Assistant

Talk to Gladys from Rocket.Chat, post to channels and run scenes on messages and commands.

View on GitHubAll integrations

Talk to Gladys from Rocket.Chat, the open-source team chat you can host yourself, the way the Telegram bot of Gladys works: ask a question, run a scene, receive the messages of Gladys in a direct message. The integration also posts in Rocket.Chat channels from your scenes, and starts scenes when a message or a command such as !lights off is written in a channel it watches. It uses a bot account of your Rocket.Chat server, on the local network or on the Internet.

Developed without the hardware: feedback welcome. The integration was tested against a real Rocket.Chat server (8.9, in Docker), but not inside a real Gladys nor with every Rocket.Chat client. Please report what works and what does not in the issues or on the Gladys forum.

What you need​

  • Gladys Assistant 5.1.0 or later.
  • A Rocket.Chat server Gladys can reach (tested with 8.9; sending images needs 6.8 or later), and an administrator account to create the bot.
  • A user for the bot, with a personal access token. Do not use your personal account: the bot answers in its name.
  • The username of each person allowed to talk to the bot, such as alice.

Set up​

  1. In Rocket.Chat, Administration → Users → New user: a username such as gladys, an email and a password, the roles bot and user.
  2. Log in to Rocket.Chat as this user, Profile → Personal access tokens: give a name, tick Ignore two-factor authentication, click Add. Copy the token and the user id shown once.
  3. In Gladys, Integrations → Rocket.Chat → Configuration:
    • Server address: the address of Rocket.Chat as in the browser, for example https://chat.example.org or http://192.168.1.20:3000.
    • User id of the bot and Personal access token: the two values of step 2.
    • Allowed people: the usernames the bot listens to, separated by commas (alice, bob), written as in Rocket.Chat: the case matters. Empty, the bot answers nobody: it ignores the messages of everyone who is not in this list.
    • Watched channels: the channels whose messages start scenes, written #name (the address https://chat.example.org/channel/garage or the id of the channel are accepted too), separated by commas. The bot joins the public channels by itself; add it to the private ones first.
    • Command prefix: ! by default (/ is taken by the slash commands of Rocket.Chat).
    • Language of the bot: the language of what the bot writes before a person is linked.
  4. Click Test the connection: the report gives the account of the bot, the watched channels it joined and the allowed people it found. The connection status of the page says it too, and names a channel or a person that was not found.

Each Gladys user who wants to talk to Gladys from Rocket.Chat does it once:

  1. In Gladys, Integrations → Rocket.Chat → Configuration, block "Link my account": click Generate a link code.
  2. In Rocket.Chat, open a direct message with the bot (the pencil icon Create new → Direct message, then its username) and send it the code (8 characters). The bot confirms: your Rocket.Chat account is linked to your Gladys user. You can unlink it from the same block.

What the bot does​

  • In a direct message with an allowed person: it passes the messages to Gladys, with the authority of the linked Gladys user, exactly like the Telegram bot: "What is the temperature in the living room?", "Turn off the lights". The answers of Gladys come back in this direct message, Markdown rendered by Rocket.Chat. The messages Gladys sends to you (the Send Message scene action, the system messages) arrive there too, even before any conversation. A camera image sent by a scene arrives as an image.
  • In a watched channel: every message of an allowed person starts the Rocket.Chat message received trigger, and a message starting with the prefix also starts Rocket.Chat command received. The bot never answers there by itself: what happens is up to your scenes.
  • In any other room (a channel that is not watched, a direct message with several people): it stays silent. Gladys never answers where others can read.
  • What it ignores: everyone who is not an allowed person, its own messages (a scene that posts in a watched channel never starts itself again), the messages of incoming webhooks and apps (even when they post in the name of an allowed person), the system messages ("joined the channel"), edits, and the messages older than 5 minutes when it reads them (a "!open garage" from two hours ago does not run now).
  • After a cut (a restart of the server, of Gladys, a network blip): it reconnects by itself, and reads back the messages of the watched channels and of the direct messages posted in the last 5 minutes.

Dashboard​

The Rocket.Chat widget shows whether the bot is connected, its account, the watched channels it is in, the last 5 messages received in the watched channels (author, text, date) and a Test the connection button. The direct messages with Gladys are never shown: everyone who sees the dashboard sees the widget.

Scenes​

Triggers​

  • Rocket.Chat message received: an allowed person wrote in a watched channel. Filters (empty = any): Channel (written as in the configuration, for example #garage) and Sender (the username, without @: alice). Variables: Message, Sender, Channel, Channel id.
  • Rocket.Chat command received: an allowed person wrote a command in a watched channel: the prefix, then a word, then optional arguments, for example !lights off kitchen. Filter Command: the word without the prefix, in lower case (lights); and Channel, Sender. Variables: Command (lights), Arguments (off kitchen), Message, Sender, Channel, Channel id. The same message also starts Rocket.Chat message received.
  • Rocket.Chat connection lost: the bot cannot reach the server any more, for a minute, or its token is refused. Variable: Error. Started once, until the connection comes back.
  • Rocket.Chat connection restored: the bot reaches the server again after a lost connection. Variable: Bot account (username).

Actions​

  • Send a Rocket.Chat message: posts a message in a channel (#name, its address or its id), or to a person in a direct message (@alice). The message accepts the scene variables and the Markdown of Rocket.Chat (**bold**, _italic_, lists, links, @here). A public channel takes the message even if the bot is not in it; a private channel only if the bot is a member. Results: Sent (yes/no), Message id, Error. A failed message does not stop the scene: test Sent with a condition if needed.

To write to one Gladys user, the Send Message action of Gladys also works: it reaches their linked Rocket.Chat account.

Scene ideas​

  • Garage by command: trigger Rocket.Chat command received, command garage, channel #garage; then a condition on the variable Arguments equal to close, and the action that closes the garage.
  • Washing machine done: when the power of the washing machine plug drops, Send a Rocket.Chat message to #family: "The washing machine is done @here".
  • Alert when the bot is cut off: trigger Rocket.Chat connection lost, then a notification through another channel (Gotify, ntfy, SMS) with the Error variable.

Troubleshooting​

  • "no Rocket.Chat server at this address": use the address you open Rocket.Chat with in a browser, without /home nor a channel. https://<address>/api/info must answer {"version":…,"success":true}.
  • "user id or access token refused": the token was removed, the user id is not the one of the token, or the bot account was deactivated. Create a new token in Profile → Personal access tokens.
  • A watched channel is not joined: the status of the page and the test name it. Check the name of the channel, add the bot to it if it is private, then save the configuration again.
  • The bot does not answer me: is your username in Allowed people, written exactly, with the same case? Do you write to it in a direct message with the bot alone? Is your account linked (the bot then gives you the instructions)?
  • A command does not start the scene: the Command filter is the word without the prefix, in lower case: lights, not !Lights.
  • Behind a reverse proxy, the WebSocket (/websocket) must be forwarded too, as for the Rocket.Chat apps.
  • More details in the logs of the integration with LOG_LEVEL=debug.

Limits​

  • A person linked to Gladys can do from Rocket.Chat everything their Gladys user can do: keep the list of allowed people short, and keep the token of the bot secret.
  • One bot account per Gladys. The bot reads the messages over the real-time API of Rocket.Chat (DDP over the WebSocket): a command takes effect in about a second. Messages missed during a cut longer than 5 minutes are skipped.
  • Files, images and voice messages sent to the bot are ignored; only text counts. Threads are read as ordinary messages, and the answers of Gladys are not posted in the thread.
  • A message holds 5000 characters by default (setting Message → Maximum allowed message size): a longer answer of Gladys is cut. The bot role is exempt from the API rate limits of the server.
  • Not affiliated with Rocket.Chat Technologies Corp. Rocket.Chat is a trademark of Rocket.Chat Technologies Corp.

Configuration settings​

These are the settings Rocket.Chat asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Getting startedsectionNoCreate a user for the bot in Rocket.Chat (Administration → Users, role bot), log in with it, create a personal access token (Profile → Personal access tokens) and copy the token and the user id. Then write to it in a direct message.
Server addressstringYesThe address of your Rocket.Chat, as in the browser, e.g. https://chat.example.org or http://192.168.1.20:3000.
User id of the botstringYesShown next to the token when you create it (17 or 24 characters).
Personal access tokensecretNoThe personal access token of the bot account (tick “Ignore two-factor authentication” when you create it).
Allowed peoplestringNoUsernames the bot listens to, separated by commas, as written in Rocket.Chat (case matters), e.g. alice, bob. Empty: the bot answers nobody.
Watched channelsstringNoChannels whose messages trigger scenes, as #name, by address or by id, separated by commas. The bot joins public channels; add it to private ones.
Command prefixstringNoA message starting with it is a command, e.g. !lights off. One to three characters.
Language of the botselectNoLanguage of what the bot writes before a person is linked, and of the reports.

How to install Rocket.Chat in Gladys​

  1. In Gladys, open Integrations: Rocket.Chat appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-rocketchat:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-rocketchat.

Rocket.Chat requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Rocket.Chat is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on