Manage rooms

Introduction

Group discussions take place in rooms.

NOTE. Before you add a new room, you can create a space for it. For instructions, refer to Manage spaces.

Manage rooms

Create a room

The below instructions are about adding a new room to a space. If you want to start a one-to-one chat, refer to Find and invite your colleagues, instead.

1. Navigate to the side bar on the left and right-click the space where you want to add a new room. Select Room.

2. Enter the name and topic of your room. The topic is optional.

3. Open the drop-down menu to select the visibility setting of your room:

   • Visible to space members. Everyone in the space will be able to find and join your room.

   • Private room. Only people invited will be able to find and join your room.

   • Public room. Anyone will be able to find and join your room.

     NOTE. You can change these settings later.

4. A. Click the toggle to enable or disable end-to-end encryption. This option may be disabled or enabled by default in some organizations.

   NOTE. You cannot disable this later.

   B. If your room is a public room, enter a room address for you room.

5. For advanced settings, select Show advanced.

   Under the advanced settings, you can block anyone who is not part of the same server from ever joining your room. You can enable this setting if the room is only used for collaborating with internal teams on your homeserver.
   Click the toggle to enable or disable this setting.

   NOTE. This setting cannot be changed later.

6. Finish by selecting Create room.

Add an existing room

Instead of creating a new room, you can also add an already existing room to your space.

1. Navigate to the side bar on the left and click the space where you want to add an existing room.

2. Click the + icon at the top and select Add existing room.

3. Select the room(s) that you want to add from the list. You can also use the search bar to search for rooms.

4. Finish by selecting Add.

Share a room

NOTE. If the room is private, the user needs an invitation from the room admin to join the room.

1. Click the info icon at the top right corner of the chat.

2. Select Share room.

3. There are several ways to share the room:

   • Copy the link. Select the Link to most recent message checkbox if you want to share a link to the most recent message in the room.

   • Share the link on social media. Share the link on Facebook, X, LinkedIn, and Reddit.

   • Share the link via email.

   • Share a QR code. Right-click the QR code to copy or save the image.

Remove a room from a space

1. Navigate to the side bar and click the space where the room is located.

2. In the middle panel, select the room that you want to remove and click Remove.

Join a public room

1. Select Home from the side bar.

2. Click the + icon at the top and select Join public room.

   You can scroll the list of suggested public rooms or use the search bar to search for them.

   You can even search for public rooms in other servers. To open the server list, click the drop-down menu at the right side of the window.

   Select View to preview a public room before joining. If you want to join the room, select Join the discussion at the bottom of the room.

   Select Join to join a public room.

Leave a room

1. Go go to room and click info icon at the top right corner of the chat and select Leave.

   NOTE. If you are the only person in the room, no one will be able to join it in the future, including you.

2. Confirm by reselecting Leave.

Add a room to favorites

1. Navigate to the side bar and click the space where the room is located.

2. Click the three dots on the room and select Favorite.

   The room appears under the Favorites tab.

   To remove a room from favorites, select Favorited. The room disappears from the Favorites tab and reappears under the Rooms tab.

Manage room settings

There are two ways to access the room settings:

• From the left panel:
• From the info tab:

Change room name, topic and picture

1. Go to room settings

2. Under the General tab, enter the new name, topic, and picture of the room.

3. Finish by selecting Save.

Manage URL previews

URL previews in messages give more information about the shared link, such as the title, description, and image from the website.

In encrypted rooms, URL previews are disabled by default. This is to make sure that your homeserver can't gather information about the links you see in rooms.

To enable or disable URL previews:

1. Go to room settings
2. Under the General tab, scroll down to Other and URL Previews, and click the toggle to enable or disable URL previews.
   NOTE. This affects only you.

Change encryption settings

NOTE. Once enabled, encryption cannot be disabled.

1. Go to room settings -> Security & Privacy tab.

2. If you did not enable encryption when you created this room, you can enable it here.

   Click the toggle to enable or disable sending encrypted messages to unverified devices in this room from this device. The default setting: off

Define who can join your room

1. Go to room settings -> Security & Privacy tab.

2. Under Access, select who can join your room.

Define who can read room history

1. Go to room settings -> Security & Privacy tab.

2. Under Who can read history?, select the members who can read room history.

NOTE. This option is only available for public rooms.

Edit privileged user roles

1. Go to room settings -> Roles & Permissions tab.

2. Under Privileged Users, click the privileged user whose role you want to to edit.

   You can select from the following roles:

   • Admin. Can do all administrative tasks in the room.
   • Moderator. Can do some administrative tasks in the room.
   • Default. No administrative tasks in the room.

Add privileged users

1. Go to room and click the info icon at the top right corner of the chat.

2. Go to members and select the member you want to grant privileges to

3. Open the drop-down menu to select the role. You can select from the following roles:

   • Admin. Can do all administrative tasks in the room. NOTE. You can't undo this change as you are promoting the user to have the same role as you.

   • Moderator. Can do some administrative tasks in the room.

   • Default. No administrative tasks in the room.

Change notification settings

1. Navigate to the side bar and click the space where the room is located.
2. Click the Notification options icon on the room. You can choose from the following options:
   • Match default setting. Matches the default notification settings of your account. For more information, refer to Manage your settings > Change notification settings.
   • All messages. Show all notifications.
   • Mentions & keywords. Show a notification when someone mentions you or uses keywords.
   • Mute room. Mute all notifications from this room.

Set a custom notification sound

1. Go to room settings -> Notifications tab.

2. Click Browse to select a custom sound.

3. Finish by selecting Save.

View room information

1. Go to room settings -> Advanced tab.

   You can copy the internal room ID and view the room version.

Manage room members

Invite a user

1. Navigate to the side bar and click the space where the room is located.

2. Click the three dots on the room and select Invite.

3. Enter a name, email address, or username into the text field. Users that are already using Secure Messaging appear on the Suggestions list below.

   NOTE. Some suggestions may be hidden for privacy.

4. A. If the user is on the list, click it and select Invite.

   

   B. If you can't find the user on the list, you can share the room with them. Click share this room and follow the instructions.

   Once the user receives the invitation, they have three options to choose from:

   • Accept. The user accepts the invitation and joins the room.
   • Reject and ignore user. The user rejects the invitation and ignores the user. The user can no longer invite the user to a room.
   • Reject. The user rejects the invitation.

Revoke invitation

1. Click the info icon at the top right corner of the chat.

2. Select Members.

3. Under Invited, click the user whose invitation you want to revoke.

4. Under Admin tools, select Revoke invite.

Remove a user

1. Click the room.

2. Click the info icon at the top right corner of the room.

3. Select Members.

4. Click the user who you want to remove.

5. Under Admin tools, select Remove from room.

Ignore a user

Ignoring a user hides all messages and invites from them.

1. Click the room.

2. Click the info icon at the top right corner of the room.

3. Select Members.

4. Click the user who you want to ignore.

5. Under Options, select Ignore.

6. Confirm by reselecting Ignore.

   To unignore a user, select Unignore.

Mute a user

Muting a user prevents them from posting to the room. However, they can still see the room.

1. Click the room.
2. Click the info icon at the top right corner of the room.
3. Select Members.
4. Click the user who you want to mute.
5. Under Admin tools, select Mute. To unmute a user, select Unmute.

Ban a user

Banning a user bans them from the room. They can no longer see the room or join the conversation.

1. Click the room.
2. Click the info icon at the top right corner of the room.
3. Select Members.
4. Click the user who you want to ban from the room.
5. Under Admin tools, select Ban from room. To unban a user, select Unban from room.

Remove a user's recent messages

Removing a user's recent messages removes messages sent by that user permanently for everyone in the conversation. For a large amount of messages, this might take some time. Do not refresh the client in the meantine.

1. Click the room.

2. Click the info icon at the top right corner of the room.

3. Select Members.

4. Click the user whose messages you want to remove.

5. Under Admin tools, select Remove recent messages.

6. Check the Preserve system messages option if you don't want to remove system messages, such as membership changes and profile changes, on this user.

   Uncheck the option if you want to remove all messages on this user, including the system messages.

7. Finish by selecting Remove Messages.

Adding Integrations/Bots

SSH Secure Messaging has several bots and integrations that can be added to rooms. These bots and integrations must be setup and configured by a system administrator with access to the SSH Secure Messaging backend and the third-party service which the bot may be interacting with. Once these integrations have been enabled, they will appear as user accounts and can be added to the room by inviting the user account.

Interaction with these bots typically involves using the "!" mark followed by the bot name and the bot command, for example:

!botname <command>

All bots have a help menu that lists the bot commands and room-specific configurations. You can view the help menu by using the following command:

!botname help

Jira Integration

The Jira integration connects a Jira DC or Jira Cloud instance to the SSH Secure Messaging platform, allowing users to view and interact with Jira tickets seamlessly. To get started with the Jira integration, invite the Jira bot to the required room. The bot should then automatically accept the invite and join the room. Once the bot is in the room, configure it to follow a specific Jira project using the following command:

!jira follow <project name>

The bot allows you to follow multiple projects in the same room. You can list all the projects that are currently being followed using the following command:

!jira list

To unfollow a project, use the following command:

!jira unfollow <project name>

To unfollow all projects and disable new notifications, use the following command:

!jira unfollow all

Jira Ticket Notifications

Once configured to follow a project, the bot will automatically check for updates and post notifications to the room for the following events:

• New Jira issue created
• New comment on a Jira issue
• Jira issue description updated

Comments Sync

By default, comments are synced both ways. This means if you get a new Jira ticket update in your Secure Messaging room, you can reply in a thread to that message, and your comment will sync to Jira as well.

Jira Ticket Finder

When a user writes a message containing a Jira issue key in the chat, the bot will attempt to find and post that ticket to the same room. If it cannot find the issue or doesn't have access, it will remain silent. The same ticket can only be pulled once per 60 seconds to prevent spam.

Per Room Configuration

The bot has various settings specific to the room it's running in. These settings control the bot behavior, such as fine-tuning notifications or enabling and disabling features. To view the default settings, use the following command:

!jira config list

For more information about the bot's functionality and features, check the bot help menu:

!jira help

Jenkins Integration

The Jenkins integration provides an easy way to get notifications for build events. Once the bot is set up by a system administrator to integrate to a Jenkins instance, invite the bot user to the required room and list all available pipelines:

!jenkins list-available

This command will list all available pipelines that can be followed. To follow a pipeline, use the following command:

!jenkins follow <pipeline name>

The bot allows you to follow multiple pipelines in the same room. You can list all the pipelines that are currently being followed using the following command:

!jenkins list

To unfollow a pipeline, use the following command:

!jenkins unfollow <pipeline name>

After following a pipeline, the bot will automatically track it and post notifications to the room when a build has finished. The status message will contain the following information:

• Build event information

• Commit messages and hashes

• Artifacts and their download links

Gitlab Integration

The Gitlab integration allows you to set up the bot to follow a specific Gitlab project for notifications. These notifications may include push events, merge requests, new issues, build events, etc. These events can be configured and fine-tuned in the Gitlab integration settings. The bot can also follow multiple Gitlab projects from different instances simultaneously.

To get started, invite the bot to the desired room and configure a Webhook for the bot to listen to and for Gitlab to send notifications to:

!gitlab webhook add

The bot will send a private message containing the following details:

• Webhook type
• API key
• Webhook endpoint
• Room ID where the webhook has been set up

Then, head to Gitlab -> Project -> Settings -> Integrations -> And fill the following information: URL -> Webhook endpoint Secret Token -> Webhook API key

Then choose which events this webhook should trigger on and click add webhook.

Note: The behavior of the Gitlab test event button may not work correctly; therefore, not all notifications will be reported when you click the test button. However, all real events should be supported.

Note: Once a webhook is set up, the API key is only sent once. This is because the bot itself is not aware of the API key after it is sent; only a hashed version of the key is kept to verify the key's validity. This means that the key is only known to the person who set up the integration.

To remove the webhook from the room, use the following command:

!gitlab webhook remove

Github Integration

The Github integration allows you to set up the bot to follow a specific Github project for notifications. These notifications may include push events, merge requests, new issues, build events, etc. These events can be configured and fine-tuned in the Github integration settings. The bot can also follow multiple Github projects from different instances simultaneously.

To get started, invite the bot to the desired room and configure a webhook for the bot to listen to and for Github to send notifications to:

!github webhook add

The bot will send a private message containing the following details:

• Webhook type
• API key
• Webhook endpoint
• Room ID where the webhook has been set up

Then, head to Github -> Project -> Settings -> Webhooks -> Add webhook -> Fill in the following settings:

• Payload URL -> Webhook endpoint
• Content Type -> application/json
• Secret -> Webhook API key Then select which events you want this Webhook to trigger and click on add webhook. Once added, the bot should send a message to the room confirming that it has been added successfully.

To remove the webhook from the room, use the following command:

!github webhook remove

Webhooks Bot

The Webhooks bot allows any third-party service to send Webhook events to SSH Secure Messaging via a simple REST API. To configure the bot, invite the bot to the desired room and configure a webhook:

!webhook add

The bot will send a private message containing the following details:

• Webhook type
• API key
• Webhook endpoint
• Room ID where the webhook has been set up

Note: Once a Webhook is set up, the API key is only sent once. This is because the bot itself is not aware of the API key after it is sent; only a hashed version of the key is kept to verify the key's validity. This means that the key is only known to the person who set up the integration.

You can then test the Webhook by making a simple POST request to that endpoint:

curl -X POST <webhook endpoint> -H "Content-Type: application/json" -H "Authorization: Bearer <API key>" -d 'Hello World'

Furthermore, this bot supports HTML formatted messages by using the URL parameter html=true in the webhook endpoint. Example:

curl -X POST http://bot-url/webhook/room_id/generic?html=true -H "Content-Type: application/json" -H "Authorization: Bearer <API key>" -d 'Hello World'

If you need to retrieve the Webhook information again, use the following command:

!webhook get

However, note that you won't be able to retrieve the API key. If you lose the API key, there is no way to recover it. The only solution is to regenerate it by removing and re-adding the webhook. The webhook can be removed with the following command:

!webhook remove