Telegram

This I/O Server allows you to implement a custom Telegram bot in HSYCO, for sending and receiving messages using the Telegram messaging service.

Communication and Telegram bot setup

The Telegram I/O Server connects to the Telegram service using the Telegram Bot API and requires a fully functional Internet connection.

In order to use this I/O Server you need to create a bot first. Using your Telegram account, send the /newbot command to the Telegram BotFather bot. The BotFather will ask you for a name and username, then generate an authorization token for your new bot.

The name of your bot will be displayed in contact details and elsewhere.

The Username is a short name, to be used in mentions and telegram.me links. Usernames are 5-32 characters long and are case insensitive, but may only include Latin characters, numbers, and underscores. Your bot's username must end in ‘bot’, e.g. ‘tetris_bot’ or ‘TetrisBot’.

The token is a string along the lines of 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw that will be required to authorize the bot, setting the token parameter statically, in the I/O Server configuration, or dynamically, writing the token datapoint.

HSYCO Configuration

Add a Telegram I/O Server in the I/O Servers section of the Settings and set its parameters:

High Availability

• Shutdown when inactive: defaults to true.

Options

ID	Default	Values	Description
token		token string	the bot's token string, generated by the BotFather
password		registration string (spaces are allowed, no length restrictions)	the user registration string (see Users Registration below)

A valid token is required to activate the Telegram I/O server, but you can set it dynamically, writing to the token datapoint. If you configure a Telegram I/O server without the token option, the I/O server will only activate once the token datapoint is set.

Users registration

If you don't set a password, all users will be able to send messages to your Telegram bot, and it will be up to your application logic in HSYCO to filter out unwanted messages.

As in most cases you may need to accept messages only from specific users, the Telegram I/O Server implements a simple user registration procedure.

If you set an arbitrary length phrase (spaces between characters are allowed) in the password configuration parameter or writing to the password datapoint, when a Telegram message is received from a user that exactly matches the registration phrase, that user is added to the registered users list. Note that the match is case-sensitive, and only leading/trailing spaces are ignored.

So, if you set a password, only messages originating from registered users are accepted and forwarded to HSYCO applications via I/O events.

The list of registered users is stored in text files in HSYCO's root directory, named telegram-<I/O Server name>.ini

Datapoints

ID	Value	R/W	Description
connection	online	R	connection established
	offline	R	HSYCO can't connect to the Telegram servers, or the bot token is not valid
bot	<bot name>	R	the name of the bot associated to the token. This datapoint is set only when the connection to the Telegram's servers is established, and the token is valid. You don't need to set the bot name to establish the connection, only the token string is required
password	<registration phrase>	W	see Users registration. Note that writing the password datapoint overrides the password set as configuration parameter
token	<token string>	W	see Communication and Telegram bot setup. Note that writing the token datapoint overrides the token set as configuration parameter
enable	<user id>	W	description
disable	<user id>	W	description
message.<from>	<message text>	R	description
message.json	<JSON string>	R	description
message.<to>	<text>	W	description
message.<to>.<message id>	<text>	W	description
message.all	<text>	W	description
message.html.<to>	<text>	W	description
message.html.<to>.<message id>	<text>	W	description
message.html.all	<text>	W	description

Note 1 

If the option 'countrycode' is used, then the country code will be automatically added to the specified numbers, unless the latter begins with a '+' character. For instance, assuming the option 'countrycode' is set to “39”, the addressee number “3480077000” will be automatically changed to “+393480077000”, while the number “+46765007700” will remain unchanged. If, on the other hand, no default country code has been specified, then the addressee numbers must always be provided prepending the country code.

Note 2 

The numbers are reported as sent from the modem and the format may vary depending on the number itself and the modem settings. If the reported number is an international number, then a '+' will be prepended to it, unless the country code is equal to the value of the 'countrycode' option. In the last case the country code will be omitted. In some cases, the sender number field might also be replaced by an alphanumeric string.

Examples

Sending an SMS

Assuming that we are sending an SMS at 12 o' clock to number 777123456 located in Italy (International prefix code: +39) and the option "countrycode" of the GSM IO server is not specified, this is the corresponding EVENTS programming declaration:

time = 1200 : io gsm.sms.+39777123456 = "I'm sending and sms to the world"

You can send multiple SMSs to different numbers using this syntax:

time = 1200 : io gsm.sms.+39777123456 gsm.sms.+39777654321 = "I'm sending an sms to the world"

Receiving an SMS

Hsyco can receive SMSs through the GSM IO server and perform actions according to the text contained in the SMS.

io gsm.sms.777123456 = "Help" : io gsm.sms.777123456 = "I accept the following commands: Open, Status"
io gsm.sms.777123456 = "Open" : io knx.1/1/2 = 1, wait = 1, io knx.1/1/2 = 0

Release Notes

3.6.0

• initial release

---

The Telegram logo is a registered trademark of Telegram Messenger LLP.