The Adioso Agent will tell you the minimum airline prices between a pair of cities, and within a certain period of time.
The currency is USD. Please make sure that the difference between start_date
and end_date
is less than 150 days. You will need to contact Adioso
for a username
and password
.
The Aftership agent allows you to track your shipment from aftership and emit them into events.
To be able to use the Aftership API, you need to generate an API Key
. You need a paying plan to use their tracking feature.
You can use this agent to retrieve tracking data.
Provide the path
for the API endpoint that you’d like to hit. For example, for all active packages, enter trackings
(see https://www.aftership.com/docs/api/4/trackings), for a specific package, use trackings/SLUG/TRACKING_NUMBER
and replace SLUG
with a courier code and TRACKING_NUMBER
with the tracking number. You can request last checkpoint of a package
by providing last_checkpoint/SLUG/TRACKING_NUMBER
instead.
You can get a list of courier information here https://www.aftership.com/courier
Required Options:
api_key
- YOUR_API_KEY.path request and its full path
The AlgoritmiaAgent runs algorithms from Algorithmia.
You need to register an account before using this Agent.
The created event will have the output from Algorithmia in the result
key.
To merge incoming Events with the result, use merge
for the mode
key.
The Attribute Difference Agent receives events and emits a new event with the difference or change of a specific attribute in comparison to the previous event received.
path
specifies the JSON path of the attribute to be used from the event.
output
specifies the new attribute name that will be created on the original payload
and it will contain the difference or change.
method
specifies if it should be…
percentage_change
eg. Previous value was 160
, new value is 116
. Percentage change is -27.5
decimal_difference
eg. Previous value was 5.5
, new value is 15.2
. Difference is 9.7
integer_difference
eg. Previous value was 50
, new value is 40
. Difference is -10
decimal_precision
defaults to 3
, but you can override this if you want.
expected_update_period_in_days
is used to determine if the Agent is working.
The resulting event will be a copy of the received event with the difference
or change added as an extra attribute. If you use the percentage_change
the
attribute will be formatted as such {{attribute}}_change
, otherwise it will
be {{attribute}}_diff
.
All configuration options will be liquid interpolated based on the incoming event.
The Basecamp Agent checks a Basecamp project for new Events
To be able to use this Agent you need to authenticate with 37signals in the Services section first.
The Boxcar agent sends push notifications to iPhone.
To be able to use the Boxcar end-user API, you need your Access Token
.
The access token is available on general “Settings” screen of Boxcar iOS
app or from Boxcar Web Inbox settings page.
Please provide your access token in the user_credentials
option. If
you’d like to use a credential, set the user_credentials
option to {%
credential CREDENTIAL_NAME %}
.
Options:
user_credentials
- Boxcar access token.title
- Title of the message.body
- Body of the message.source_name
- Name of the source of the message. Set to Huginn
by default.icon_url
- URL to the icon.sound
- Sound to be played for the notification. Set to ‘bird-1’ by default.The huginn catalog agent checks if new campaign is available.
changes_only
is only used to emit event about a currency’s change.
expected_receive_period_in_days
is used to determine if the Agent is working. Set it to the maximum number of days
that you anticipate passing without this Agent receiving an incoming Event.
The Change Detector Agent receives a stream of events and emits a new event when a property of the received event changes.
property
specifies a Liquid template that expands to the property to be watched, where you can use a variable last_property
for the last property value. If you want to detect a new lowest price, try this: {% assign drop = last_property | minus: price %}{% if last_property == blank or drop > 0 %}{{ price | default: last_property }}{% else %}{{ last_property }}{% endif %}
expected_update_period_in_days
is used to determine if the Agent is working.
The resulting event will be a copy of the received event.
The Commander Agent is triggered by schedule or an incoming event, and commands other agents (“targets”) to run, disable, configure, or enable themselves.
Set action
to one of the action types below:
run
: Target Agents are run when this agent is triggered.
disable
: Target Agents are disabled (if not) when this agent is triggered.
enable
: Target Agents are enabled (if not) when this agent is triggered.
drop_pending_events
is set to true
, pending events will be cleared before the agent is enabled.configure
: Target Agents have their options updated with the contents of configure_options
.Here’s a tip: you can use Liquid templating to dynamically determine the action type. For example:
To create a CommanderAgent that receives an event from a WeatherAgent every morning to kick an agent flow that is only useful in a nice weather, try this: {% if conditions contains 'Sunny' or conditions contains 'Cloudy' %}
run{% endif %}
Likewise, if you have a scheduled agent flow specially crafted for rainy days, try this: {% if conditions contains 'Rain' %}enable{% else %}disabled{% endif %}
If you want to update a WeatherAgent based on a UserLocationAgent, you could use 'action': 'configure'
and set ‘configure_options’ to { 'location': '{{_location_.latlng}}' }
.
In templating, you can use the variable target
to refer to each target agent, which has the following attributes: sources
, type
, id
, url
, receivers
, keep_events_for
, propagate_immediately
, working
, schedule
, name
, controllers
, disabled
, options
, memory
, and control_targets
.
Select Agents that you want to control from this CommanderAgent.
The CsvAgent
parses or serializes CSV data. When parsing, events can either be emitted for the entire CSV, or one per row.
Set mode
to parse
to parse CSV from incoming event, when set to serialize
the agent serilizes the data of events to CSV.
Specify the separator
which is used to seperate the fields from each other (default is ,
).
data_key
sets the key which contains the serialized CSV or parsed CSV data in emitted events.
If use_fields
is set to a comma seperated string and the CSV file contains field headers the agent will only extract the specified fields.
output
determines wheather one event per row is emitted or one event that includes all the rows.
Set with_header
to true
if first line of the CSV file are field names.
This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: FtpsiteAgent
, S3Agent
, LocalFileAgent
. Read more about the concept in the wiki.
When receiving the CSV data in a regular event use JSONPath to select the path in data_path
. data_path
is only used when the received event does not contain a ‘file pointer’.
If use_fields
is set to a comma seperated string and the first received event has a object at the specified data_path
the generated CSV will only include the given fields.
Set with_header
to true
to include a field header in the CSV.
Use JSONPath in data_path
to select with part of the received events should be serialized.
The Data Output Agent outputs received events as either RSS or JSON. Use it to output a public or private stream of Huginn data.
This Agent will output data at:
https:///users/1/web_requests/:id/:secret.xml
where :secret
is one of the allowed secrets specified in your options and the extension can be xml
or json
.
You can setup multiple secrets so that you can individually authorize external systems to access your Huginn data.
Options:
secrets
- An array of tokens that the requestor must provide for light-weight authentication.expected_receive_period_in_days
- How often you expect data to be received by this Agent from other Agents.template
- A JSON object representing a mapping between item output keys and incoming event values. Use Liquid to format the values. Values of the link
, title
, description
and icon
keys will be put into the <channel> section of RSS output. Value of the self
key will be used as URL for this feed itself, which is useful when you serve it via reverse proxy. The item
key will be repeated for every Event. The pubDate
key for each item will have the creation time of the Event unless given.events_to_show
- The number of events to output in RSS or JSON. (default: 40
)ttl
- A value for the <ttl> element in RSS output. (default: 60
)ns_media
- Add yahoo media namespace in output xmlns_itunes
- Add itunes compatible namespace in output xmlrss_content_type
- Content-Type for RSS output (default: application/rss+xml
)response_headers
- An object with any custom response headers. (example: {"Access-Control-Allow-Origin": "*"}
)push_hubs
- Set to a list of PubSubHubbub endpoints you want to publish an update to every time this agent receives an event. (default: none) Popular hubs include Superfeedr and Google. Note that publishing updates will make your feed URL known to the public, so if you want to keep it secret, set up a reverse proxy to serve your feed via a safe URL and specify it in template.self
.If you’d like to output RSS tags with attributes, such as enclosure
, use something like the following in your template
:
"enclosure": {
"_attributes": {
"url": "{{media_url}}",
"length": "1234456789",
"type": "audio/mpeg"
}
},
"another_tag": {
"_attributes": {
"key": "value",
"another_key": "another_value"
},
"_contents": "tag contents (can be an object for nesting)"
}
To specify the order of events, set events_order
to an array of sort keys, each of which looks like either expression
or [expression, type, descending]
, as described as follows:
expression is a Liquid template to generate a string to be used as sort key.
type (optional) is one of string
(default), number
and time
, which specifies how to evaluate expression for comparison.
descending (optional) is a boolean value to determine if comparison should be done in descending (reverse) order, which defaults to false
.
Sort keys listed earlier take precedence over ones listed later. For example, if you want to sort articles by the date and then by the author, specify [["{{date}}", "time"], "{{author}}"]
.
Sorting is done stably, so even if all events have the same set of sort key values the original order is retained. Also, a special Liquid variable _index_
is provided, which contains the zero-based index number of each event, which means you can exactly reverse the order of events by specifying [["{{_index_}}", "number", true]]
.
DataOutputAgent will select the last events_to_show
entries of its received events sorted in the order specified by events_order
, which is defaulted to the event creation time.
So, if you have multiple source agents that may create many events in a run, you may want to either increase events_to_show
to have a larger “window”, or specify the events_order
option to an appropriate value (like date_published
) so events from various sources are properly mixed in the resulted feed.
There is also an option events_list_order
that only controls the order of events listed in the final output, without attempting to maintain a total order of received events. It has the same format as events_order
and is defaulted to [["{{_index_}}","number",true]]
so the selected events are listed in reverse order like most popular RSS feeds list their articles.
In Liquid templating, the following variable is available:
events
: An array of events being output, sorted in the given order, up to events_to_show
in number. For example, if source events contain a site title in the site_title
key, you can refer to it in template.title
by putting {{events.first.site_title}}
.The De-duplication Agent receives a stream of events and remits the event if it is not a duplicate.
property
the value that should be used to determine the uniqueness of the event (empty to use the whole payload)
lookback
amount of past Events to compare the value to (0 for unlimited)
expected_update_period_in_days
is used to determine if the Agent is working.
The DelayAgent stores received Events and emits copies of them on a schedule. Use this as a buffer or queue of Events.
max_events
should be set to the maximum number of events that you’d like to hold in the buffer. When this number is
reached, new events will either be ignored, or will displace the oldest event already in the buffer, depending on
whether you set keep
to newest
or oldest
.
expected_receive_period_in_days
is used to determine if the Agent is working. Set it to the maximum number of days
that you anticipate passing without this Agent receiving an incoming Event.
max_emitted_events
is used to limit the number of the maximum events which should be created. If you omit this DelayAgent will create events for every event stored in the memory.
The Digest Agent collects any Events sent to it and emits them as a single event.
The resulting Event will have a payload message of message
. You can use liquid templating in the message
, have a look at the Wiki for details.
Set expected_receive_period_in_days
to the maximum amount of time that you’d expect to pass between Events being received by this Agent.
If retained_events
is set to 0 (the default), all received events are cleared after a digest is sent. Set retained_events
to a value larger than 0 to keep a certain number of events around on a rolling basis to re-send in future digests.
For instance, say retained_events
is set to 3 and the Agent has received Events 5
, 4
, and 3
. When a digest is sent, Events 5
, 4
, and 3
are retained for a future digest. After Event 6
is received, the next digest will contain Events 6
, 5
, and 4
.
The DropboxFileUrlAgent is used to work with Dropbox. It takes a file path (or multiple files paths) and emits events with either temporary links or permanent links.
dropbox-api
and omniauth-dropbox
gems in your Gemfile
and set DROPBOX_OAUTH_KEY
and DROPBOX_OAUTH_SECRET
in your environment to use Dropbox Agents.The incoming event payload needs to have a paths
key, with a comma-separated list of files you want the URL for. For example:
{
"paths": "first/path, second/path"
}
TIP: You can use the Event Formatting Agent to format events before they come in. Here’s an example configuration for formatting an event coming out of a Dropbox Watch Agent:
{
"instructions": {
"paths": "{{ added | map: 'path' | join: ',' }}"
},
"matchers": [],
"mode": "clean"
}
An example of usage would be to watch a specific Dropbox directory (with the DropboxWatchAgent) and get the URLs for the added or updated files. You could then, for example, send emails with those links.
Set link_type
to 'temporary'
if you want temporary links, or to 'permanent'
for permanent ones.
The Dropbox Watch Agent watches the given dir_to_watch
and emits events with the detected changes.
dropbox-api
and omniauth-dropbox
gems in your Gemfile
and set DROPBOX_OAUTH_KEY
and DROPBOX_OAUTH_SECRET
in your environment to use Dropbox Agents.The Email Agent sends any events it receives via email immediately.
You can specify the email’s subject line by providing a subject
option, which can contain Liquid formatting. E.g.,
you could provide "Huginn email"
to set a simple subject, or {{subject}}
to use the subject
key from the incoming Event.
By default, the email body will contain an optional headline
, followed by a listing of the Events’ keys.
You can customize the email body by including the optional body
param. Like the subject
, the body
can be a simple message
or a Liquid template. You could send only the Event’s some_text
field with a body
set to {{ some_text }}
.
The body can contain simple HTML and will be sanitized. Note that when using body
, it will be wrapped with <html>
and <body>
tags,
so you do not need to add these yourself.
You can specify one or more recipients
for the email, or skip the option in order to send the email to your
account’s default email address.
You can provide a from
address for the email, or leave it blank to default to the value of EMAIL_FROM_ADDRESS
(``).
You can provide a content_type
for the email and specify text/plain
or text/html
to be sent.
If you do not specify content_type
, then the recipient email server will determine the correct rendering.
Set expected_receive_period_in_days
to the maximum amount of time that you’d expect to pass between Events being received by this Agent.
The Email Digest Agent collects any Events sent to it and sends them all via email when scheduled. The number of
used events also relies on the Keep events
option of the emitting Agent, meaning that if events expire before
this agent is scheduled to run, they will not appear in the email.
By default, the email will have a subject
and an optional headline
before listing the Events. If the Events’
payloads contain a message
, that will be highlighted, otherwise everything in
their payloads will be shown.
You can specify one or more recipients
for the email, or skip the option in order to send the email to your
account’s default email address.
You can provide a from
address for the email, or leave it blank to default to the value of EMAIL_FROM_ADDRESS
(``).
You can provide a content_type
for the email and specify text/plain
or text/html
to be sent.
If you do not specify content_type
, then the recipient email server will determine the correct rendering.
Set expected_receive_period_in_days
to the maximum amount of time that you’d expect to pass between Events being received by this Agent.
The Github notification agent fetches notifications and creates an event by notification.
mark_as_read
is used to post request for mark as read notification.
result_limit
is used when you want to limit result per page.
real_value
is used for calculating token value with the tokenDecimal applied.
with_confirmations
is used to avoid an event as soon as it increases.
debug
is used to verbose mode.
type
can be tokentx type (you can see api documentation).
Get a list of “ERC20 - Token Transfer Events” by Address
expected_receive_period_in_days
is used to determine if the Agent is working. Set it to the maximum number of days
that you anticipate passing without this Agent receiving an incoming Event.
The Event Formatting Agent allows you to format incoming Events, adding new fields as needed.
For example, here is a possible Event:
{
"high": {
"celsius": "18",
"fahreinheit": "64"
},
"date": {
"epoch": "1357959600",
"pretty": "10:00 PM EST on January 11, 2013"
},
"conditions": "Rain showers",
"data": "This is some data"
}
You may want to send this event to another Agent, for example a Twilio Agent, which expects a message
key.
You can use an Event Formatting Agent’s instructions
setting to do this in the following way:
"instructions": {
"message": "Today's conditions look like {{conditions}} with a high temperature of {{high.celsius}} degrees Celsius.",
"subject": "{{data}}",
"created_at": "{{created_at}}"
}
Names here like conditions
, high
and data
refer to the corresponding values in the Event hash.
The special key created_at
refers to the timestamp of the Event, which can be reformatted by the date
filter, like {{created_at | date:"at %I:%M %p" }}
.
The upstream agent of each received event is accessible via the key agent
, which has the following attributes: sources
, type
, id
, url
, receivers
, keep_events_for
, propagate_immediately
, working
, schedule
, name
, controllers
, disabled
, options
, memory
, control_targets
.
Have a look at the Wiki to learn more about liquid templating.
Events generated by this possible Event Formatting Agent will look like:
{
"message": "Today's conditions look like Rain showers with a high temperature of 18 degrees Celsius.",
"subject": "This is some data"
}
In matchers
setting you can perform regular expression matching against contents of events and expand the match data for use in instructions
setting. Here is an example:
{
"matchers": [
{
"path": "{{date.pretty}}",
"regexp": "\A(?<time>\d\d:\d\d [AP]M [A-Z]+)",
"to": "pretty_date"
}
]
}
This virtually merges the following hash into the original event hash:
"pretty_date": {
"time": "10:00 PM EST",
"0": "10:00 PM EST on January 11, 2013"
"1": "10:00 PM EST"
}
So you can use it in instructions
like this:
"instructions": {
"message": "Today's conditions look like {{conditions}} with a high temperature of {{high.celsius}} degrees Celsius according to the forecast at {{pretty_date.time}}.",
"subject": "{{data}}"
}
If you want to retain original contents of events and only add new keys, then set mode
to merge
, otherwise set it to clean
.
To CGI escape output (for example when creating a link), use the Liquid uri_escape
filter, like so:
{
"message": "A peak was on Twitter in {{group_by}}. Search: https://twitter.com/search?q={{group_by | uri_escape}}"
}
The Evernote Agent connects with a user’s Evernote note store.
Visit Evernote to set up an Evernote app and receive an api key and secret. Store these in the Evernote environment variables in the .env file. You will also need to create a Sandbox account to use during development.
Next, you’ll need to authenticate with Evernote in the Services section.
Options:
mode
- Two possible values:
update
Based on events it receives, the agent will create notes
or update notes with the same title
and notebook
read
On a schedule, it will generate events containing data for newly
added or updated notes
include_xhtml_content
- Set to true
to include the content in ENML (Evernote Markup Language) of the note
note
When mode
is update
the parameters of note
are the attributes of the note to be added/edited.
To edit a note, both title
and notebook
must be set.
For example, to add the tags ‘comic’ and ‘CS’ to a note titled ‘xkcd Survey’ in the notebook ‘xkcd’, use:
"notes": {
"title": "xkcd Survey",
"content": "",
"notebook": "xkcd",
"tagNames": "comic, CS"
}
If a note with the above title and notebook did note exist already, one would be created.
When mode
is read
the values are search parameters.
Note: The content
parameter is not used for searching. Setting title
only filters
notes whose titles contain title
as a substring, not as the exact title.
For example, to find all notes with tag ‘CS’ in the notebook ‘xkcd’, use:
"notes": {
"title": "",
"content": "",
"notebook": "xkcd",
"tagNames": "CS"
}
Create events from Fitbit activities
OAUTHv2 client and secret can be specified in the configuration of the
agent or globally using ENV['FITBIT_OAUTH2_CLIENT']
and
ENV['FITBIT_OAUTH2_SECRET']
.
The agent will remember some (loopback
=50) activities so it can update
them instead of creating new ones.
Refer to this page for a list of properties of the events created.
After the agent is created go into its description to complete the OAUTHv2 flow and authorize it to read your Fitbit data.
The Ftp Site Agent checks an FTP site and creates Events based on newly uploaded files in a directory. When receiving events it creates files on the configured FTP server.
mode
must be present and either read
or write
, in read
mode the agent checks the FTP site for changed files, with write
it writes received events to a file on the server.
Specify a url
that represents a directory of an FTP site to watch, and a list of patterns
to match against file names.
Login credentials can be included in url
if authentication is required: ftp://username:password@ftp.example.com/path
. Liquid formatting is supported as well: ftp://{% credential ftp_credentials %}@ftp.example.com/
Optionally specify the encoding of the files you want to read/write in force_encoding
, by default UTF-8 is used.
Only files with a last modification time later than the after
value, if specifed, are emitted as event.
Specify the filename to use in filename
, Liquid interpolation is possible to change the name per event.
Use Liquid templating in data
to specify which part of the received event should be written.
This agent only emits a ‘file pointer’, not the data inside the files, the following agents can consume the created events: PostAgent
, CsvAgent
, ReadFileAgent
. Read more about the concept in the wiki.
The Gap Detector Agent will watch for holes or gaps in a stream of incoming Events and generate “no data alerts”.
The value_path
value is a JSONPath to a value of interest. If either
this value is empty, or no Events are received, during window_duration_in_days
, an Event will be created with
a payload of message
.
The Google Calendar Publish Agent creates events on your Google Calendar.
This agent relies on service accounts, rather than oauth.
Setup:
/home/huginn/Huginn-5d12345678cd.json
. Or open that file and copy the private_key
.An earlier version of Huginn used PKCS12 key files to authenticate. This will no longer work, you should generate a new JSON format keyfile, that will look something like:
{
"type": "service_account",
"project_id": "huginn-123123",
"private_key_id": "6d6b476fc6ccdb31e0f171991e5528bb396ffbe4",
"private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
"client_email": "huginn-calendar@huginn-123123.iam.gserviceaccount.com",
"client_id": "123123...123123",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://accounts.google.com/o/oauth2/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/huginn-calendar%40huginn-123123.iam.gserviceaccount.com"
}
Agent Configuration:
calendar_id
- The id the calendar you want to publish to. Typically your google account email address. Liquid formatting (e.g. {{ cal_id }}
) is allowed here in order to extract the calendar_id from the incoming event.
google
A hash of configuration options for the agent.
google
service_account_email
- The authorised service account email address.
google
key_file
OR google
key
- The path to the JSON key file above, or the key itself (the value of private_key
). Liquid formatting is supported if you want to use a Credential. (E.g., {% credential google_key %}
)
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
Use it with a trigger agent to shape your payload!
A hash of event details. See the Google Calendar API docs
The prior version Google’s API expected keys like dateTime
but in the latest version they expect snake case keys like date_time
.
Example payload for trigger agent:
{
"message": {
"visibility": "default",
"summary": "Awesome event",
"description": "An example event with text. Pro tip: DateTimes are in RFC3339",
"start": {
"date_time": "2017-06-30T17:00:00-05:00"
},
"end": {
"date_time": "2017-06-30T18:00:00-05:00"
}
}
}
The Translation Agent will attempt to translate text between natural languages.
Services are provided using Google Translate. You can sign up to get google_api_key
which is required to use this agent.
The service is not free.
To use credentials for the google_api_key
use the liquid credential
tag like so {% credential google-api-key %}
to
must be filled with a translator language code.
from
is the language translated from. If it’s not specified, the API will attempt to detect the source language automatically and return it within the response.
Specify what you would like to translate in content
field, you can use Liquid specify which part of the payload you want to translate.
expected_receive_period_in_days
is the maximum number of days you would allow to pass between events.
The Growl Agent sends any events it receives to a Growl GNTP server immediately.
The option message
, which will hold the body of the growl notification, and the subject
option,
which will have the headline of the Growl notification are required. All other options are optional.
When callback_url
is set to a URL clicking on the notification will open the link in your default browser.
Set expected_receive_period_in_days
to the maximum amount of time that you’d expect to pass between
Events being received by this Agent.
Have a look at the Wiki to learn more about liquid templating.
The Hipchat Agent sends messages to a Hipchat Room
To authenticate you need to set the auth_token
, you can get one at your Hipchat Group Admin page which you can find here:
https://
yoursubdomain.hipchat.com/admin/api
Change the room_name
to the name of the room you want to send notifications to.
You can provide a username
and a message
. If you want to use mentions change format
to “text” (details).
If you want your message to notify the room members change notify
to “True”.
Modify the background color of your message via the color
attribute (one of “yellow”, “red”, “green”, “purple”, “gray”, or “random”)
Have a look at the Wiki to learn more about liquid templating.
The HttpStatusAgent will check a url and emit the resulting HTTP status code with the time that it waited for a reply. Additionally, it will optionally emit the value of one or more specified headers.
Specify a Url
and the Http Status Agent will produce an event with the HTTP status code. If you specify one or more Headers to save
(comma-delimited) as well, that header or headers’ value(s) will be included in the event.
The disable redirect follow
option causes the Agent to not follow HTTP redirects. For example, setting this to true
will cause an agent that receives a 301 redirect to http://yahoo.com
to return a status of 301 instead of following the redirect and returning 200.
The changes only
option causes the Agent to report an event only when the status changes. If set to false, an event will be created for every check. If set to true, an event will only be created when the status changes (like if your site goes from 200 to 500).
The Human Task Agent is used to create Human Intelligence Tasks (HITs) on Mechanical Turk.
HITs can be created in response to events, or on a schedule. Set trigger_on
to either schedule
or event
.
The schedule of this Agent is how often it should check for completed HITs, NOT how often to submit one. To configure how often a new HIT
should be submitted when in schedule
mode, set submission_period
to a number of hours.
If created with an event, all HIT fields can contain interpolated values via liquid templating. For example, if the incoming event was a Twitter event, you could make a HITT to rate its sentiment like this:
{
"expected_receive_period_in_days": 2,
"trigger_on": "event",
"hit": {
"assignments": 1,
"title": "Sentiment evaluation",
"description": "Please rate the sentiment of this message: '{{message}}'",
"reward": 0.05,
"lifetime_in_seconds": "3600",
"questions": [
{
"type": "selection",
"key": "sentiment",
"name": "Sentiment",
"required": "true",
"question": "Please select the best sentiment value:",
"selections": [
{ "key": "happy", "text": "Happy" },
{ "key": "sad", "text": "Sad" },
{ "key": "neutral", "text": "Neutral" }
]
},
{
"type": "free_text",
"key": "feedback",
"name": "Have any feedback for us?",
"required": "false",
"question": "Feedback",
"default": "Type here...",
"min_length": "2",
"max_length": "2000"
}
]
}
}
As you can see, you configure the created HIT with the hit
option. Required fields are title
, which is the
title of the created HIT, description
, which is the description of the HIT, and questions
which is an array of
questions. Questions can be of type
selection or free_text. Both types require the key
, name
, required
,
type
, and question
configuration options. Additionally, selection requires a selections
array of options, each of
which contain key
and text
. For free_text, the special configuration options are all optional, and are
default
, min_length
, and max_length
.
By default, all answers are emitted in a single event. If you’d like separate events for each answer, set separate_answers
to true
.
There are a couple of ways to combine HITs that have multiple assignments
, all of which involve setting combination_mode
at the top level.
Option 1: if all of your questions
are of type
selection, you can set combination_mode
to take_majority
.
This will cause the Agent to automatically select the majority vote for each question across all assignments
and return it as majority_answer
.
If all selections are numeric, an average_answer
will also be generated.
Option 2: you can have the Agent ask additional human workers to rank the assignments
and return the most highly ranked answer.
To do this, set combination_mode
to poll
and provide a poll_options
object. Here is an example:
{
"trigger_on": "schedule",
"submission_period": 12,
"combination_mode": "poll",
"poll_options": {
"title": "Take a poll about some jokes",
"instructions": "Please rank these jokes from most funny (5) to least funny (1)",
"assignments": 3,
"row_template": "{{joke}}"
},
"hit": {
"assignments": 5,
"title": "Tell a joke",
"description": "Please tell me a joke",
"reward": 0.05,
"lifetime_in_seconds": "3600",
"questions": [
{
"type": "free_text",
"key": "joke",
"name": "Your joke",
"required": "true",
"question": "Joke",
"min_length": "2",
"max_length": "2000"
}
]
}
}
Resulting events will have the original answers
, as well as the poll
results, and a field called best_answer
that contains the best answer as determined by the poll. (Note that separate_answers
won’t work when doing a poll.)
lifetime_in_seconds
is the number of seconds a HIT is left on Amazon before it’s automatically closed. The default is 1 day.
As with most Agents, expected_receive_period_in_days
is required if trigger_on
is set to event
.
The Imap Folder Agent checks an IMAP server in specified folders and creates Events based on new mails found since the last run. In the first visit to a folder, this agent only checks for the initial status and does not create events.
Specify an IMAP server to connect with host
, and set ssl
to true if the server supports IMAP over SSL. Specify port
if you need to connect to a port other than standard (143 or 993 depending on the ssl
value).
Specify login credentials in username
and password
.
List the names of folders to check in folders
.
To narrow mails by conditions, build a conditions
hash with the following keys:
subject
body
Specify a regular expression to match against the decoded subject/body of each mail.
Use the (?i)
directive for case-insensitive search. For example, a pattern (?i)alert
will match “alert”, “Alert”or “ALERT”. You can also make only a part of a pattern to work case-insensitively: Re: (?i:alert)
will match either “Re: Alert” or “Re: alert”, but not “RE: alert”.
When a mail has multiple non-attachment text parts, they are prioritized according to the mime_types
option (which see below) and the first part that matches a “body” pattern, if specified, will be chosen as the “body” value in a created event.
Named captures will appear in the “matches” hash in a created event.
from
, to
, cc
Specify a shell glob pattern string that is matched against mail addresses extracted from the corresponding header values of each mail.
Patterns match addresses in case insensitive manner.
Multiple pattern strings can be specified in an array, in which case a mail is selected if any of the patterns matches. (i.e. patterns are OR’d)
mime_types
Specify an array of MIME types to tell which non-attachment part of a mail among its text/* parts should be used as mail body. The default value is ['text/plain', 'text/enriched', 'text/html']
.
is_unread
Setting this to true or false means only mails that is marked as unread or read respectively, are selected.
If this key is unspecified or set to null, it is ignored.
has_attachment
Setting this to true or false means only mails that does or does not have an attachment are selected.
If this key is unspecified or set to null, it is ignored.
Set mark_as_read
to true to mark found mails as read.
Set delete
to true to delete found mails.
Set event_headers
to a list of header names you want to include in a headers
hash in each created event, either in an array of string or in a comma-separated string.
Set event_headers_style
to one of the following values to normalize the keys of “headers” for downstream agents’ convenience:
capitalized
(default) - Header names are capitalized; e.g. “Content-Type”downcased
- Header names are downcased; e.g. “content-type”snakecased
- Header names are snakecased; e.g. “content_type”Set include_raw_mail
to true to add a raw_mail
value to each created event, which contains a Base64-encoded blob in the “RFC822” format defined in the IMAP4 standard. Note that while the result of Base64 encoding will be LF-terminated, its raw content will often be CRLF-terminated because of the nature of the e-mail protocols and formats. The primary use case for a raw mail blob is to pass to a Shell Command Agent with a command like openssl enc -d -base64 | tr -d '
' | procmail -Yf-
.
Each agent instance memorizes the highest UID of mails that are found in the last run for each watched folder, so even if you change a set of conditions so that it matches mails that are missed previously, or if you alter the flag status of already found mails, they will not show up as new events.
Also, in order to avoid duplicated notification it keeps a list of Message-Id’s of 100 most recent mails, so if multiple mails of the same Message-Id are found, you will only see one event out of them.
Monitor public Instagram accounts and creates an event for each post.
It can be scheduled to hit Instagram as much as you want but will obey
the wait_between_refresh
for each account to avoid being banned.
If set to 0
it will refresh all accounts at every run.
Links generally expire after 24 hours but this agent will try to keep the corresponding events updated so they can be used in a feed.
The Jabber Agent will send any events it receives to your Jabber/XMPP IM account.
Specify the jabber_server
and jabber_port
for your Jabber server.
The message
is sent from jabber_sender
to jaber_receiver
. This message
can contain any keys found in the source’s payload, escaped using double curly braces.
ex: "News Story: {{title}}: {{url}}"
When connect_to_receiver
is set to true, the JabberAgent will emit an event for every message it receives.
Have a look at the Wiki to learn more about liquid templating.
The JavaScript Agent allows you to write code in JavaScript that can create and receive events. If other Agents aren’t meeting your needs, try this one!
You can put code in the code
option, or put your code in a Credential and reference it from code
with credential:<name>
(recommended).
You can implement Agent.check
and Agent.receive
as you see fit. The following methods will be available on Agent in the JavaScript environment:
this.createEvent(payload)
this.incomingEvents()
(the returned event objects will each have a payload
property)this.memory()
this.memory(key)
this.memory(keyToSet, valueToSet)
this.setMemory(object)
(replaces the Agent’s memory with the provided object)this.deleteKey(key)
(deletes a key from memory and returns the value)this.credential(name)
this.credential(name, valueToSet)
this.options()
this.options(key)
this.log(message)
this.error(message)
this.escapeHtml(htmlToEscape)
this.unescapeHtml(htmlToUnescape)
The Jira Agent subscribes to Jira issue updates.
jira_url
specifies the full URL of the jira installation, including https://jql
is an optional Jira Query Language-based filter to limit the flow of events. See JQL Docs for details. username
and password
are optional, and may need to be specified if your Jira instance is read-protectedtimeout
is an optional parameter that specifies how long the request processing may take in minutes.The agent does periodic queries and emits the events containing the updated issues in JSON format.
NOTE: upon the first execution, the agent will fetch everything available by the JQL query. So if it’s not desirable, limit the jql
query by date.
The Jq Agent allows you to process incoming Events with jq the JSON processor. (This agent is not enabled on this server)
It allows you to filter, transform and restructure Events in the way you want using jq’s powerful features.
You can specify a jq filter expression to apply to each incoming event in filter
, and results it produces will become Events to be emitted.
You can optionally pass in variables to the filter program by specifying key-value pairs of a variable name and an associated value in the variables
key, each of which becomes a predefined variable.
This Agent can be used to parse a complex JSON structure that is too hard to handle with JSONPath or Liquid templating.
For example, suppose that a Post Agent created an Event which contains a body
key with a value of the JSON formatted string of the following response body:
{
"status": "1",
"since": "1245626956",
"list": {
"93817": {
"item_id": "93817",
"url": "http://url.com",
"title": "Page Title",
"time_updated": "1245626956",
"time_added": "1245626956",
"tags": "comma,seperated,list",
"state": "0"
},
"935812": {
"item_id": "935812",
"url": "http://google.com",
"title": "Google",
"time_updated": "1245635279",
"time_added": "1245635279",
"tags": "comma,seperated,list",
"state": "1"
}
}
}
Then you could have a Jq Agent with the following jq filter:
.body | fromjson | .list | to_entries | map(.value) | map(try(.tags |= split(",")) // .) | sort_by(.time_added | tonumber)
To get the following two Events emitted out of the said incoming Event from Post Agent:
[
{
"item_id": "93817",
"url": "http://url.com",
"title": "Page Title",
"time_updated": "1245626956",
"time_added": "1245626956",
"tags": ["comma", "seperated", "list"],
"state": "0"
},
{
"item_id": "935812",
"url": "http://google.com",
"title": "Google",
"time_updated": "1245626956",
"time_added": "1245626956",
"tags": ["comma", "seperated", "list"],
"state": "1"
}
]
The JSON Parse Agent parses a JSON string and emits the data in a new event or merge with with the original event.
data
is the JSON to parse. Use Liquid templating to specify the JSON string.
data_key
sets the key which contains the parsed JSON data in emitted events
mode
determines whether create a new clean
event or merge
old payload with new values (default: clean
)
Add a Agent description here
The Liquid Output Agent outputs events through a Liquid template you provide. Use it to create a HTML page, or a json feed, or anything else that can be rendered as a string from your stream of Huginn data.
This Agent will output data at:
https:///users/1/web_requests/:id/:secret.any_extension
where :secret
is the secret specified in your options. You can use any extension you wish.
Options:
secret
- A token that the requestor must provide for light-weight authentication.expected_receive_period_in_days
- How often you expect data to be received by this Agent from other Agents.content
- The content to display when someone requests this page.mime_type
- The mime type to use when someone requests this page.response_headers
- An object with any custom response headers. (example: {"Access-Control-Allow-Origin": "*"}
)mode
- The behavior that determines what data is passed to the Liquid template.event_limit
- A limit applied to the events passed to a template when in “Last X events” mode. Can be a count like “1”, or an amount of time like “1 day” or “5 minutes”.The content you provide will be run as a Liquid template. The data from the last event received will be used when processing the Liquid template.
The data for incoming events will be merged. So if two events come in like this:
{ 'a' => 'b', 'c' => 'd'}
{ 'a' => 'bb', 'e' => 'f'}
The final result will be:
{ 'a' => 'bb', 'c' => 'd', 'e' => 'f'}
This merged version will be passed to the Liquid template.
The data from the last event will be passed to the template.
All of the events received by this agent will be passed to the template
as the events
array.
The number of events can be controlled via the event_limit
option.
If event_limit
is an integer X, the last X events will be passed
to the template. If event_limit
is an integer with a unit of
measure like “1 day” or “5 minutes” or “9 years”, a date filter will
be applied to the events passed to the template. If no event_limit
is provided, then all of the events for the agent will be passed to
the template.
For performance, the maximum event_limit
allowed is 1000.
The Github notification agent fetches notifications and creates an event by notification.
mark_as_read
is used to post request for mark as read notification.
result_limit
is used when you want to limit result per page.
real_value
is used for calculating token value with the tokenDecimal applied.
with_confirmations
is used to avoid an event as soon as it increases.
debug
is used to verbose mode.
type
can be tokentx type (you can see api documentation).
Get a list of “ERC20 - Token Transfer Events” by Address
expected_receive_period_in_days
is used to determine if the Agent is working. Set it to the maximum number of days
that you anticipate passing without this Agent receiving an incoming Event.
The LocalFileAgent can watch a file/directory for changes or emit an event for every file in that directory. When receiving an event it writes the received data into a file.
mode
determines if the agent is emitting events for (changed) files or writing received event data to disk.
When watch
is set to true
the LocalFileAgent will watch the specified path
for changes, the schedule is ignored and the file system is watched continuously. An event will be emitted for every detected change.
When watch
is set to false
the agent will emit an event for every file in the directory on each scheduled run.
This agent only emits a ‘file pointer’, not the data inside the files, the following agents can consume the created events: PostAgent
, CsvAgent
, ReadFileAgent
. Read more about the concept in the wiki.
Every event will be writting into a file at path
, Liquid interpolation is possible to change the path per event.
When append
is true the received data will be appended to the file.
Use Liquid templating in data
to specify which part of the received event should be written.
Warning: This type of Agent can read and write any file the user that runs the Huginn server has access to, and is currently disabled.
Only enable this Agent if you trust everyone using your Huginn installation.
You can enable this Agent in your .env file by setting ENABLE_INSECURE_AGENTS
to true
.
The Manual Event Agent is used to manually create Events for testing or other purposes.
Connect this Agent to other Agents and create Events using the UI provided on this Agent’s Summary page.
You can set the default event payload via the “payload” option.
The Moves Agent pulls location data from your Moves app.
The Moves Current Location agent pulls the most recent location from your Moves app.
To be able to use this Agent you need to authenticate with Moves in the Services section first.
The MQTT Agent allows both publication and subscription to an MQTT topic.
MQTT is a generic transport protocol for machine to machine communication.
You can do things like:
Simply choose a topic (think email subject line) to publish/listen to, and configure your service.
It’s easy to setup your own broker or connect to a cloud service
Hints: Many services run mqtts (mqtt over SSL) often with a custom certificate.
You’ll want to download their cert and install it locally, specifying the certificate_path
configuration.
Example configuration:
{
'uri' => 'mqtts://user:pass@localhost:8883'
'ssl' => :TLSv1,
'ca_file' => './ca.pem',
'cert_file' => './client.crt',
'key_file' => './client.key',
'topic' => 'huginn'
}
Subscribe to CloCkWeRX’s TheThingSystem instance (thethingsystem.com), where temperature and other events are being published.
{
'uri' => 'mqtt://kcqlmkgx:sVNoccqwvXxE@m10.cloudmqtt.com:13858',
'topic' => 'the_thing_system/demo'
}
Subscribe to all topics
{
'uri' => 'mqtt://kcqlmkgx:sVNoccqwvXxE@m10.cloudmqtt.com:13858',
'topic' => '/#'
}
Find out more detail on subscription wildcards
The Naive Bayes Agent uses incoming Events from certain sources as a training set for Naive Bayes Machine Learning. Then it classifies Events from other sources and adds category tags to them accordingly.
All incoming events should have these two fields in their payloads, likely via the Event Formatting or Javascript Agent:
nb_content
for the content used for classification, space separated. nb_cats
for the classification categories, space separated.If nb_cats
is empty or contains =class
, then the content from nb_content
will be classified according to the training data. The categories will be added to nb_cats
and then a new event is created with that payload.
However, if nb_cats
is already populated, then the content from nb_content
will be used as training data for the categories listed in nb_cats
. For instance, say nb_cats
consists of trees
. Then nb_content
will be used as training data for the category trees
. The data is saved to the agent memory.
Data in nb_content
can be cleaned before classification. If strip_punctuation
is set to true, the text in nb_content
is stripped of punctuation before it is sent to the classifier. The changes are not saved to nb_content
but will affect the Agent’s saved training data.
Content can also be “stemmed”, reducing words to their base, by setting stem
to true. Stemming will reduce “epistemology”, “epistemologies”, and “epistemological” all to “epistemolog”. See here for the implementation used. Again, changes are not saved to nb_content
but will affect the Agent’s saved training data.
When an event is received for classification, the Naive Bayes Agent will assign a value between 0 and 1 representing the likelihood that it falls under a category. The min_value
option lets you choose the minimum threshold that must be reached before the event is labeled with that category. If min_value
is set to 1, then the event is labeled with whichever category has the highest value.
The option propagate_training_events
lets you choose whether the training events are emitted along with the classified events. If it is set to false, then no new event will be created from events that already had categories when they were received.
To load trained data into an agent’s memory, create a Manual Agent with nb_cats : =loadYML
and nb_content : your-well-formed-training-data-here
. Use the text input box, not the form view, by clicking “Toggle View” when inputting your training data else whitespace errors occur in the YML. Then submit this to your Naive Bayes Agent.
Be carefull with these functions: see the documentation linked below.
If a category has a -
in front of it, eg. -trees
, then the category trees
will be UNtrained according to that content.
Low frequency words that increase processing time and may overfit - tokens with a count less than x (measured by summing across all classes) - can be removed: Set nb_cats : =purgeTokens
and nb_content : integer-value
.
Categories can be similarly deleted by nb_cats : =delCat
and nb_content : categories to delete
.
See the NBayes ruby gem and this blog post for more information about the Naive Bayes implementation used here.
The S3Agent can watch a bucket for changes or emit an event for every file in that bucket. When receiving events, it writes the data into a file on S3.
mode
must be present and either read
or write
, in read
mode the agent checks the S3 bucket for changed files, with write
it writes received events to a file in the bucket.
To use credentials for the access_key
and access_key_secret
use the liquid credential
tag like so {% credential name-of-credential %}
Select the region
in which the bucket was created.
When watch
is set to true
the S3Agent will watch the specified bucket
for changes. An event will be emitted for every detected change.
When watch
is set to false
the agent will emit an event for every file in the bucket on each sheduled run.
This agent only emits a ‘file pointer’, not the data inside the files, the following agents can consume the created events: PostAgent
, CsvAgent
, ReadFileAgent
. Read more about the concept in the wiki.
Specify the filename to use in filename
, Liquid interpolation is possible to change the name per event.
Use Liquid templating in data
to specify which part of the received event should be written.
The PDF Info Agent returns the metadata contained within a given PDF file, using HyPDF.
In order for this agent to work, you need to have HyPDF running and configured.
It works by acting on events that contain a key url
in their payload, and runs the pdfinfo command on them.
The Peak Detector Agent will watch for peaks in an event stream. When a peak is detected, the resulting Event will have a payload message of message
. You can include extractions in the message, for example: I saw a bar of: {{foo.bar}}
, have a look at the Wiki for details.
The value_path
value is a JSONPath to the value of interest. group_by_path
is a JSONPath that will be used to group values, if present.
Set expected_receive_period_in_days
to the maximum amount of time that you’d expect to pass between Events being received by this Agent.
You may set window_duration_in_days
to change the default memory window length of 14
days, min_peak_spacing_in_days
to change the default minimum peak spacing of 2
days (peaks closer together will be ignored), and std_multiple
to change the default standard deviation threshold multiple of 3
.
You may set min_events
for the minimal number of accumulated events before the agent starts detecting.
You may set search_url
to point to something else than Twitter search, using the URI Template syntax defined in RFC 6570. Default value is https://twitter.com/search?q={q}
where {q}
will be replaced with group name.
This Agent generates PhantomJs Cloud URLs that can be used to render JavaScript-heavy webpages for content extraction.
URLs generated by this Agent are formulated in accordance with the PhantomJs Cloud API. The generated URLs can then be supplied to a Website Agent to fetch and parse the content.
Sign up to get an api key, and add it in Huginn credentials.
Please see the Huginn Wiki for more info.
Options:
Api key
- PhantomJs Cloud API Key credential stored in HuginnUrl
- The url to renderMode
- Create a new clean
event or merge
old payload with new values (default: clean
)Render type
- Render as html, plain text without html tags, or jpg as screenshot of the page (default: html
)Output as json
- Return the page contents and metadata as a JSON object (default: false
)Ignore images
- Skip loading of inlined images (default: false
)Url agent
- A custom User-Agent name (default: Huginn - https://github.com/huginn/huginn
)Wait interval
- Milliseconds to delay rendering after the last resource is finished loading.
This is useful in case there are any AJAX requests or animations that need to finish up.
This can safely be set to 0 if you know there are no AJAX or animations you need to wait for (default: 1000
ms)As this agent only provides a limited subset of the most commonly used options, you can follow this guide to make full use of additional options PhantomJsCloud provides.
The agent checks a port (TCP) for a specific host.
expected_receive_period_in_days
is used to determine if the Agent is working. Set it to the maximum number of days
that you anticipate passing without this Agent receiving an incoming Event.
A Post Agent receives events from other agents (or runs periodically), merges those events with the Liquid-interpolated contents of payload
, and sends the results as POST (or GET) requests to a specified url. To skip merging in the incoming event, but still send the interpolated payload, set no_merge
to true
.
The post_url
field must specify where you would like to send requests. Please include the URI scheme (http
or https
).
The method
used can be any of get
, post
, put
, patch
, and delete
.
By default, non-GETs will be sent with form encoding (application/x-www-form-urlencoded
).
Change content_type
to json
to send JSON instead.
Change content_type
to xml
to send XML, where the name of the root element may be specified using xml_root
, defaulting to post
.
When content_type
contains a MIME type, and payload
is a string, its interpolated value will be sent as a string in the HTTP request’s body and the request’s Content-Type
HTTP header will be set to content_type
. When payload
is a string no_merge
has to be set to true
.
If emit_events
is set to true
, the server response will be emitted as an Event and can be fed to a WebsiteAgent for parsing (using its data_from_event
and type
options). No data processing
will be attempted by this Agent, so the Event’s “body” value will always be raw text.
The Event will also have a “headers” hash and a “status” integer value.
If output_mode
is set to merge
, the emitted Event will be merged into the original contents of the received Event.
Set event_headers
to a list of header names, either in an array of string or in a comma-separated string, to include only some of the header values.
Set event_headers_style
to one of the following values to normalize the keys of “headers” for downstream agents’ convenience:
capitalized
(default) - Header names are capitalized; e.g. “Content-Type”downcased
- Header names are downcased; e.g. “content-type”snakecased
- Header names are snakecased; e.g. “content_type”raw
- Backward compatibility option to leave them unmodified from what the underlying HTTP library returns.Other Options:
headers
- When present, it should be a hash of headers to send with the request.basic_auth
- Specify HTTP basic auth parameters: "username:password"
, or ["username", "password"]
.disable_ssl_verification
- Set to true
to disable ssl verification.user_agent
- A custom User-Agent name (default: “Faraday v0.12.1”).This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: FtpsiteAgent
, S3Agent
, LocalFileAgent
. Read more about the concept in the wiki.
When receiving a file_pointer
the request will be sent with multipart encoding (multipart/form-data
) and content_type
is ignored. upload_key
can be used to specify the parameter in which the file will be sent, it defaults to file
.
The Public Transport Request Agent generates Events based on NextBus GPS transit predictions.
Specify the following user settings:
First, select an agency by visiting http://www.nextbus.com/predictor/adaAgency.jsp and finding your transit system. Once you find it, copy the part of the URL after ?a=
. For example, for the San Francisco MUNI system, you would end up on http://www.nextbus.com/predictor/adaDirection.jsp?a=sf-muni and copy “sf-muni”. Put that into this Agent’s agency setting.
Next, find the stop tags that you care about.
Select your destination and lets use the n-judah route. The link should be http://www.nextbus.com/predictor/adaStop.jsp?a=sf-muni&r=N Once you find it, copy the part of the URL after r=
.
The link may not work, but we’re just trying to get the part after the r=, so even if it gives an error, continue to the next step.
To find the tags for the sf-muni system, for the N route, visit this URL: http://webservices.nextbus.com/service/publicXMLFeed?command=routeConfig&a=sf-muni&r=N
The tags are listed as tag=”1234”. Copy that number and add the route before it, separated by a pipe ‘|’ symbol. Once you have one or more tags from that page, add them to this Agent’s stop list. E.g,
agency: "sf-muni"
stops: ["N|5221", "N|5215"]
Remember to pick the appropriate stop, which will have different tags for in-bound and out-bound.
This Agent will generate predictions by requesting a URL similar to the following:
Finally, set the arrival window that you’re interested in. E.g., 5 minutes. Events will be created by the agent anytime a new train or bus comes into that time window.
alert_window_in_minutes: 5
The Pushbullet agent sends pushes to a pushbullet device
To authenticate you need to either the api_key
or create a pushbullet_api_key
credential, you can find yours at your account page:
https://www.pushbullet.com/account
If you do not select an existing device, Huginn will create a new one with the name ‘Huginn’.
To push to all of your devices, select All Devices
from the devices list.
You have to provide a message type
which has to be note
, link
, or address
. The message types checklist
, and file
are not supported at the moment.
Depending on the message type
you can use additional fields:
title
and body
title
, body
, and url
name
, and address
In every value of the options hash you can use the liquid templating, learn more about it at the Wiki.
The Pushover Agent receives and collects events and sends them via push notification to a user/group.
You need a Pushover API Token: https://pushover.net/apps/build
token
: your application’s API tokenuser
: the user or group key (not e-mail address).expected_receive_period_in_days
: is maximum number of days that you would expect to pass between events being received by this agent.The following options are all Liquid templates whose evaluated values will be posted to the Pushover API. Only the message
parameter is required, and if it is blank API call is omitted.
Pushover API has a 512
Character Limit including title
. message
will be truncated.
message
- your message (required)device
- your user’s device name to send the message directly to that device, rather than all of the user’s devicestitle
or subject
- your notification’s titleurl
- a supplementary URL to show with your message - 512
Character Limiturl_title
- a title for your supplementary URL, otherwise just the URL is shown - 100
Character Limittimestamp
- a Unix timestamp of your message’s date and time to display to the user, rather than the time your message is received by the Pushover API.priority
- send as -1
to always send as a quiet notification, 0
is default, 1
to display as high-priority and bypass the user’s quiet hours, or 2
for emergency priority: Please read Pushover Docs on Emergency Prioritysound
- the name of one of the sounds supported by device clients to override the user’s default sound choice. See PushOver docs for sound options.retry
- Required for emergency priority - Specifies how often (in seconds) the Pushover servers will send the same notification to the user. Minimum value: 30
expire
- Required for emergency priority - Specifies how many seconds your notification will continue to be retried for (every retry seconds). Maximum value: 86400
html
- set to true
to have Pushover’s apps display the message
content as HTMLThe Github notification agent fetches notifications and creates an event by notification.
changes_only
is only used to emit event about a status’ change.
expected_receive_period_in_days
is used to determine if the Agent is working. Set it to the maximum number of days
that you anticipate passing without this Agent receiving an incoming Event.
This agent fetch stats about user’s suicides and creates a top score for R6 Games
The Raw Webhook Agent will create events by receiving webhooks from any source. In order to create events with this agent, make a POST request to:
https:///users/1/web_requests/:id/:secret
The placeholder symbols above will be replaced by their values once the agent is saved.
secret
(required) - A token that the host will provide for authentication.expected_receive_period_in_days
(required) - How often you expect to receive
events this way. Used to determine if the agent is working.verbs
- Comma-separated list of http verbs your agent will accept.
For example, “post,get” will enable POST and GET requests. Defaults
to “post”.response
- The response message to the request. Defaults to ‘Event Created’.response_headers
- An object with any custom response headers. (example: {"Access-Control-Allow-Origin": "*"}
)code
- The response code to the request. Defaults to ‘201’. If the code is ‘301’ or ‘302’ the request will automatically be redirected to the url defined in “response”.recaptcha_secret
- Setting this to a reCAPTCHA “secret” key makes your agent verify incoming requests with reCAPTCHA. Don’t forget to embed a reCAPTCHA snippet including your “site” key in the originating form(s).recaptcha_send_remote_addr
- Set this to true if your server is properly configured to set REMOTE_ADDR to the IP address of each visitor (instead of that of a proxy server).force_encoding
- Set this to override the automatic detection of request encoding. (example: UTF-8
)content_type
- Override the value of Content-Type header in the response. (example: application/json
, default: text/plain
)The ReadFileAgent takes events from FileHandling
agents, reads the file, and emits the contents as a string.
data_key
specifies the key of the emitted event which contains the file contents.
This agent can consume a ‘file pointer’ event from the following agents with no additional configuration: FtpsiteAgent
, S3Agent
, LocalFileAgent
. Read more about the concept in the wiki.
The Renault ZE Battery Agent checks the battery status of your Renault.
To authenticate you need to either set the username
and password
, or
provide credentials named renault_ze_username
and renault_ze_password
.
The RSS Agent consumes RSS feeds and emits events when they change.
This agent, using Feedjira as a base, can parse various types of RSS and Atom feeds and has some special handlers for FeedBurner, iTunes RSS, and so on. However, supported fields are limited by its general and abstract nature. For complex feeds with additional field types, we recommend using a WebsiteAgent. See this example.
If you want to output an RSS feed, use the DataOutputAgent.
Options:
url
- The URL of the RSS feed (an array of URLs can also be used; items with identical guids across feeds will be considered duplicates).include_feed_info
- Set to true
to include feed information in each event.clean
- Set to true
to sanitize description
and content
as HTML fragments, removing unknown/unsafe elements and attributes.expected_update_period_in_days
- How often you expect this RSS feed to change. If more than this amount of time passes without an update, the Agent will mark itself as not working.headers
- When present, it should be a hash of headers to send with the request.basic_auth
- Specify HTTP basic auth parameters: "username:password"
, or ["username", "password"]
.disable_ssl_verification
- Set to true
to disable ssl verification.disable_url_encoding
- Set to true
to disable url encoding.force_encoding
- Set force_encoding
to an encoding name if the website is known to respond with a missing, invalid or wrong charset in the Content-Type header. Note that a text content without a charset is taken as encoded in UTF-8 (not ISO-8859-1).user_agent
- A custom User-Agent name (default: “Faraday v0.12.1”).max_events_per_run
- Limit number of events created (items parsed) per run for feed.remembered_id_count
- Number of IDs to keep track of and avoid re-emitting (default: 500).To specify the order of events created in each run, set events_order
to an array of sort keys, each of which looks like either expression
or [expression, type, descending]
, as described as follows:
expression is a Liquid template to generate a string to be used as sort key.
type (optional) is one of string
(default), number
and time
, which specifies how to evaluate expression for comparison.
descending (optional) is a boolean value to determine if comparison should be done in descending (reverse) order, which defaults to false
.
Sort keys listed earlier take precedence over ones listed later. For example, if you want to sort articles by the date and then by the author, specify [["{{date}}", "time"], "{{author}}"]
.
Sorting is done stably, so even if all events have the same set of sort key values the original order is retained. Also, a special Liquid variable _index_
is provided, which contains the zero-based index number of each event, which means you can exactly reverse the order of events by specifying [["{{_index_}}", "number", true]]
.
If the include_sort_info
option is set, each created event will have a sort_info
key whose value is a hash containing the following keys:
position
: 1-based index of each event after the sortcount
: Total number of events sortedIn this Agent, the default value for events_order
is [["{{date_published}}","time"],["{{last_updated}}","time"]]
.
The S3Agent can watch a bucket for changes or emit an event for every file in that bucket. When receiving events, it writes the data into a file on S3.
mode
must be present and either read
or write
, in read
mode the agent checks the S3 bucket for changed files, with write
it writes received events to a file in the bucket.
To use credentials for the access_key
and access_key_secret
use the liquid credential
tag like so {% credential name-of-credential %}
Select the region
in which the bucket was created.
When watch
is set to true
the S3Agent will watch the specified bucket
for changes. An event will be emitted for every detected change.
When watch
is set to false
the agent will emit an event for every file in the bucket on each sheduled run.
This agent only emits a ‘file pointer’, not the data inside the files, the following agents can consume the created events: PostAgent
, CsvAgent
, ReadFileAgent
. Read more about the concept in the wiki.
Specify the filename to use in filename
, Liquid interpolation is possible to change the name per event.
Use Liquid templating in data
to specify which part of the received event should be written.
The Scheduler Agent periodically takes an action on target Agents according to a user-defined schedule.
Set action
to one of the action types below:
run
: Target Agents are run at intervals, except for those disabled.
disable
: Target Agents are disabled (if not) at intervals.
enable
: Target Agents are enabled (if not) at intervals.
drop_pending_events
is set to true
, pending events will be cleared before the agent is enabled.Select Agents that you want to run periodically by this SchedulerAgent.
Set schedule
to a schedule specification in the cron format.
For example:
0 22 * * 1-5
: every day of the week at 22:00 (10pm)
*/10 8-11 * * *
: every 10 minutes from 8:00 to and not including 12:00
This variant has several extensions as explained below.
You can optionally specify a timezone (default: Pacific Time (US & Canada)
) after the day-of-week field using the labels in the tz database
0 22 * * 1-5 Europe/Paris
: every day of the week when it’s 22:00 in Paris
0 22 * * 1-5 Etc/GMT+2
: every day of the week when it’s 22:00 in GMT+2
You can optionally specify seconds before the minute field.
*/30 * * * * *
: every 30 secondsOnly multiples of fifteen are allowed as values for the seconds field, i.e. */15
, */30
, 15,45
etc.
L
signifies “last day of month” in day-of-month
.
0 22 L * *
: every month on the last day at 22:00You can use three letter names instead of numbers in the weekdays
field.
0 22 * * Sat,Sun
: every Saturday and Sunday, at 22:00You can specify “nth weekday of the month” like this.
0 22 * * Sun#1,Sun#2
: every first and second Sunday of the month, at 22:00
0 22 * * Sun#L1
: every last Sunday of the month, at 22:00
The Sentiment Agent generates good-bad
(psychological valence or happiness index), active-passive
(arousal), and strong-weak
(dominance) score. It will output a value between 1 and 9. It will only work on English content.
Make sure the content this agent is analyzing is of sufficient length to get respectable results.
Provide a JSONPath in content
field where content is residing and set expected_receive_period_in_days
to the maximum number of days you would allow to be passed between events being received by this agent.
The Shell Command Agent will execute commands on your local system, returning the output.
command
specifies the command (either a shell command line string or an array of command line arguments) to be executed, and path
will tell ShellCommandAgent in what directory to run this command. The content of stdin
will be fed to the command via the standard input.
expected_update_period_in_days
is used to determine if the Agent is working.
ShellCommandAgent can also act upon received events. When receiving an event, this Agent’s options can interpolate values from the incoming event.
For example, your command could be defined as {{cmd}}
, in which case the event’s cmd
property would be used.
The resulting event will contain the command
which was executed, the path
it was executed under, the exit_status
of the command, the errors
, and the actual output
. ShellCommandAgent will not log an error if the result implies that something went wrong.
If unbundle
is set to true, the command is run in a clean environment, outside of Huginn’s bundler context.
If suppress_on_failure
is set to true, no event is emitted when exit_status
is not zero.
If suppress_on_empty_output
is set to true, no event is emitted when output
is empty.
Warning: This type of Agent runs arbitrary commands on your system, and is currently disabled.
Only enable this Agent if you trust everyone using your Huginn installation.
You can enable this Agent in your .env file by setting ENABLE_INSECURE_AGENTS
to true
.
The Slack Agent lets you receive events and send notifications to Slack.
To get started, you will first need to configure an incoming webhook.
https://my.slack.com/services/new/incoming-webhook
, choose a default channel and add the integration.Your webhook URL will look like: https://hooks.slack.com/services/some/random/characters
Once the webhook has been configured, it can be used to post to other channels or direct to team members. To send a private message to team member, use their @username as the channel. Messages can be formatted using Liquid.
Finally, you can set a custom icon for this webhook in icon
, either as emoji or an URL to an image. Leaving this field blank will use the default icon for a webhook.
This agent instanciate a slack bot and send messages.
Generate a slack bot token here, and put into a credential called slack_bot_token
To send messages, just fill the options as a documented here
The bot needs to be in channel to send messages in it.
Agent for sending SMS from Huginn via Sms77.io.
Get an API key at Sms77 and you are ready to start sending!
Options:
* text
- The message you want to send (required)
* to
- recipient(s) separated by comma - phone number(s) or contact(s) (required)
from
- Sender number. Allowed value: A string of 11 alphanumeric or 16 numeric charactersdebug
- If activated no SMS will be sent or calculated Allowed values: 0, 1delay
- Date/time for time-delayed SMS: Allowed values: A UNIX timestamp or date with format yyyy-mm-dd hh:iino_reload
- Switch off reload lock. This lock prevents the sending of the same SMS (text, type and recipient alike) within 180 seconds Allowed values: 0, 1unicode
- For Cyrillic, Arabic etc characters. SMS length is then reduced to 70 characters. The API recognizes the coding automatically; this parameter enforces it Allowed values: 0, 1flash
- Send SMS as Flash SMS. These are displayed directly in the receiver’s display Allowed values: 0, 1udh
- Individual User Data Header of the SMS. If specified and parameter text contains hexcode, message gets sent as 8-bit binaryutf8
- Forces the detection as a UTF8 character set and overrides automatic recognition of the API Allowed values: 0, 1ttl
- Specifies the validity period of the SMS in milliseconds Allowed values: integer between 300000 and 86400000details
- Shows numerous details to the sent SMS. Handy for debugging Allowed values: 0, 1return_msg_id
- If this parameter is set, the ID of the SMS is output in the second line after the status code Allowed values: 0, 1label
- Custom label for whatever use. Allowed characters: a-z, A-Z, 0-9, .-_@json
- The output is more detailed in JSON format Allowed values: 0, 1performance_tracking
- Enable Performance Tracking for URLs found in the message text Allowed values: 0, 1foreign_id
- Custom tag to return in DLR callbacks etc. Max. 64 chars. Allowed characters: a-z, A-Z, 0-9, .-_@The Sms77.io Agent receives and collects events for dispatching Text2Voice phone calls to a given number.
Expects an event with key text
, message
, voice
or sms
with the text to send. Use the EventFormattingAgent
if lacks such a key.
Requires an API key from Sms77 for sending.
Options:
text
- The message you want to send (required)
to
- recipient phone number (required)
from
- Sender number. Expects a string with 11 alphanumeric or 16 numeric characters
xml
- Decides whether the given text is XML or not Allowed values: 0, 1
The StubHub Agent creates an event for a given StubHub Event.
It can be used to track how many tickets are available for the event and the minimum and maximum price. All that is required is that you paste in the url from the actual event, e.g. https://www.stubhub.com/outside-lands-music-festival-tickets/outside-lands-music-festival-3-day-pass-san-francisco-golden-gate-park-polo-fields-8-8-2014-9020701/
The Telegram Agent receives and collects events and sends them via Telegram.
It is assumed that events have either a text
, photo
, audio
, document
or video
key. You can use the EventFormattingAgent if your event does not provide these keys.
The value of text
key is sent as a plain text message. You can also tell Telegram how to parse the message with parse_mode
, set to either html
or markdown
.
The value of photo
, audio
, document
and video
keys should be a url whose contents will be sent to you.
Setup
auth_token
by creating a new bot.chat_id
from the dropdown.Options
caption
: caption for a media content (0-1024 characters)disable_notification
: send a message silently in a channeldisable_web_page_preview
: disable link previews for links in a text messagelong_message
: truncate (default) or split text messages and captions that exceed Telegram API limits. Markdown and HTML tags can’t span across messages and, if not opened or closed properly, will render as plain text.parse_mode
: parse policy of a text messageSee the official Telegram Bot API documentation for detailed info.
The Github notification agent fetches notifications and creates an event by notification.
changes_only
is only used to emit event about a status’ change.
expected_receive_period_in_days
is used to determine if the Agent is working. Set it to the maximum number of days
that you anticipate passing without this Agent receiving an incoming Event.
The Todoist Agent creates items on your Todoist.
To authenticate you need to either set api_token
or provide a credential named
todoist_api_token
to your Todoist API token. You can find it within the
Todoist web frontend from “Gear Menu” > Todoist Settings > Account tab.
Change content
to whatever the new Todoist item should tell. You can use liquid
templating to include parts from the incoming event in the new item.
Have a look at the Wiki
to learn more about liquid templating.
In order to set a due date provide a date_string
(which may contain all date string
features supported by Todoist).
project_id
is the ID of the project to add the item to. Leave blank for INBOX.
labels
is a comma-seperated list of label IDs (or blank for no labels).
prority
is an integer from 1 to 4. Where 1 means lowest (natural) priority and
4 highest. Defaults to natural priority (aka 1).
The Todoist Close Item Agent closes items on your Todoist.
To authenticate you need to either set api_token
or provide a credential named
todoist_api_token
to your Todoist API token. You can find it within the
Todoist web frontend from “Gear Menu” > Todoist Settings > Account tab.
Change id
to whatever the ID of the item you would want to be closed is. You
can also route query results from “Todoist Query Agent” to this agent and
interpolate it using {{ id }}
to close all items included in the search result.
The Todoist Query Agent allows to search items on your Todoist.
To authenticate you need to either set api_token
or provide a credential named
todoist_api_token
to your Todoist API token. You can find it within the
Todoist web frontend from “Gear Menu” > Todoist Settings > Account tab.
Change query
to the Todoist filter expression
you’d like to be carried out.
The mode
option allows to control what information is emitted. With the default value
of items
an event is emitted for every item that matches the search result. And consequently
no event is emitted if no items match the query.
With count
the agent always emits a single event, that just tells the number of matched items.
Add a Agent description here
Connects to the transport.opendata.ch API and checks currently available connections between two defined cities for the timestamp the request is sent.
The Trigger Agent will watch for a specific value in an Event payload.
The rules
array contains a mixture of strings and hashes.
A string rule is a Liquid template and counts as a match when it expands to true
.
A hash rule consists of the following keys: path
, value
, and type
.
The path
value is a dotted path through a hash in JSONPaths syntax. For simple events, this is usually just the name of the field you want, like ‘text’ for the text key of the event.
The type
can be one of regex
, !regex
, field<value
, field<=value
, field==value
, field!=value
, field>=value
, field>value
, and not in
and compares with the value
. Note that regex patterns are matched case insensitively. If you want case sensitive matching, prefix your pattern with (?-i)
.
In any type
including regex Liquid variables can be used normally. To search for just a word matching the concatenation of foo
and variable bar
would use value
of foo{{bar}}
. Note that note that starting/ending delimiters like /
or |
are not required for regex.
The value
can be a single value or an array of values. In the case of an array, all items must be strings, and if one or more values match, then the rule matches. Note: avoid using field!=value
with arrays, you should use not in
instead.
By default, all rules must match for the Agent to trigger. You can switch this so that only one rule must match by
setting must_match
to 1
.
The resulting Event will have a payload message of message
. You can use liquid templating in the `message, have a look at the Wiki for details.
Set keep_event
to true
if you’d like to re-emit the incoming event, optionally merged with ‘message’ when provided.
Set expected_receive_period_in_days
to the maximum amount of time that you’d expect to pass between Events being received by this Agent.
The Tumblr Likes Agent checks for liked Tumblr posts from a specific blog.
To be able to use this Agent you need to authenticate with Tumblr in the Services section first.
Required fields:
blog_name
The Tumblr URL you’re querying (e.g. “staff.tumblr.com”)
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
The Tumblr Publish Agent publishes Tumblr posts from the events it receives.
To be able to use this Agent you need to authenticate with Tumblr in the Services section first.
Required fields:
blog_name
Your Tumblr URL (e.g. “mustardhamsters.tumblr.com”)
post_type
One of [text, photo, quote, link, chat, audio, video, reblog]
You may leave any of the following optional fields blank. Including a field not allowed for the specified post_type
will cause a failure.
Any post type
state
published, draft, queue, privatetags
Comma-separated tags for this posttweet
off, text for tweetdate
GMT date and time of the post as a stringformat
html, markdownslug
short text summary at end of the post URLText title
body
Photo caption
link
source
Quote quote
source
Link title
url
description
Chat title
conversation
Audio caption
external_url
Video caption
embed
Reblog id
reblog_key
comment
Full information on field options
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
The Twilio Agent receives and collects events and sends them via text message (up to 160 characters) or gives you a call when scheduled.
It is assumed that events have a message
, text
, or sms
key, the value of which is sent as the content of the text message/call. You can use the EventFormattingAgent if your event does not provide these keys.
Set receiver_cell
to the number to receive text messages/call and sender_cell
to the number sending them.
expected_receive_period_in_days
is maximum number of days that you would expect to pass between events being received by this agent.
If you would like to receive calls, set receive_call
to true
. In this case, server_url
must be set to the URL of your
Huginn installation (probably “https://”), which must be web-accessible. Be sure to set http/https correctly.
The Twilio Receive Text Agent receives text messages from Twilio and emits them as events.
In order to create events with this agent, configure Twilio to send POST requests to:
https:///users/1/web_requests/:id/sms-endpoint
The placeholder symbols above will be replaced by their values once the agent is saved.
Options:
server_url
must be set to the URL of your
Huginn installation (probably “https://”), which must be web-accessible. Be sure to set http/https correctly.
account_sid
and auth_token
are your Twilio account credentials. auth_token
must be the primary auth token for your Twilio accout.
If reply_text
is set, it’s contents will be sent back as a confirmation text.
expected_receive_period_in_days
- How often you expect to receive events this way. Used to determine if the agent is working.
The Twitter Action Agent is able to retweet or favorite tweets from the events it receives.
It expects to consume events generated by twitter agents where the payload is a hash of tweet information. The existing TwitterStreamAgent is one example of a valid event producer for this Agent.
To be able to use this Agent you need to authenticate with Twitter in the Services section first.
Set expected_receive_period_in_days
to the maximum amount of time that you’d expect to pass between Events being received by this Agent.
Set retweet
to either true or false.
Set favorite
to either true or false.
Set emit_error_events
to true to emit an Event when the action failed, otherwise the action will be retried.
The Twitter Favorites List Agent follows the favorites list of a specified Twitter user.
To be able to use this Agent you need to authenticate with Twitter in the Services section first.
You must also provide the username
of the Twitter user, number
of latest tweets to monitor and `history’ as number of tweets that will be held in memory.
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
Set starting_at
to the date/time (eg. Mon Jun 02 00:38:12 +0000 2014
) you want to start receiving tweets from (default: agent’s created_at
)
The Twitter Publish Agent publishes tweets from the events it receives.
To be able to use this Agent you need to authenticate with Twitter in the Services section first.
You must also specify a message
parameter, you can use Liquid to format the message.
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
The Twitter Search Agent performs and emits the results of a specified Twitter search.
If you want realtime data from Twitter about frequent terms, you should definitely use the Twitter Stream Agent instead.
To be able to use this Agent you need to authenticate with Twitter in the Services section first.
You must provide the desired search
.
Set result_type
to specify which type of search results you would prefer to receive. Options are “mixed”, “recent”, and “popular”. (default: mixed
)
Set max_results
to limit the amount of results to retrieve per run(default: 500
. The API rate limit is ~18,000 per 15 minutes. Click here to learn more about rate limits.
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
Set starting_at
to the date/time (eg. Mon Jun 02 00:38:12 +0000 2014
) you want to start receiving tweets from (default: agent’s created_at
)
The Twitter Stream Agent follows the Twitter stream in real time, watching for certain keywords, or filters, that you provide.
To follow the Twitter stream, provide an array of filters
. Multiple words in a filter must all show up in a tweet, but are independent of order.
If you provide an array instead of a filter, the first entry will be considered primary and any additional values will be treated as aliases.
To be able to use this Agent you need to authenticate with Twitter in the Services section first.
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
generate
should be either events
or counts
. If set to counts
, it will output event summaries whenever the Agent is scheduled.
The Twitter User Agent either follows the timeline of a specific Twitter user or follows your own home timeline including both your tweets and tweets from people whom you are following.
To be able to use this Agent you need to authenticate with Twitter in the Services section first.
To follow a Twitter user set choose_home_time_line
to false
and provide the username
.
To follow your own home timeline set choose_home_time_line
to true
.
Set include_retweets
to false
to not include retweets (default: true
)
Set exclude_replies
to true
to exclude replies (default: false
)
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
Set starting_at
to the date/time (eg. Mon Jun 02 00:38:12 +0000 2014
) you want to start receiving tweets from (default: agent’s created_at
)
The User Location Agent creates events based on WebHook POSTS that contain a latitude
and longitude
. You can use the POSTLocation or PostGPS iOS app to post your location to https:///users/1/update_location/:secret
where :secret
is specified in your options.
If you want to only keep more precise locations, set max_accuracy
to the upper bound, in meters. The default name for this field is accuracy
, but you can change this by setting a value for accuracy_field
.
If you want to require a certain distance traveled, set min_distance
to the minimum distance, in meters. Note that GPS readings and the measurement itself aren’t exact, so don’t rely on this for precision filtering.
To view the locations on a map, set api_key
to your Google Maps JavaScript API key.
The Weather Agent creates an event for the day’s weather at a given location
.
You also must select when you would like to get the weather forecast for using the which_day
option, where the number 1 represents today, 2 represents tomorrow and so on. Weather forecast inforation is only returned for at most one week at a time.
The weather forecast information is provided by Dark Sky.
The location
must be a comma-separated string of map co-ordinates (longitude, latitude). For example, San Francisco would be 37.7771,-122.4196
.
You must set up an API key for Dark Sky in order to use this Agent.
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
The Webhook Agent will create events by receiving webhooks from any source. In order to create events with this agent, make a POST request to:
https:///users/1/web_requests/:id/:secret
The placeholder symbols above will be replaced by their values once the agent is saved.
Options:
secret
- A token that the host will provide for authentication.expected_receive_period_in_days
- How often you expect to receive
events this way. Used to determine if the agent is working.payload_path
- JSONPath of the attribute in the POST body to be
used as the Event payload. Set to .
to return the entire message.
If payload_path
points to an array, Events will be created for each element.event_headers
- Comma-separated list of HTTP headers your agent will include in the payload.event_headers_key
- The key to use to store all the headers receivedverbs
- Comma-separated list of http verbs your agent will accept.
For example, “post,get” will enable POST and GET requests. Defaults
to “post”.response
- The response message to the request. Defaults to ‘Event Created’.response_headers
- An object with any custom response headers. (example: {"Access-Control-Allow-Origin": "*"}
)code
- The response code to the request. Defaults to ‘201’. If the code is ‘301’ or ‘302’ the request will automatically be redirected to the url defined in “response”.recaptcha_secret
- Setting this to a reCAPTCHA “secret” key makes your agent verify incoming requests with reCAPTCHA. Don’t forget to embed a reCAPTCHA snippet including your “site” key in the originating form(s).recaptcha_send_remote_addr
- Set this to true if your server is properly configured to set REMOTE_ADDR to the IP address of each visitor (instead of that of a proxy server).score_threshold
- Setting this when using reCAPTCHA v3 to define the treshold when a submission is verified. Defaults to 0.5The Website Agent scrapes a website, XML document, or JSON feed and creates Events based on the results.
Specify a url
and select a mode
for when to create Events based on the scraped data, either all
, on_change
, or merge
(if fetching based on an Event, see below).
The url
option can be a single url, or an array of urls (for example, for multiple pages with the exact same structure but different content to scrape).
The WebsiteAgent can also scrape based on incoming events.
url_from_event
option to a Liquid template to generate the url to access based on the Event. (To fetch the url in the Event’s url
key, for example, set url_from_event
to {{ url }}
.)data_from_event
to a Liquid template to use data directly without fetching any URL. (For example, set it to {{ html }}
to use HTML contained in the html
key of the incoming Event.)merge
for the mode
option, Huginn will retain the old payload and update it with new values.The type
value can be xml
, html
, json
, or text
.
To tell the Agent how to parse the content, specify extract
as a hash with keys naming the extractions and values of hashes.
Note that for all of the formats, whatever you extract MUST have the same number of matches for each extractor except when it has repeat
set to true. E.g., if you’re extracting rows, all extractors must match all rows. For generating CSS selectors, something like SelectorGadget may be helpful.
For extractors with hidden
set to true, they will be excluded from the payloads of events created by the Agent, but can be used and interpolated in the template
option explained below.
For extractors with repeat
set to true, their first matches will be included in all extracts. This is useful such as when you want to include the title of a page in all events created from the page.
When parsing HTML or XML, these sub-hashes specify how each extraction should be done. The Agent first selects a node set from the document for each extraction key by evaluating either a CSS selector in css
or an XPath expression in xpath
. It then evaluates an XPath expression in value
(default: .
) on each node in the node set, converting the result into a string. Here’s an example:
"extract": {
"url": { "css": "#comic img", "value": "@src" },
"title": { "css": "#comic img", "value": "@title" },
"body_text": { "css": "div.main", "value": "string(.)" },
"page_title": { "css": "title", "value": "string(.)", "repeat": true }
} or
"extract": {
"url": { "xpath": "//*[@class="blog-item"]/a/@href", "value": "."
"title": { "xpath": "//*[@class="blog-item"]/a", "value": "normalize-space(.)" },
"description": { "xpath": "//*[@class="blog-item"]/div[0]", "value": "string(.)" }
}
“@attr” is the XPath expression to extract the value of an attribute named attr from a node (such as “@href” from a hyperlink), and string(.)
gives a string with all the enclosed text nodes concatenated without entity escaping (such as &
). To extract the innerHTML, use ./node()
; and to extract the outer HTML, use .
.
You can also use XPath functions like normalize-space
to strip and squeeze whitespace, substring-after
to extract part of a text, and translate
to remove commas from formatted numbers, etc. Instead of passing string(.)
to these functions, you can just pass .
like normalize-space(.)
and translate(., ',', '')
.
Beware that when parsing an XML document (i.e. type
is xml
) using xpath
expressions, all namespaces are stripped from the document unless the top-level option use_namespaces
is set to true
.
For extraction with array
set to true, all matches will be extracted into an array. This is useful when extracting list elements or multiple parts of a website that can only be matched with the same selector.
When parsing JSON, these sub-hashes specify JSONPaths to the values that you care about.
Sample incoming event:
{ "results": {
"data": [
{
"title": "Lorem ipsum 1",
"description": "Aliquam pharetra leo ipsum."
"price": 8.95
},
{
"title": "Lorem ipsum 2",
"description": "Suspendisse a pulvinar lacus."
"price": 12.99
},
{
"title": "Lorem ipsum 3",
"description": "Praesent ac arcu tellus."
"price": 8.99
}
]
}
}
Sample rule:
"extract": {
"title": { "path": "results.data[*].title" },
"description": { "path": "results.data[*].description" }
}
In this example the *
wildcard character makes the parser to iterate through all items of the data
array. Three events will be created as a result.
Sample outgoing events:
[
{
"title": "Lorem ipsum 1",
"description": "Aliquam pharetra leo ipsum."
},
{
"title": "Lorem ipsum 2",
"description": "Suspendisse a pulvinar lacus."
},
{
"title": "Lorem ipsum 3",
"description": "Praesent ac arcu tellus."
}
]
The extract
option can be skipped for the JSON type, causing the full JSON response to be returned.
When parsing text, each sub-hash should contain a regexp
and index
. Output text is matched against the regular expression repeatedly from the beginning through to the end, collecting a captured group specified by index
in each match. Each index should be either an integer or a string name which corresponds to (?<name>...)
. For example, to parse lines of word: definition
, the following should work:
"extract": {
"word": { "regexp": "^(.+?): (.+)$", "index": 1 },
"definition": { "regexp": "^(.+?): (.+)$", "index": 2 }
}
Or if you prefer names to numbers for index:
"extract": {
"word": { "regexp": "^(?<word>.+?): (?<definition>.+)$", "index": "word" },
"definition": { "regexp": "^(?<word>.+?): (?<definition>.+)$", "index": "definition" }
}
To extract the whole content as one event:
"extract": {
"content": { "regexp": "\A(?m:.)*\z", "index": 0 }
}
Beware that .
does not match the newline character (LF) unless the m
flag is in effect, and ^
/$
basically match every line beginning/end. See this document to learn the regular expression variant used in this service.
Can be configured to use HTTP basic auth by including the basic_auth
parameter with "username:password"
, or ["username", "password"]
.
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent. This is only used to set the “working” status.
Set uniqueness_look_back
to limit the number of events checked for uniqueness (typically for performance). This defaults to the larger of 200 or 3x the number of detected received results.
Set force_encoding
to an encoding name (such as UTF-8
and ISO-8859-1
) if the website is known to respond with a missing, invalid, or wrong charset in the Content-Type header. Below are the steps used by Huginn to detect the encoding of fetched content:
force_encoding
is given, that value is used.type
is html
or xml
, Huginn checks for the presence of a BOM, XML declaration with attribute “encoding”, or an HTML meta tag with charset information, and uses that if found.Set user_agent
to a custom User-Agent name if the website does not like the default value (Huginn - https://github.com/huginn/huginn
).
The headers
field is optional. When present, it should be a hash of headers to send with the request.
Set disable_ssl_verification
to true
to disable ssl verification.
Set unzip
to gzip
to inflate the resource using gzip.
Set http_success_codes
to an array of status codes (e.g., [404, 422]
) to treat HTTP response codes beyond 200 as successes.
If a template
option is given, its value must be a hash, whose key-value pairs are interpolated after extraction for each iteration and merged with the payload. In the template, keys of extracted data can be interpolated, and some additional variables are also available as explained in the next section. For example:
"template": {
"url": "{{ url | to_uri: _response_.url }}",
"description": "{{ body_text }}",
"last_modified": "{{ _response_.headers.Last-Modified | date: '%FT%T' }}"
}
In the on_change
mode, change is detected based on the resulted event payload after applying this option. If you want to add some keys to each event but ignore any change in them, set mode
to all
and put a DeDuplicationAgent downstream.
In Liquid templating, the following variables are available:
_url_
: The URL specified to fetch the content from. When parsing data_from_event
, this is not set.
_response_
: A response object with the following keys:
status
: HTTP status as integer. (Almost always 200) When parsing data_from_event
, this is set to the value of the status
key in the incoming Event, if it is a number or a string convertible to an integer.
headers
: Response headers; for example, {{ _response_.headers.Content-Type }}
expands to the value of the Content-Type header. Keys are insensitive to cases and -/_. When parsing data_from_event
, this is constructed from the value of the headers
key in the incoming Event, if it is a hash.
url
: The final URL of the fetched page, following redirects. When parsing data_from_event
, this is set to the value of the url
key in the incoming Event. Using this in the template
option, you can resolve relative URLs extracted from a document like {{ link | to_uri: _response_.url }}
and {{ content | rebase_hrefs: _response_.url }}
.
To specify the order of events created in each run, set events_order
to an array of sort keys, each of which looks like either expression
or [expression, type, descending]
, as described as follows:
expression is a Liquid template to generate a string to be used as sort key.
type (optional) is one of string
(default), number
and time
, which specifies how to evaluate expression for comparison.
descending (optional) is a boolean value to determine if comparison should be done in descending (reverse) order, which defaults to false
.
Sort keys listed earlier take precedence over ones listed later. For example, if you want to sort articles by the date and then by the author, specify [["{{date}}", "time"], "{{author}}"]
.
Sorting is done stably, so even if all events have the same set of sort key values the original order is retained. Also, a special Liquid variable _index_
is provided, which contains the zero-based index number of each event, which means you can exactly reverse the order of events by specifying [["{{_index_}}", "number", true]]
.
If the include_sort_info
option is set, each created event will have a sort_info
key whose value is a hash containing the following keys:
position
: 1-based index of each event after the sortcount
: Total number of events sortedThe WebsiteMetadata Agent extracts metadata from HTML. It supports schema.org microdata, embedded JSON-LD and the common meta tag attributes.
data
HTML to use in the extraction process, use Liquid formatting to select data from incoming events.
url
optionally set the source URL of the provided HTML (without an URL schema.org links can not be extracted properly)
result_key
sets the key which contains the the extracted information.
merge
set to true to retain the received payload and update it with the extracted result
Liquid formatting can be used in all options.
The Weibo Publish Agent publishes tweets from the events it receives.
You must first set up a Weibo app and generate an access_token
for the user that will be used for posting status updates.
You’ll use that access_token
, along with the app_key
and app_secret
for your Weibo app. You must also include the Weibo User ID (as uid
) of the person to publish as.
You must also specify a message_path
parameter: a JSONPaths to the value to tweet.
You can also specify a pic_path
parameter: a JSONPaths to the picture url to tweet along.
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
The Weibo User Agent follows the timeline of a specified Weibo user. It uses this endpoint: http://open.weibo.com/wiki/2/statuses/user_timeline/en
You must first set up a Weibo app and generate an acess_token
to authenticate with. Provide that, along with the app_key
and app_secret
for your Weibo app in the options.
Specify the uid
of the Weibo user whose timeline you want to watch.
Set expected_update_period_in_days
to the maximum amount of time that you’d expect to pass between Events being created by this Agent.
The wit.ai
agent receives events, sends a text query to your wit.ai
instance and generates outcome events.
Fill in Server Access Token
of your wit.ai
instance. Use Liquid to fill query field.
expected_receive_period_in_days
is the expected number of days by which agent should receive events. It helps in determining if the agent is working.
The WunderlistAgent creates new Wunderlist tasks based on the incoming event.
omniauth-wunderlist
gem in your Gemfile
and set WUNDERLIST_OAUTH_KEY
and WUNDERLIST_OAUTH_SECRET
in your environment to use this AgentTo be able to use this Agent you need to authenticate with Wunderlist in the Services section first.
Create Invoices in Xero based on incoming Events.
See this Agent’s GitHub page for instructions on setting up this Agent to access your Xero data.
All options support Liquid templating.
Options
expected_receive_period_in_days
- How often you expect data to be received by this Agent from other Agents.due_in_days
- The number of days from now when the invoice is due.contact_name
, contact_phone_number
, contact_email
, contact_address_line_1
, contact_address_line_2
, contact_address_city
, contact_address_region
, contact_address_country
, and contact_address_post_code
allow setting details for a new contact.item_path
if you’d like to create multiple invoices, one per record at that JSONPath.item_description
, item_account_code
, and item_amount
allow configuring of invoice details and can contain Liquid templating, allowing you to make them dynamic based on Event input.