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:

Communication

• Comm ID: select the comm port the device is connected to.

High Availability

• Shutdown when inactive: defaults to true.

Options

ID	Default	Values	Description
pin		<code>	4-digits PIN code of the SIM card (if used)
gui	true	true	enable support for the UI object, UISET actions and USER commands
		false	disable UI support
inboxsize	10	n ≥ 0	the number of incoming messages to display in the UI object
countrycode		<code>	the default country code (e.g. “39”, for Italy) to be used when not otherwise specified. If omitted all provided numbers shall include the country code
srvc		<number>	phone number of the SMS service center (use the international format, e.g. +393492000200). If not specified, the default number saved on the SIM card will be used. If not available, the driver will not be able to send SMS messages
resend	4	n ≥ 0	number of sending attempts on an outgoing SMS in case of error
simphase2	false	true	enable SIM phase 2+ compatibility
		false	default

Datapoints

ID	Value	R/W	Description
connection	online	R	connection established
	offline	R	HSYCO can't connect to the modem
sms.<num>	<text>	R	an SMS message has been received form the number <num>[Note 2] with <text> as body
		W	send an SMS message to the number <num>[Note 1] with <text> as body
call	<num>	R	incoming call from number <num>[Note 2] in progress. An event is generated for each “ring” during the call
		W	start a voice call to number <num>[Note 1]
	end	W	end the ongoing voice call
	unknown	R	incoming call from an unknown number in progress
call.state	start	R	a voice call has been started
	alerting	R	the ongoing voice call is in the alerting state, i.e. the phone on the other end is ringing
	active	R	the ongoing voice call is active, i.e. the call has been answered from the other end
	held	R	the ongoing voice call is being held
	dialing	R	the modem is dialing the number
	waiting	R	the ongoing voice call is waiting
	end	R	the voice call has ended
sms.<num>.sent	<mr>	R	a message has been successfully sent to the number <num> and the message reference number is <mr>
sms.<num>.errors	<val>	R	an error occurred while sending a message to number <num>. The value <val> is an increasing counter of the occurred errors since the I/O Server started
signal	{0 ... 31}	R	the GSM signal level has the reported value (ranging from 0 to 31)
	unknown	R	the GSM signal level is unknown

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.