IMMP (pronounced, unsurprisingly, as “imp” 😈) is an Instant Message Modular Processor.

At a high level, it allows you to accept incoming data (in the form of messages) from a variety of sources, and distribute them to worker methods that act on them as they wish.


The system consists of a number of basic building blocks, most of which are represented by standard Python classes:


An external service that provides message-based communication.


A unit of data, which can include text, images, attachments, authorship, and so on.


An individual or service which can author messages on a network.


A handler for all communication with an external network, transforming the network’s content to message objects and back again.


A single room in an external network – a source of messages, and often a container of users.


A collection of plugs and channels.


A worker that processes a stream of incoming messages, in whichever way it sees fit.

The top of the system is called the host, and coordinates message delivery between plugs and hooks. When any connected plug receives a message from its network, the standard message object is passed to the host, along with the source channel. From here, the host pushes this pair to all hooks.

Hooks may themselves yield messages, which can be sent directly to a channel (either back to the source, or to any other channel it knows about).

Use cases#

Communication with third-party tools#

If your favourite service doesn’t provide a native integration for your preferred networks, write your own! Create a plug to listen on a socket, long-poll an API, or do whatever it needs to retrieve its data, then generate simple message objects from your data. From there, you can use the various built-in hooks to process that data, or craft the exact logic you need by writing a small hook of your own.

Multi-platform bots#

Because all plugs yield a common representation of messages, one can write a bot in the form of a hook, after which it’s trivial to extend it to arbitrarily many channels of the supported networks. By default, hooks receive all messages across all plugs, so it’s up to the hook to filter by channel, typically by accepting a list of channels or plugs in its config.

The hooks distributed with IMMP provide small assorted bot features, such as automatic responses, mention and subscription alerts via private messages, recallable notes for channels, and more.

Powerful channel bridging#

The message format allows plugs to make use of common network-provided features wherever possible, such as rich text formatting, message replies and forwarding, user joins and parts, and so on. The built-in sync hook harnesses these to generate native-looking messages across all platforms. Never lose track of message threads – replies from an external network are seamlessly included in the conversation.

Help chat#

If you’re looking to start running your own IMMP instance, or develop plugs or hooks for one, drop by the admin chat on Hangouts or Telegram to ask any burning questions.