Adapters

Adapters are the backend of marvin. The exchangeable part that talks to the chat service itself.

Adapters are not yet exchangeable at runtime. The bot application is compiled against one adapter.

Adapter polymorphism

The capabilties required of an adapter is defined via the typeclass IsAdapter in Marvin.Adapter. Therefore you may define generic scripts which will work with any adapter using just the IsAdapter constraint in the script initializer type signature.

import Marvin

script :: IsAdapter a => ScriptInit a
script = defineScript "name" $ do ...

Or if you need capabilities specific to some adapter you can reference the adapter type directly.

import Marvin
import Marvin.Adapter.Slack.RTM

script :: ScriptInit (Slack RTM)
script = defineScript "name" $ do ...

Users can define their own adapters of course but are strongly encouraged to release generic adapters publicly or contribute them to marvin.

Shell

Quick info

Adapter id shell
Module Marvin.Adapter.Shell
Type ShellAdapter

✅ Supports `files`_

The simplest of all adapters, the shell adapter is used mostly for testing purposes.

The adapter id (for including it via the preprocessor) is “shell”. To wire manually import ShellAdapter from Marvin.Adapter.Shell.

It is recommended to run a shell instance of marvin with stderr piped to a file so that it does not interfere with your interactions with marvin.

The shell adapter supports a persistent history by specifying adapters.shell.history-file in your config.

Configuration keys

Name Type Necessity Description
history-file String optional If set the history of entered commands will be persisted here

Slack

For both of the following adapters you’ll have to create a new bot user for your slack team.

Also for both of the following adapters you’ll have to invite your bot to any channel in which it should be active (in slack) using /invite <botname>.

Channel references (for instance for enterIn and messageChannel) for this adapter use the actual channel name without the #. For instance the channel #random is referenced only with the string random.

✅ Supports `files`_

Real Time Messaging API

Quick info

Adapter id slack-rtm
Module Marvin.Adapter.Slack.RTM
Type SlackAdapter RTM

The adapter for the slack real time messaging api is currently the best supported adapter.

It works by opening a websocket to the slack servers from which it recieves events in real time.

The adapter id is “slack-rtm”. For manual wiring you’ll need the (SlackAdapter RTM) data structure from Marvin.Adapter.Slack.RTM.

Configuration keys

Name Type Necessity Description
token String required Authentication token for the slack API

Events API

Quick info

Adapter id slack-events
Module Marvin.Adapter.Slack.EventsAPI
Type SlackAdapter EventsAPI

This adapter creates a server, which listens for events from the slack Events API.

In addition to configuring marvin for this adapter you’ll also have tell slack the url for this bots server when configuring the bot.

The adapter id is “slack-rtm”. For manual wiring you’ll need the (SlackAdapter RTM) data structure from Marvin.Adapter.Slack.RTM.

Configuration keys

Name Type Necessity Description
token String required Authentication token for the slack API
use-tls Bool optional Whether to use TLS encryption, defaults to true
certfile String required if TLS is used Path to the TLS certificate
keyfile String required if TLS is used Path to the TLS key
port Int optional Port on which to run the server

Important

This adapter is not very well tested yet, please report any issues you encounter here.

Telegram

Both of the following adapters require you to create and register a telegram bot

<<<<<<< Updated upstream .. admonition:: Caveats

In telegram file size for remote files is optional. Since the marvin adapter class requires a size field this field will be negative if there was no size present on the file.

Additionally since there is per default no url property the field will always be Nothing and setting it is a no-op.

Poll

Quick info

Adapter id telegram-poll
Module Marvin.Adapter.Telegram.Poll
Type TelegramAdapter Poll

The telegram poll adapter sends long running http requests to the telegram servers to recieve events in near real time.

A unique trait of this adapter is the polling-timeout configuration key, which governs how long at maximum the polling requests may be kept open if no new event has arrived.

Configuration keys

Name Type Necessity Description
token String required Authentication token for the Telegram API
polling-timeout Int optional Timeout for the polling requests (seconds) defaults to 120

Important

This adapter is not very well tested yet, please report any issues you encounter here.

Push

Quick info

Adapter id telegram-push
Module Marvin.Adapter.Telegram.Push
Type TelegramAdapter Push

The telegram push adapter creates a server and registers a webhook with telegram to receive event updates.

Configuration keys

Name Type Necessity Description
token String required Authentication token for the slack API
url String required URL on which this server runs
use-tls Bool optional Whether to use TLS encryption, defaults to true
certfile String required if TLS is used Path to the TLS certificate
keyfile String required if TLS is used Path to the TLS key
port Int optional Port on which to run the server

Important

This adapter is not very well tested yet, please report any issues you encounter here.

IRC

Quick info

Adapter id irc
Module Marvin.Adapter.IRC
Type IRCAdapter

The irc adapter connects to your IRC server via the irc-conduit library.

Configuration keys

Name Type Necessity Description
host String required Url for the IRC server
port Int reqired Port for the irc server

Command and message events

  • All direct messages (privmsg) to the bot are interpreted as a command, and the contents of the message is passed to the handlers such as respond.
  • Messages in a channel, which are directed at the bot are also interpreted as commands.
  • All other messages are interpreted as message events.

Important

Caveats

Message encoding
As I am not very familiar with the IRC API and its message encodings in the current adapter I assume that all messages are utf-8 encoded. Should this not be the case, please report it. Should you be someone who is familiar with the encodings of IRC messages, please contact me so that we can improve this adapter.
CTCP messages
CTCP messages are not supported. All CTCP messages are currently ignored. However I welcome anyone who would like to try and implement some CTCP functionality.