Skip to main content

Bots and Integrations

SalaX 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 Salax 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 SalaX 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 SalaX 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

Tetra integration​

SalaX Secure Messaging can be integrated with Tetra systems to enable sending and receiving messages between Tetra devices and SalaX users. The Tetra integration is available as an additional module.
For more information contact your SalaX Secure Messaging representative.

Verkkokauppa.com integration​

SalaX Secure Messaging can be integrated with Verkkokauppa.com and your organization’s HR systems to enable secure messaging for procurement processes. The integrations are available as additional modules. Verkkokauppa.com integration is valid for Finland only.
For more information, contact your SalaX Secure Messaging representative.

Last updated on