Difference between revisions of "IFTTT"

From HSYCO
Jump to navigation Jump to search
 
(8 intermediate revisions by the same user not shown)
Line 10: Line 10:
 
In order to setup an IFTTT applet that triggers an event and send data to HSYCO, connect the Webhook service to the "that" side of the applet.
 
In order to setup an IFTTT applet that triggers an event and send data to HSYCO, connect the Webhook service to the "that" side of the applet.
  
−
The URL you specify must have the same server address and port number you use to access the HSYCO Web interface, followed by the /ifttt path and the password defined in the IFTTT I/O Server configuration, for example: https://example.hsyco.net:/ifttt/oieojdjeiw48394ejdejdd. Note that this password must be kept secret and should be long and difficult to guess, as it could otherwise be used to easily feed unauthorised commands to the NLP.
+
The URL you specify must have the same server address and port number you use to access the HSYCO Web interface, followed by the /ifttt path and the password defined in the IFTTT I/O Server configuration, for example: https://example.hsyco.net:/ifttt/oieojdjeiw48394ejdejdd.
 +
 
 +
Note that this password must be kept secret and should be long and difficult to guess, as it could otherwise be used to easily trigger events in HSYCO.
  
 
The "Method" field should be set to POST, the "Content Type" field is not required, and add a static or dynamic text, for example the "TextField" ingredient of a trigger, to the "Body" field.
 
The "Method" field should be set to POST, the "Content Type" field is not required, and add a static or dynamic text, for example the "TextField" ingredient of a trigger, to the "Body" field.
Line 28: Line 30:
 
=== High Availability ===
 
=== High Availability ===
 
*'''Shutdown when inactive''': defaults to false.
 
*'''Shutdown when inactive''': defaults to false.
−
 
  
 
=== Options ===
 
=== Options ===
Line 37: Line 38:
 
!Values
 
!Values
 
!Description
 
!Description
−
|-
 
−
 
−
|token
 
−
|
 
−
|token string
 
−
|the bot's token string, generated by the BotFather
 
−
 
 
|-
 
|-
  
 
|password
 
|password
 
|
 
|
−
|registration string (spaces are allowed, no length restrictions)
+
|password string (only use upper and lower case A-Z characters or digits, no space or special characters allowed, no length restrictions)
−
|the user registration string (see Users Registration below)
+
|used to accept web requests from the Webhooks service
  
 
|}
 
|}
  
−
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.
+
{{note|Note that the password must be kept secret and should be long and difficult to guess, as it could otherwise be used to easily trigger events in HSYCO.}}
−
 
 
−
=== 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 77: Line 59:
 
|-
 
|-
  
−
|rowspan="2" |connection
+
|request
−
|online
+
|<body&nbsp;text>
−
|R
 
−
|connection established
 
−
|-
 
−
|offline
 
−
|R
 
−
|HSYCO can't connect to the Telegram servers, or the bot token is not valid
 
−
 
 
−
|-
 
−
 
 
−
|bot
 
−
|<bot&nbsp;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&nbsp;phrase>
 
−
|W
 
−
|see [[Telegram#Users_registration|Users registration]]. Note that writing the password datapoint overrides the password set as configuration parameter
 
−
 
 
−
|-
 
−
 
 
−
|token
 
−
|<token&nbsp;string>
 
−
|W
 
−
|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
 
−
|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&nbsp;id>
 
−
|<message&nbsp;text>
 
 
|R
 
|R
−
|the message text received from a user with id <user&nbsp;id>. This is a forced event, triggered on every message
+
|the text sent by the IFTTT Webhooks service web request. This is a forced event, triggered on every request
  
 
|-
 
|-
  
−
|message.json
+
|request.<query>
−
|<JSON&nbsp;string>
+
|<body&nbsp;text>
 
|R
 
|R
−
|received message, with all attributes, in JSON format. This is a forced event, triggered on every message
+
|the text sent by the IFTTT Webhooks service web request. Query is the optional query string in the URL as set in the Webhooks service. This is a forced event, triggered on every request
−
 
 
−
|-
 
−
 
 
−
|message.<user&nbsp;id>
 
−
|<text>
 
−
|W
 
−
|send a text message to user <user&nbsp;id>
 
−
 
 
−
|-
 
−
 
 
−
|message.<user&nbsp;id>.<message&nbsp;id>
 
−
|<text>
 
−
|W
 
−
|send a text message to user <user&nbsp;id>, as a reply to message <message&nbsp;id>
 
  
 
|-
 
|-
  
−
|message.all
+
|event
−
|<text>
+
|<value1>
 
|W
 
|W
−
|when users registration is active, send a text message to all registered users that are currently enabled
+
|trigger an IFTTT Webhooks event with event name "hsyco", passing the value as value1
  
 
|-
 
|-
  
−
|message.html.<user&nbsp;id>
+
|event.<name>
−
|<text>
+
|<value1>
 
|W
 
|W
−
|send an [http://core.telegram.org/bots/api#html-style HTML] message to user <user&nbsp;id>
+
|trigger an IFTTT Webhooks event with the specified event name "hsyco", passing the value as value1
−
 
 
−
|-
 
−
 
 
−
|message.html.<user&nbsp;id>.<message&nbsp;id>
 
−
|<text>
 
−
|W
 
−
|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>
 
−
 
 
−
|-
 
−
 
 
−
|message.html.all
 
−
|<text>
 
−
|W
 
−
|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
 
  
 
|}
 
|}
−
 
−
=== 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 withan 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.
 
  
 
== Examples ==
 
== Examples ==
−
=== Sending messages ===
+
=== Receiving a web request from IFTTT ===
−
Assuming that we are sending an SMS at 12 o' clock  to user id 777123456, this is the EVENTS programming declaration:
+
Assuming that the IFTTT's I/O Server id is "ifttt", these events will write the incoming request to the log file:
−
 
 
−
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 telegram.message.777123456 = "Do you like my message? <nowiki>[[Yes,No]]</nowiki>"
+
  io ifttt.request : log = io ifttt.request
 +
io ifttt.request.myquery : log = io ifttt.request
  
−
=== Receiving messages ===
+
=== Generating a trigger event in IFTTT ===
−
Hsyco can receive Telegram messages and perform actions according to the text contained in the message.
+
This EVENTS line will trigger a Webhooks event named "hsyco" every minute, passing the time as the value1 field of the Webhooks trigger:
  
−
  io telegram.message.777123456 = "Yes" : io telegram.message.777123456 = "Thank you!"
+
  time : io ifttt.event = $time$
−
io telegram.message.777123456 = "No" : io telegram.message.777123456 = "Why not? You are so mean!"
 
  
 
== Release Notes ==
 
== Release Notes ==

Latest revision as of 17:28, 3 July 2018

This I/O Server implements two-way communication with the Webhooks service of IFTTT, allowing HSYCO to trigger applets in IFTTT and, the other way around, to receive notifications and data from applets.


IFTTT setup

The IFTTT I/O Server connects to IFTTT via its Webhooks service. It requires a fully functional Internet connection.

In order to setup an IFTTT applet that triggers an event and send data to HSYCO, connect the Webhook service to the "that" side of the applet.

The URL you specify must have the same server address and port number you use to access the HSYCO Web interface, followed by the /ifttt path and the password defined in the IFTTT I/O Server configuration, for example: https://example.hsyco.net:/ifttt/oieojdjeiw48394ejdejdd.

Note that this password must be kept secret and should be long and difficult to guess, as it could otherwise be used to easily trigger events in HSYCO.

The "Method" field should be set to POST, the "Content Type" field is not required, and add a static or dynamic text, for example the "TextField" ingredient of a trigger, to the "Body" field.

The IFTTT I/O Server can also be used to send trigger events to IFTTT's applets. The I/O Server will send a web request that will be received by a Webhook trigger. This request contains a text value and can optionally have an event name. If the event name is not set using the appropriate IO command's syntax, the event name passed to Webhooks is "hsyco".

On the IFTTT Webhooks page, click "Documentation" to retrieve the key and set the eventkey option of the I/O Server.

Define a new applet using the Webhook as the "this" trigger, enter the event name you want to use to identify this specific trigger, then add the "that" side of the trigger using the applet you need to trigger from HSYCO.

HSYCO Configuration

Add a IFTTT I/O Server in the I/O Servers section of the Settings and set the password.

Note that the IFTTT 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 IFTTT with HSYCO.


High Availability

  • Shutdown when inactive: defaults to false.

Options

ID Default Values Description
password password string (only use upper and lower case A-Z characters or digits, no space or special characters allowed, no length restrictions) used to accept web requests from the Webhooks service
Note that the password must be kept secret and should be long and difficult to guess, as it could otherwise be used to easily trigger events in HSYCO.


Datapoints

ID Value R/W Description
request <body text> R the text sent by the IFTTT Webhooks service web request. This is a forced event, triggered on every request
request.<query> <body text> R the text sent by the IFTTT Webhooks service web request. Query is the optional query string in the URL as set in the Webhooks service. This is a forced event, triggered on every request
event <value1> W trigger an IFTTT Webhooks event with event name "hsyco", passing the value as value1
event.<name> <value1> W trigger an IFTTT Webhooks event with the specified event name "hsyco", passing the value as value1

Examples

Receiving a web request from IFTTT

Assuming that the IFTTT's I/O Server id is "ifttt", these events will write the incoming request to the log file: 

io ifttt.request : log = io ifttt.request
io ifttt.request.myquery : log = io ifttt.request

Generating a trigger event in IFTTT

This EVENTS line will trigger a Webhooks event named "hsyco" every minute, passing the time as the value1 field of the Webhooks trigger: 

time : io ifttt.event = $time$

Release Notes

3.7.0

  • initial release


IFTTT is a registered trademark of IFTTT Inc.

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