Hemppa - generic modular Matrix bot

This bot is meant to be super easy platform to write Matrix bot functionality in Python. It uses matrix-nio library https://github.com/poljar/matrix-nio/ for Matrix communications.

Zero configuration except Matrix account info is needed. Everything else can be done with bot commands.

Type !help in room with this bot running to list active modules.

If you don't want some modules, just delete the files from modules directory or disable them with !bot disable command.

End-to-end encryption is currently not supported by bot but should be doable. Bot won't respond to commands in e2ee rooms. PR for enabling e2ee is welcome!

Support room: #hemppa:hacklab.fi - https://matrix.to/#/#hemppa:hacklab.fi

Hint: RSS Bridge

RSS Bridge is awesome project that creates RSS feeds for sites that don't have them: https://github.com/RSS-Bridge/rss-bridge

If you want bot to notify on new posts on a service, check out if RSS Bridge supports it! You can use the stock Matrix RSS bot to subscribe to feeds created by RSS bridge.

Module list

Bot

Bot management commands.

!bot status - print bot status information
!bot ping - print the ping time between the server and the bot
!bot version - print version and uptime of the bot
!bot stats - show statistics on matrix users seen by bot

The following must be done as the bot owner:

!bot enable [module] - enable module
!bot disable [module] - disable module
!bot quit - quit the bot process
!bot reload - reload all bot modules
!bot export - export all bot settings as json
!bot export [module] - export a module's settings as json
!bot import [json object] - Update all bot settings from json
!bot import [module] [json object] - Update a module's settings from json
!bot import [module] [key ...] [json object] - Update a sub-object in a module from json
- Example: !bot import alias aliases {"osm": "loc", "sh": "cmd"}
!bot logs [module] ([count]) - Print the [count] most recent messages the given module has reported
!bot uricache (view|clean|clear) - View the uri cache, or clear it. The uri cache prevents the bot from uploading a blob from a url repeatedly
!bot leave - ask bot to leave this room
!bot modules - list all modules including enabled status
!bot rooms - list rooms the bot is on

Help

Prints help on existing modules.

!help - get short help for all currently-enabled modules
!help [module] - get long help for the given module, or short help if unavailable
!sethelp msg (on|yes|1) - Configure !help to respond to !help requests via a direct message, instead of in the current room (Must be done as bot owner)

Alias

Add or remove aliases for a module.

!alias list - List all aliases
!alias add [newname] [module] - Define an alias for [module] (Must be done as bot owner)
!alias remove [name] - Remove [name] as an alias (Must be done as bot owner)

Echo

Simple example module that just echoes what user said.

!echo Hello, world!

Metar

Aviation weather metar service access.

!metar eftp

TAF

Aviation weather TAF service access.

!taf eftp

NOTAM

Aviation NOTAM data access. Currently supports only Finnish airports - implement other countries where data is available.

!notam efjm

Teamup

Can access Teamup ( https://teamup.com/ ) calendar. Teamup has nice API and is easier to set up than Google so prefer it if possible. This bot polls the calendar every 5 minutes and notifies the room of any changes.

Howto:

Create a calendar in Teamup https://teamup.com/
Get api key at https://teamup.com/api-keys/request
!teamup apikey [your api key]
!teamup add [calendar id]

Commands:

!teamup apikey [apikey] - set api key (Must be done as bot owner)
!teamup - list upcoming events in calendar
!teamup add [calendar id] - add calendar to this room (Must be done as room admin)
!teamup del [calendar id] - delete calendar from this room (Must be done as room admin)
!teamup list - list calendars in this room
!teamup poll - poll now for changes (Must be done as bot owner)

Google Calendar

Can access a google calendar in a room. This is a bit pain to set up, sorry.

To set up, you'll need to generate oauth2 credentials.json file - see https://console.developers.google.com/apis/credentials

Run the bot on local machine as OAuth2 wants to open localhost url in your browser. I haven't found out an easy way to do this on server.

There is a empty credentials.json file in the bot directory. Replace it with yours. When credentials.json is present, you must authenticate the bot to access calendar. There will be a link in console like this:

Please visit this URL to authorize this application: https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=907....

Open the link and authenticate as needed. A new file token.pickle will be created in the directory and bot will read it in future. Save the token.pickle and ship it with the bot to your server.

Now the bot should be usable.

Use !googlecal add [calendar id] to add new calendar to a room. The bot lists availble calendar ID's on startup and you can find them in google calendar.

Commands:

!googlecal - Show next 10 events in calendar
!googlecal today - Show today's events
!googlecal add [calendar id] - Add new calendar to room (Must be done as room admin)
!googlecal del [calendar id] - Delete calendar from room (Must be done as room admin)
!googlecal list - List calendars in this room

NOTE: disabled by default

Cron

Can schedule things to be done.

Commands:

!cron daily [hour] [command] - Run command on start of hour (Must be done as room admin)
!cron list - List commands in this room
!cron clear - Clear command s in this room (Must be done as room admin)
!cron time - Print the current datetime and time zone that the cron command will use (time zone set using the TZ environment variable)

Examples:

!cron daily 19 "It is now 19 o clock"
!cron daily 8 "!googlecal today"

Location

Can search OpenStreetMaps for locations and send Matrix location events from them. Translates Matrix location events into OSM links.

Commands:

!loc [location] - search for location
!loc enable - enable location to link translation in this room (must be done as room admin)
!loc disable - disable location to link translation in this room (must be done as room admin)

Example:

!loc Tampere

Room

This module is for interacting with the room that the commands are being executed on.

!room servers Lists the servers in the room
!room joined Responds with the joined members count
!room banned Lists the banned users and their provided reason
!room kicked Lists the kicked users and their provided reason
!room state [event type] [optional state key] Gets a state event with given event type and optional state key
!room tombstone [target] Creates a tombstone event pointing to target room. Target room can be alias (starting with #) or id (starting with !). User must be admin in the room.

Note on tombstone: If using alias, bot must be present in target room. This is the preferred way. If using id, make sure it's correct, as it's not validated! Tombstoning requires power level for room upgrade. Make sure bot has it in the room.

Welcome to Room

When configured in a room, the bot will monitor a room for new users and send new users a welcome message 1:1. It will then notify bot owners of the new user. It will also, optionally, notify of user departure.

Commands:

!welcome_room welcome_message [message] Sets the welcome message, along with other variables needed to detect new users.
!welcome_room notify_departure [True/False] Sets whether bot owners will be notified of departure from room. Defaults to False.
!welcome_room settings Shows the current settings for the welcome_room module.

Welcome to Server

As a server admin, the bot will monitor new user creation on the server and send the welcome message to new users 1:1. It will then notify bot owners of the new user.

Commands:

!welcome_server welcome_message [message] Sets the welcome message, along with other variables needed to detect new users.
!welcome_server settings Shows current settings for the welcome_server module

Slow polling services

These have the same usage - you can add one or more accounts to a room and bot polls the accounts. New posts are sent to room. Polls only randomly every 30 to 60 minutes to keep traffic at minimum.

Commands:

Prefix with selected service, for example "!ig add accountname" or "!teamup list"

add [accountname] - Add account to this room (Must be done as room admin)
del [accountname] - Delete account from room (Must be done as room admin)
list - List accounts in room
poll - Poll for new items (Must be done as bot owner)
clear - Clear all accounts from this room (Must be done as room admin)
debug - Show some debug information for accounts in room

Instagram

Polls instagram account(s). Uses instagram scraper library without any authentication or api key.

See: https://github.com/realsirjoe/instagram-scraper/

NOTE: disabled by default

Matrix Messaging API (mxma)

This is a simple API to ask bot to send messages in Matrix using JSON file from external service.

You'll need an API endpoint (webserver) that contains a message queue. It must respond with following JSON to a HTTP GET request:

{
   "messages":[
      {
         "to": "@example:matrix.org",
         "title": "Room Title",
         "message": "Hello from Hemppa"
      },
      {
         "to": "@another:matrix.user",
         "title": "Room 2 Title",
         "message": "Second message"
      }
   ]
}

Hemppa

Install / Use

README

Hemppa - generic modular Matrix bot

Hint: RSS Bridge

Module list

Bot

Help

Alias

Echo

Metar

TAF

NOTAM

Teamup

Google Calendar

Cron

Location

Room

Welcome to Room

Welcome to Server

Slow polling services

Instagram

Matrix Messaging API (mxma)