Skip to content

Slack Connector

Introduction

Slack is a cloud-based team communtication platform, primarily offered as a business-to-business service, with its userbase being predominantly team-based businesses.

SlackMQTT allows reciprocal communication, displaying and sending MQTT messages through Slack channels. This connector allows an easy integration between the Broker and the Slack Workspace, offering useful functionalities to manage your data directly from slack. Its versatility allows this connector to be highly personalized, designed to match your business requirements and needs, all from a familiar interface.

Features and Benefits

  • Seamless Communication: Enables seamless integration between Slack workspaces and MQTT clients, streamlining the exchange of data across platforms;
  • Real-Time Monitoring: Facilitates real-time data exchange between Slack and the broker, through Slack messages;
  • Easy Integration: Simplifies the integration of Slack with your IoT projects, making it possible to receive data from various IoT devices;
  • Reciprocal Communication: Also allows users to send messages to the broker directly through Slack workspaces.

Prerequisites

Before you install and configure the connector, make sure you have the following prerequisites:

  • Basic understanding of the MQTT Protocol;
  • Basic understanding of SlackApi App management;
  • Access to an MQTT broker compatible with your setup;
  • MQTT Client software (such as MQTT Explorer or similar);
  • Access to a Slack Workplace.

SlackApi App

To be able to use this connector, you need to have a SlackApi App in your slack workplace. Follow these steps to get your Slack App ready for this connector:

  1. Go to Slack Api and navigate to Your Apps; alt text

  2. Create a new app from manifest, assigning the desired workplace and using the following manifest:

{
    "display_information": {
        "name": "your-app-name"
    },
    "features": {
        "bot_user": {
            "display_name": "your-app-name",
            "always_online": false
        }
    },
    "oauth_config": {
        "scopes": {
            "bot": [
                "channels:history",
                "channels:read",
                "chat:write",
                "chat:write.public",
                "commands",
                "groups:history",
                "im:history",
                "im:write",
                "mpim:history"
            ]
        }
    },
    "settings": {
        "event_subscriptions": {
            "bot_events": [
                "message.channels",
                "message.groups",
                "message.im",
                "message.mpim"
            ]
        },
        "interactivity": {
            "is_enabled": true
        },
        "org_deploy_enabled": false,
        "socket_mode_enabled": true,
        "token_rotation_enabled": false
    }
}

Change "your-app-name" to the desired name.

  1. Go to Socket Mode and enable it, saving the app-level token as the AppLevelToken for the connector configuration;

alt text

alt text

alt text

alt text

  1. Install the app in your workplace;

alt text

alt text

  1. Save the Bot User OAuth Token as the ApiKey for the connector configuration;

alt text

alt text

  1. Add the application to the desired channels inside the workplace, in slack:

alt text

alt text

alt text

  1. The SlackApp is now ready to integrate with the connector!

Connector Instalation

Using Coreflux HUB

Please refer to the general docs for connector installation through the Coreflux HUB.

Using Coreflux HUBLESS

Connector management and control are conducted using the MQTT protocol. Commands (payload) are sent to the $/Coreflux/Command topic. The results of these commands are published to $/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

  1. Connect to the Coreflux MQTT Broker using your preferred client;

  2. Login using your Coreflux Account: 

    -L myname@mydomain.com password

  3. Check for available connector: 

    -l

  4. Install the connector: 

    -I coreflux_slackmqtt

  5. If there were no issues during the installation, you should receive a message on the $/Coreflux/Command/Output:
Your coreflux_slackmqtt was installed with the version <version> with the <asset_guid>. Let the magic begin!

Connector Configuration

Before using the connector, it must be properly configured.
This configuration process entails adjusting various parameters that affect its functionality, the setup of the device, and how they interact with each other.
This involves specifying the device's IP address, selecting which symbols to read from the device, among other settings.

The configuration is detailed in a JSON file, divided into three main sections: MQTT Parameters, Slack Parameters and Tags.
The instructions bellow serve as a configuration guide, for each section. By the end, you should have a comprehensive example configuration that can be tailored to your specific needs.

⚠ : If a parameter is not included in the connector's configuration and it is not required, a default value will be applied. Incorrect configuration may cause the connector to not work as intended.

ℹ : This configuration is presented using a hubless setup as an example. The key takeaway is the understanding of the parameters and their significance. If you are configuring the connector via Coreflux Hub, the same parameters and configurations apply.

MQTT Parameters

The MQTTParameters in the JSON configuration define how to connect to a MQTT Broker, specifying the communications details.

The Address and Port indicate the broker's network location (in this case, 127.0.0.1 on port 1883), which is where the data will be sent to or received from.
The parameters also detail authentication methods and use of TLS for secure communication.

This setup determines the pathway for the data exchange between the device and the MQTT broker, facilitating the monitoring or control of device operations.

Parameter Description Required Example Default Value
Port Port number on which the MQTT broker is running. Yes 1883 1883
Address IP address or hostname of the MQTT broker. Yes "iot.coreflux.cloud" "127.0.0.1"
IsAnonymous Indicates if the connection is anonymous (no username/password required). No true true
Username Username for authentication, if not anonymous. No "" (empty string) "" (empty string)
Password Password for authentication, if not anonymous. No "" (empty string) "" (empty string)
WithTLS Specifies whether TLS encryption is enabled for secure communication. No true false
ClientId Used to uniquely to identify the client to the MQTT broker. Yes Client1 Random.Name.Generator

Example: 

{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    }
}

Slack Parameters

Slack in the JSON configuration outlines the setup for the connection between the connector and the SlackApi. This parameter requires the API key, the Bot User OAuth Token, and the App Level Token available in your app, on the Slack API website, after login.

Parameter Description Required Example Default Value
ApiKey Bot User OAuth Token Yes "xoxb-123456789012-1234567890123-ABCDEFGHIJKLmnoPQRstUVWXyZ" ""
AppLevelToken App Level Token Yes "xapp-1-A1111B22CC33D44E5555F6666A7777B8C9999DDDDDDDDDD" ""

Example: 

{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    },
    "Slack":{
        "ApiKey" : "xoxb-123456789012-1234567890123-ABCDEFGHIJKLmnoPQRstUVWXyZ",
        "AppLevelToken" : "xapp-1-A1111B22CC33D44E5555F6666A7777B8C9999DDDDDDDDDD"
    }
}

⚠ : It is recommended to keep these tokens hidden.

Tags

Tags are crucial components that simplify the set of actions the asset will perform in the workspace. Each Tag establishes a direct link to the topics and the channels/messages in the slack workspace to which you want the payload to go, as well as actions for said messages.
These tags configure the specifics of the slack messages and the MQTT communication, including the Action Type, to post, delete or update messages, the ChannelId of the slack workspace channel and the MessageURL of a targeted message for update actions, for example.

Parameter Description Required Example Default Value
Name Unique Tag Identifier Yes RoomTemperature TagName
Route Specifies the direction of data flow within the system.
Acceptable values are: 'ToSubscribers' (0), 'ToOther' (1).		 Yes 0 1
Publish Choose how data is sent.
Acceptable values are: 'Update' (0), 'Cyclic' (1), 'Once' (2)		 Yes 0 2
PublishCycle Specifies the interval for publishing messages when 'publish' is set to 'Cyclic'.
Must be a value between 1 and 86,400 seconds (24 hours).		 No 500 1
MqttTopic Unique Topic connecting with the specified Register Yes "room/temp" "mqtt/topic"
MqttRetain Defines if the message should be retained.
Options are: true or false.		 Yes true false
QualityOfService Defines the level of delivery assurance for MQTT messages.
The options are: AtMostOnce (0), AtLeastOnce(1), ExactlyOnce(1).		 Yes 2 2
ActionType Sets the action option for the tag.
Options are: 'PostMessage' (0), 'DeleteMessage (1)', 'UpdateMessage (2)'.		 Yes 2 ``
ChannelId Defines the channel where the payload will be sent to and/or message events will be registered No C01234567AB ""
MessageURL URL of the message to manipulate No https://slack.com/archives/C01234567AB/p1617891234567800 ""
DataType Type of data for slack to receive.
Options are: 'RawValue (0)', 'JsonParameter (1)', 'CustomMessage (2)'.		 No 1 0
JsonParameter Selected parameter to send to slack from the MQTT json payload. No value ""
CustomMessage A custom message to be sent to slack when a new payload is received from the broker No "Error detected at ${Machine}, with description ${Description}" ""

Example: 

{
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    },
    "Slack":{
        "ApiKey" : "xoxb-123456789012-1234567890123-ABCDEFGHIJKLmnoPQRstUVWXyZ",
        "AppLevelToken" : "xapp-1-A1111B22CC33D44E5555F6666A7777B8C9999DDDDDDDDDD"
    },
    "Tags":[
        {
            "Name" : "FromMqttToSlack",
            "Route" : 1,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "ActionType" : 0,    
            "ChannelId" : "C01234567AB",       
            "DataType" : 0         
        },
        {
            "Name" : "FromSlackToMqtt",
            "Route" : 0,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "ActionType" : 1,
            "MessageURL" : "https://slack.com/archives/C01234567AB/p1617891234567800",        
        },
        {
            "Name" : "FromMqttToSlackCustom",
            "Route" : 0,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/temp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "ActionType" : 0,
            "ChannelId" : "C01234567AB",
            "DataType" :   2,
            "CustomMessage" : "Error detected at ${Machine}, with description ${Description}"      
        }
    ]
}

⚠ : Tags for payloads from MQTT to Slack should use Route: ToOthers. From Slack to MQTT, use Route: ToSubscribers

⚠ : Don't fill both Channel Id and Message URL. Use Channel Id when posting messages. Use Message URL for the message updates.

Using Custom message

To be able to use the custom message as intended, there's a few considerations to make:
- Target parameters only work with Json payloads; - The targeted parameter must be written between the key ${}, for example ${targetedParameter}, to be recognised by the connector; - If the payload is not a json, you can still choose where it goes in your custom message, using the key ${RawData} where you want the payload to be shown; - If no ${targetedParameter} is present, the connector adds a new line with the raw payload at the end of your custom message; - If there is a key ${targetedParameter} but it is not found in the payload, it replaces the key with [unknown] in the custom message and logs which parameter it couldn't find; - Nested objects can be found too, using dots to separate them, for example ${targetParamater.Value}. This also works for JsonParameter.

Saving the Configuration

connector management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : Configuration requires the user to be logged in and have an connector installed. If these requirements are not met, please refer to the installation section.

  1. Save the configuration:
-assetConfigSave <asset_guid> <configuration>`

ℹ : The asset asset_guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Example: 

-assetConfigSave assetName {
    "MqttParameters": {
        "Port" : 1883,
        "Address" : "iot.coreflux.cloud",
        "IsAnonymous" : true,
        "UserName" : "",
        "Password" : "",
        "WithTLS" : false,
        "ClientId" : "ClientId1"
    },
    "Slack":{
        "ApiKey" : "xoxb-123456789012-1234567890123-ABCDEFGHIJKLmnoPQRstUVWXyZ",
        "AppLevelToken" : "xapp-1-A1111B22CC33D44E5555F6666A7777B8C9999DDDDDDDDDD"
    },
    "Tags":[
        {
            "Name" : "FromMqttToSlack",
            "Route" : 1,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/readtemp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "ActionType" : 0,
            "ChannelId" : "C01234567AB",
            "DataType" : 0         
        },
        {
            "Name" : "FromSlackToMqtt",
            "Route" : 0,
            "Publish" : 0,
            "PublishCycle" : 127,
            "MqttTopic" : "room/settemp",
            "MqttRetain" : true,
            "QualityOfService" : 0,
            "ActionType" : 0,
            "MessageURL" : "https://slack.com/archives/C01234567AB/p1617891234567800",
            "DataType" :   1,
            "JsonParameter" : "value"          
        }
    ]
}
2. Check if the configuration was saved (optional):

-assetConfigLoad <asset_guid>

Using the Connector

⚠ : It is important to understand that the flow of data between the broker and the device highly depends on the configuration of both the connector and the device. In case of unexpected results, please verify the configuration and/or check the logs for any possible errors.

With Coreflux HUB

Please refer the to general docs for connector installation through the Coreflux HUB.

With Coreflux HUBLESS

Connector management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $/Coreflux/Command topic. The results of these commands are published to $/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : The asset guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Run Connector

  1. Run connector:
-R <asset_guid>

Stop Connector

  1. Stop connector:
-S <asset_guid>

Logs

Logs are essential to monitor and debug your system. They provide insight into the operation of your connectors and can help identify and resolve issues promptly.

With Coreflux HUB

On Coreflux HUB, the logs are displayed in the "Log" section of the connector configuration.

With MQTT Explorer

To display logs in MQTT Explorer, follow these steps:

  1. Publish the following command to the $/Coreflux/Command topic:

-addTraceLog topic=topic/to/show/log level=Error/Information/Warning messageContains=(assetID)
2. The logs will be shown on the $/Coreflux/Log/Traces/topic/to/show/log topic.

Example1:

To display informational logs, use:

-addTraceLog topic=log/inf level=Information

Note : This will display the Logs "Information" of all the connectors

Example2:

To display error logs, from a specific connector, use:

-addTraceLog topic=log/slack/err level=Error messageContains=assetID

Note : This will display the Logs "Error" of a specific connector

Note: To display all three types of logs (Error, Information, and Warning), you will need to repeat this process three times, one for each log level. three times, one for each log level.