Difference between revisions of "Telegram"

From HSYCO
Jump to navigation Jump to search
 
(60 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
This I/O Server allows you to implement a custom Telegram bot in HSYCO, for sending and receiving messages using the Telegram messaging service.
+
This I/O Server allows you to implement a custom Telegram bot in HSYCO, for sending and receiving messages using the [http://telegram.org Telegram messaging service].
  
 
[[Category:I/O Server]]
 
[[Category:I/O Server]]
Line 14: Line 14:
 
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 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.
+
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 ==
 
== HSYCO Configuration ==
−
Add a Telegram I/O Server in the [[Settings#I/O Servers|I/O Servers section of the Settings]] and set its parameters:
+
Add a Telegram I/O Server in the [[Settings#I/O Servers|I/O Servers section of the Settings]] and set its parameters.
 +
 
 +
{{note|Note that the Telegram I/O Server doesn't count in the I/O servers license total, so you don't need an extra I/O Server license to use Telegram with HSYCO.}}
 +
 
  
 
=== High Availability ===
 
=== High Availability ===
 
*'''Shutdown when inactive''': defaults to true.
 
*'''Shutdown when inactive''': defaults to true.
 +
 +
Note that Telegram does not allow multiple connections to the same bot, so setting this option to false, thus leaving the Telegram I/O Server active on the slave server will generate connection errors on both the master and the slave servers. You may keep the slave Telegram I/O Server active using a different, dedicated bot, for it.
  
 
=== Options ===
 
=== Options ===
Line 40: Line 45:
 
|password
 
|password
 
|
 
|
−
|authentication string
+
|registration string (spaces are allowed, no length restrictions)
−
|the user authentication string (see Users Registration below)
+
|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.
+
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 <nowiki>telegram-<I/O Server name>.ini</nowiki>
  
 
== Datapoints ==
 
== Datapoints ==
Line 64: Line 81:
 
|offline
 
|offline
 
|R
 
|R
−
|HSYCO can't connect to the modem
+
|HSYCO can't connect to the Telegram servers, or the bot token is not valid
  
 
|-
 
|-
  
−
|rowspan="2"|sms.<num>
+
|bot
−
|rowspan="2"|<text>
+
|<bot&nbsp;name>
 
|R
 
|R
−
|an SMS message has been received form the number <num><sup>[[#note2|[Note 2]]]</sup> with <text> as body
+
|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&nbsp;phrase>
 
|W
 
|W
−
|send an SMS message to the number <num><sup>[[#note1|[Note 1]]]</sup> with <text> as body
+
|see [[Telegram#Users_registration|Users registration]]. Note that writing the password datapoint overrides the password set as configuration parameter
  
 
|-
 
|-
  
−
|rowspan="4"|call
+
|token
−
|rowspan="2"|<num>
+
|<token&nbsp;string>
−
|R
+
|W
−
|incoming call from number <num><sup>[[#note2|[Note 2]]]</sup> in progress. An event is generated for each “ring” during the call
+
|see [[Telegram#Communication_and_Telegram_bot_setup|Communication and Telegram bot setup]]. Note that writing the token datapoint overrides the token set as configuration parameter
 +
 
 
|-
 
|-
 +
 +
|enable
 +
|<user id>
 
|W
 
|W
−
|start a voice call to number <num><sup>[[#note2|[Note 1]]]</sup>
+
|when users registration is active, you can re-enable a user that was previously disabled
 +
 
 
|-
 
|-
−
|end
+
 
 +
|disable
 +
|<user id>
 
|W
 
|W
−
|end the ongoing voice call
+
|when users registration is active, you can disable a registered user, so that messages originating from that user will be ignored
 +
 
 
|-
 
|-
−
|unknown
+
 
 +
|message.<user&nbsp;id>
 +
|<message&nbsp;text>
 
|R
 
|R
−
|incoming call from an unknown number in progress
+
|the message text received from a user with id <user&nbsp;id>. This is a forced event, triggered on every message
  
 
|-
 
|-
  
−
|rowspan="7"|call.state
+
|message.json
−
|start
+
|<JSON&nbsp;string>
 
|R
 
|R
−
|a voice call has been started
+
|received message, with all attributes, in JSON format. This is a forced event, triggered on every message
 +
 
 
|-
 
|-
−
|alerting
+
 
−
|R
+
|message.<user&nbsp;id>
−
|the ongoing voice call is in the alerting state, i.e. the phone on the other end is ringing
+
|<text>
 +
|W
 +
|send a text message to user <user&nbsp;id>
 +
 
 
|-
 
|-
−
|active
+
 
−
|R
+
|message.<user&nbsp;id>.<message&nbsp;id>
−
|the ongoing voice call is active, i.e. the call has been answered from the other end
+
|<text>
 +
|W
 +
|send a text message to user <user&nbsp;id>, as a reply to message <message&nbsp;id>
 +
 
 
|-
 
|-
−
|held
+
 
−
|R
+
|message.all
−
|the ongoing voice call is being held
+
|<text>
 +
|W
 +
|when users registration is active, send a text message to all registered users that are currently enabled
 +
 
 
|-
 
|-
−
|dialing
+
 
−
|R
+
|message.html.<user&nbsp;id>
−
|the modem is dialing the number
+
|<text>
 +
|W
 +
|send an [http://core.telegram.org/bots/api#html-style HTML] message to user <user&nbsp;id>
 +
 
 
|-
 
|-
−
|waiting
+
 
−
|R
+
|message.html.<user&nbsp;id>.<message&nbsp;id>
−
|the ongoing voice call is waiting
+
|<text>
−
|-
+
|W
−
|end
+
|send an [http://core.telegram.org/bots/api#html-style HTML] message to user <user&nbsp;id>, as a reply to message <message&nbsp;id>
−
|R
 
−
|the voice call has ended
 
  
 
|-
 
|-
  
−
|style="white-space:nowrap" |sms.<num>.sent
+
|message.html.all
−
|<mr>
+
|<text>
−
|R
+
|W
−
|a message has been successfully sent to the number <num> and the message reference number is <mr>
+
|when users registration is active, send an [http://core.telegram.org/bots/api#html-style HTML] message to all registered users that are currently enabled
  
 
|-
 
|-
  
−
|style="white-space:nowrap" | sms.<num>.errors
+
|message.image.<user&nbsp;id>
−
|<val>
+
|<image> <text>
−
|R
+
|W
−
|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
+
|send an image to user <user&nbsp;id>
  
 
|-
 
|-
  
−
|rowspan="2"|signal
+
|message.image.<user&nbsp;id>.<message&nbsp;id>
−
|{0 ... 31}
+
|<image> <text>
−
|R
+
|W
−
|the GSM signal level has the reported value (ranging from 0 to 31)
+
|send an image to user <user&nbsp;id>, as a reply to message <message&nbsp;id>
 +
 
 
|-
 
|-
−
|unknown
 
−
|R
 
−
|the GSM signal level is unknown
 
  
−
|-
+
|message.image.all
 +
|<image> <text>
 +
|W
 +
|when users registration is active, send an image to all registered users that are currently enabled
  
 
|}
 
|}
  
−
<span id="note1">
+
=== Keyboards ===
−
;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.
+
 
−
</span>
+
You can send messages with a custom keyboard with predefined reply options. Simply use the following format at the end of the message:
 +
[[r1c1,r1c2...],[r2c1,r2c2...]...]
 +
r1c1 is the text label of the first button of the first row, r1c2 is the second button of the first row, r2c1 is the first button of the second row, etc. You can create keyboards with an arbitrary number of rows and columns, as far as the format makes sense for Telegram. This keyboard format is interpreted as a keyboard only if it is at the very end of the message, otherwise it will be sent unmodified in the text.
 +
 
 +
See [https://core.telegram.org/bots#keyboards Keyboards] for additional information.
 +
 
 +
=== Images ===
 +
 
 +
To send an image from a camera, write a string having this format to the "message.image" data points: "cam:cameraname[:seconds_back[:frames_back]]".
 +
 
 +
For example, "cam:door" sends a live frame from the camera called "door"; "cam:door:0" sends the last recorded frame; "cam:door:2" sends a frame that was recorded two seconds before the last recorded frame and "cam:door:2:5" sends a frame that is 5 frames earlier than the one recorded two seconds before the last recording.
 +
 
 +
To send other generic image files, use the following format: "file:<file name>". The file path is relative to the HSYCO root directory.
 +
 
 +
Any additional text, after one or more space characters, is interpreted as the caption text for the image to be sent.
 +
 
 +
Custom keyboards are also supported, like in ordinary text or HTML messages.
  
−
<span id="note2">
+
The video feed must be active, if HSYCO is not recording from the camera, add MotionBuffer=1 to the camera attributes.
−
;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.
 
−
</span>
 
  
 
== Examples ==
 
== Examples ==
−
=== Sending an SMS ===
+
=== Sending messages ===
−
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:
+
Assuming that we are sending an SMS at 12 o' clock  to user id 777123456, this is the EVENTS programming declaration:
 +
 
 +
time = 1200 : io telegram.message.777123456 = "I'm sending this message to you, my dear"
 +
 
 +
When users registration is active, you can send a message to all registered users that are currently enabled, also using a few HTML tags (as supported by the Telegram Bot API):
 +
 
 +
time = 1200 : io telegram.message.html.all  = "I'm sending this message to you, <nowiki><b>my dear</b></nowiki>"
 +
 
 +
Send a message with a custom keyboard:
  
−
  time = 1200 : io gsm.sms.+39777123456 = "I'm sending and sms to the world"
+
  time = 1200 : io telegram.message.777123456 = "Do you like my message? <nowiki>[[Yes,No]]</nowiki>"
  
−
You can send multiple SMSs to different numbers using this syntax:
+
Send a live frame from a camera with caption and a custom keyboard:
  
−
  time = 1200 : io gsm.sms.+39777123456 gsm.sms.+39777654321 = "I'm sending an sms to the world"
+
  time = 1200 : io telegram.message.777123456 = "cam:front Live view from the front camera. Open the door? <nowiki>[[Yes,No]]</nowiki>"
  
−
=== Receiving an SMS ===
+
=== Receiving messages ===
−
Hsyco can receive SMSs through the GSM IO server and perform actions according to the text contained in the SMS.
+
Hsyco can receive Telegram messages and perform actions according to the text contained in the message.
  
−
  io gsm.sms.777123456 = "Help" : io gsm.sms.777123456 = "I accept the following commands: Open, Status"
+
  io telegram.message.777123456 = "Yes" : io telegram.message.777123456 = "Thank you!"
−
  io gsm.sms.777123456 = "Open" : io knx.1/1/2 = 1, wait = 1, io knx.1/1/2 = 0
+
  io telegram.message.777123456 = "No" : io telegram.message.777123456 = "Why not? You are so mean!"
  
 
== Release Notes ==
 
== Release Notes ==
 +
=== 3.7.0 ===
 +
*camera images and generic image files can now be sent via Telegram messages
 +
*a connection error during the I/O server startup sequence could cause it to wait indefinitely and never re-connect
 +
 
=== 3.6.0 ===
 
=== 3.6.0 ===
 
*initial release
 
*initial release

Latest revision as of 17:51, 1 October 2020

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.

Note that the Telegram I/O Server doesn't count in the I/O servers license total, so you don't need an extra I/O Server license to use Telegram with HSYCO.


High Availability

  • Shutdown when inactive: defaults to true.

Note that Telegram does not allow multiple connections to the same bot, so setting this option to false, thus leaving the Telegram I/O Server active on the slave server will generate connection errors on both the master and the slave servers. You may keep the slave Telegram I/O Server active using a different, dedicated bot, for it.

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 when users registration is active, you can re-enable a user that was previously disabled
disable <user id> W when users registration is active, you can disable a registered user, so that messages originating from that user will be ignored
message.<user id> <message text> R the message text received from a user with id <user id>. This is a forced event, triggered on every message
message.json <JSON string> R received message, with all attributes, in JSON format. This is a forced event, triggered on every message
message.<user id> <text> W send a text message to user <user id>
message.<user id>.<message id> <text> W send a text message to user <user id>, as a reply to message <message id>
message.all <text> W when users registration is active, send a text message to all registered users that are currently enabled
message.html.<user id> <text> W send an HTML message to user <user id>
message.html.<user id>.<message id> <text> W send an HTML message to user <user id>, as a reply to message <message id>
message.html.all <text> W when users registration is active, send an HTML message to all registered users that are currently enabled
message.image.<user id> <image> <text> W send an image to user <user id>
message.image.<user id>.<message id> <image> <text> W send an image to user <user id>, as a reply to message <message id>
message.image.all <image> <text> W when users registration is active, send an image to all registered users that are currently enabled

Keyboards

You can send messages with a custom keyboard with predefined reply options. Simply use the following format at the end of the message: 

[[r1c1,r1c2...],[r2c1,r2c2...]...]

r1c1 is the text label of the first button of the first row, r1c2 is the second button of the first row, r2c1 is the first button of the second row, etc. You can create keyboards with an arbitrary number of rows and columns, as far as the format makes sense for Telegram. This keyboard format is interpreted as a keyboard only if it is at the very end of the message, otherwise it will be sent unmodified in the text.

See Keyboards for additional information.

Images

To send an image from a camera, write a string having this format to the "message.image" data points: "cam:cameraname[:seconds_back[:frames_back]]".

For example, "cam:door" sends a live frame from the camera called "door"; "cam:door:0" sends the last recorded frame; "cam:door:2" sends a frame that was recorded two seconds before the last recorded frame and "cam:door:2:5" sends a frame that is 5 frames earlier than the one recorded two seconds before the last recording.

To send other generic image files, use the following format: "file:<file name>". The file path is relative to the HSYCO root directory.

Any additional text, after one or more space characters, is interpreted as the caption text for the image to be sent.

Custom keyboards are also supported, like in ordinary text or HTML messages.

The video feed must be active, if HSYCO is not recording from the camera, add MotionBuffer=1 to the camera attributes.

Examples

Sending messages

Assuming that we are sending an SMS at 12 o' clock to user id 777123456, this is the EVENTS programming declaration: 

time = 1200 : io telegram.message.777123456 = "I'm sending this message to you, my dear"

When users registration is active, you can send a message to all registered users that are currently enabled, also using a few HTML tags (as supported by the Telegram Bot API): 

time = 1200 : io telegram.message.html.all  = "I'm sending this message to you, <b>my dear</b>"

Send a message with a custom keyboard: 

time = 1200 : io telegram.message.777123456 = "Do you like my message? [[Yes,No]]"

Send a live frame from a camera with caption and a custom keyboard: 

time = 1200 : io telegram.message.777123456 = "cam:front Live view from the front camera. Open the door? [[Yes,No]]"

Receiving messages

Hsyco can receive Telegram messages and perform actions according to the text contained in the message. 

io telegram.message.777123456 = "Yes" : io telegram.message.777123456 = "Thank you!"
io telegram.message.777123456 = "No" : io telegram.message.777123456 = "Why not? You are so mean!"

Release Notes

3.7.0

  • camera images and generic image files can now be sent via Telegram messages
  • a connection error during the I/O server startup sequence could cause it to wait indefinitely and never re-connect

3.6.0

  • initial release


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

Retrieved from "https://wiki.hsyco.com/3.7/index.php?title=Telegram&oldid=9055"