Telegram

Description

ezvpn-mqtt-telegram listens on an MQTT broker and sends messages to a specific Telegram chat.

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

Telegram schema

How to use it

ezvpn-mqtt-telegram is a Docker container image pre-configured for communication with ezvpn-mqtt and Telegram. To use it, you first need a Telegram account with a bot and a chatID to send 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.

Telegram bot configuration

Create a Telegram account if you don't have it.

Register a new Telegram Bot by typing /newbot in the @BotFather bot and proceed following the instructions shown in the screenshot below.

Take note of the token provided by @BotFather. It will be necessary for configuring the TELEGRAM_TOKEN environment variable.

Create Bot

How to send notifications to a user

If you want to receive personal notifications, you need to obtain the user chat ID to send the messages. EZ VPN has developed the Telegram bot @IOIndustryBot to obtain the chat ID easily.

Send /mychatid to @IOIndustryBot in Telegram messenger. Copy the command result (Chat ID number) and use it in the TELEGRAM_CHAT_ID environment variable.

Get chat ID

Send /start to the bot created above. If you skip this step, the Telegram bot won't send messages to the user.

Start

When a message is sent to the environment variable content MQTT_SUBSCRIBE_TOPIC, the telegram container will forward it to your Telegram user.

How to send notifications to a group

If you want to send notifications to a group of users, create a new Telegram group or use an existing one.

Add the bot @your_bot_name_here to your Telegram group so you can receive the notifications from IOhub. You can add the bot just like an user.

Add the bot @IOIndustryBot to your Telegram group and type /mychatid@IOIndustryBot message in the group to obtain the group chat ID.

After you get the chat ID you can remove the bot @IOIndustryBot from the group (optional)

Start

In the group chat, send /start@your_bot_name_here. If you skip this step, the Telegram bot won't send messages to the group.

Start

When a message is sent to the environment variable content MQTT_SUBSCRIBE_TOPIC, the telegram container will forward it to your Telegram group.

Environment variables

When you start the Telegram 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 telegram/#. Subscribe to multiple topics can be obtained by defining each topic on a separate 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.

Telegram Connection

  • TELEGRAM_TOKEN: Bot token. Must be provided.

  • TELEGRAM_CHAT_ID: chat id where messages are posted. Must be provided.

  • TELEGRAM_TEMPLATE: used as body 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. Defaults to ## DATA ##.

Docker container details

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

Supported architecture: amd64

Changelog

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