Automations and Bots

If you want to automatically generate messages in a Matrix room, the API does not work directly due to SSO authentication. Instead, you can use the Academiccloud Bot instance for this purpose.

There are many possible use cases, such as:

  • Automated welcome messages for new room members
  • Creating toots on Mastodon
  • Automatic reminders for scheduled events
  • Notifications for changes in software repositories
  • Automatic alerts for disruptions in web services

Depending on the use case, the so-called hookshot user can be added to a room with the necessary permissions. This user can then be used in a few simple steps for RSS feeds, GitLab events, or webhooks.

If you need a more general solution to respond to certain room events (e.g. a user joining), a bot account can be created. This bot can send messages via the Client-Server API, and messages will appear in the room as coming from the bot.

Hookshot-User

To use hookshot, you must invite the hookshot user @hookshot:gwdg.de from the main instance into a room and grant it power level Moderator. After that, you can subscribe to an RSS feed or create a new webhook with the following chat messages:

!hookshot feed <url>
bzw.
!hookshot webhook <kreativerName>

When creating a webhook, the necessary details (token/URL) will be sent via direct message from the hookshot user.

To send a message via the webhook, you can use:

curl -X PUT https://hook.matrix.gwdg.de/webhook/ffffff-fffff-ffff-ffff-ffffffffffff -H "Content-Type: application/json" -d '{"text": "The answer is 42."}'

To see all available commands, use:

!hookshot help

For more details, check the hookshot bot documentation.

Bot-User

For maximum flexibility, bot accounts can be used. These accounts exist on a separate Matrix instance, meaning their home server is always bot.academiccloud.de. The steps for creating a bot-account are:

  1. Open a support-ticket to request the necessary right to create bot accounts.
  2. Open “Application Credentials” on id.academiccloud.de and authenticate with your multi-faktor-authentication.
  3. In the entry “Matrix Bot” click on “add”, fill in the required data and klick “save”.
  4. A uid and a password will be generated. You can use the uid as username (in the API it is called localpart) for the bot, eg. uid uXXXXX results in in user-id @uXXXXX:bot.academiccloud.de.
  5. Using these credentials you can now create an access_token, that can be used to authenticate against the matrix client-server api. The available endpoints are documented in the spec.

On the Client-Server API page, you can find minimal code examples and references to useful clients.

If you do not want to directly use the Client-Server API, there are also some tools that simplify this. You may consider one of the following: