Huginn agent for retrieving sane ACUMEN invoice data.
The following outlines the available options in this agent
status: 200: Indicates a true success. The agent has output the full
range of expected data.
status: 206: Indicates a partial success. The products within the bundle
are vaild, but the bundle may be missing products that were somehow invalid.
status: 500: Indicates a processing error. This may represent a complete
process failure, but may also be issued in parallel to a 202 payload.
Because this agent receives an array of Order Codes as input, errors will be issued in such a way that product processing can recover when possible. Errors that occur within a specific product bundle will emit an error event, but the agent will then move forward processing the next bundle.
For example, if this agent receives two products as input (A and B), and we fail to
load the Inv_Product record for product A, the agent would emit an error payload of:
{
status: 500,
scope: 'Fetch Inv_Product Data',
message: 'Failed to lookup Inv_Product record for Product A',
data: { product_id: 123 },
trace: [ ... ]
}
The goal of this approach is to ensure the agent outputs as much data as reasonably possible with each execution. If there is an error in the Paperback version of a title, that shouldn’t prevent this agent from returning the Hardcover version.
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 pathThe 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.5decimal_difference eg. Previous value was 5.5, new value is 15.2. Difference is 9.7integer_difference eg. Previous value was 50, new value is 40. Difference is -10decimal_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"
}
The File URL agent takes a url and emits an event with a file_pointer. Optionally, you can merge
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:
subjectbody
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)
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 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.
Takes a list of URLs, downloads them and then posts them as files to the described mattermost server, team, and channel. If message is defined the files are posted with the given message.
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: 1000ms)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 bodytitle, body, and urlname, and addressIn 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: 30expire - Required for emergency priority - Specifies how many seconds your notification will continue to be retried for (every retry seconds). Maximum value: 86400html - 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 Get Participants Agent takes in an event with a conversation_sid or ConversationSid key and populates a Participants array with the participant phone numbers in the conversation.
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 include_retweets to true to not include retweets (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.
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.