Slack

Description

ezvpn-mqtt-slack listens on an MQTT broker and sends messages to a specific Slack channel ID.

In IOhubTM architecture, ezvpn-mqtt-slack subscribes to an MQTT topic (slack/# by default) on the internal MQTT broker and sends messages to Slack.

Slack schema

How to use it

ezvpn-mqtt-slack is a Docker container image pre-configured for communication with ezvpn-mqtt and Slack. To use it, you first need a Slack account with a Workspace and a channel where to receive notifications from IOhub. When used in combination with ezvpn-fld-exchanger you have a flexible system that sends messages based on specific conditions triggered by events.

Slack configuration

Create App
  • Give your new app a name, select your Slack Workspace, click "Create App":
App Name
  • At the bottom of the "Basic Information" section, you can add a name and a logo that your Slack Bot will use in your Workspace:
App Info
  • Go to "OAuth & Permissions" in the left menu, navigate to "Scopes > Bot Token Scopes" and click "Add an OAuth Scope":
App Scope
  • Add the "chat:write" and "files:write" scopes to the "Bot Token Scopes":
App Scope
  • After scopes are added, click "Install to Workspace" at the top of the page:
App Install
  • You will get a "Bot User OAuth Access Token"; copy the token and use it as the value of the SLACK_TOKEN environment variable:
App Token
  • In your Slack Workspace, invite the IOhub Bot to the channel it will post to using /invite @<bot_name>:
App Channel
  • If you need to get the channel ID, follow this procedure:
    • right-click on the slack channel (or direct message) in the desktop App and select the 'Copy Link' option.
    • This will give you a URL of the form: https://org.slack.com/messages/[channel-ID] or https://<your workspace>.slack.com/archives/[channel-ID]

The files:write scope is, at the moment of writing, not needed. We suggest that you add it to be ready for future extensions sending images and other documents.

Environment variables

When you start the Slack container, you can adjust the instance's configuration by passing one or more environment variables to the docker run command.

MQTT Connection

  • MQTT_HOST: MQTT host. Defaults to 127.0.0.1

  • MQTT_PORT: MQTT port. Defaults to 1883

  • MQTT_SUBSCRIBE_TOPIC: IOhubTM MQTT topic to subscribe. Defaults to slack/#. Subscribe to multiple topics can be obtained defining each topic on a separated line.

  • MQTT_WANT_QOS2: ask MQTT to upgrade each incoming message on MQTT_IN_TOPIC to QoS 2 (delivery guaranteed). MQTT will honor the request only if persistence is enabled.

  • SKIP_RETAIN: if true, discard all MQTT messages with retain flag set to true. Defaults to false.

With SKIP_RETAIN set to false, each client that subscribes to a topic pattern receives the retained message immediately after they subscribe.

The broker stores only one retained message per topic.

Slack Connection

  • SLACK_TOKEN: App token. Must be provided.

  • SLACK_CHANNEL_ID: channel id where messages are posted. Must be provided if SLACK_USE_TOPIC_AS_CHANNEL_ID is false.

  • SLACK_USE_TOPIC_AS_CHANNEL_ID: if true, the slack channel id is extracted from the incoming topic; the last portion of the topic after the last / is be used as channel id; SLACK_CHANNEL_ID is not be used. Defaults to false.

  • SLACK_TEMPLATE: used as a message template. ## DATA ## can be used as a placeholder for the value read from mqtt. ## TOPIC ## can be used as a placeholder for the incoming topic from MQTT. If empty, the raw incoming data is sent.

  • SLACK_SEND_AS_QUOTE: if true, post to Slack the incoming data as quoted text. Defaults to false.

Docker container details

Image: us-central1-docker.pkg.dev/ez-shared/iohub/iohub-mqtt-slack

Supported architecture: amd64

Changelog

v1.0.1
  • Smaller image
v1.0.0
  • First Release