Included plugs#

Dummy#

Path: immp.plug.dummy.DummyPlug

For testing, a plug with no external network.

Messages with sequential identifiers are created and posted to the dummy channel every 10 seconds. Any messages sent to the plug are echoed to this channel as if a network had itself processed them.

Discord#

Path: immp.plug.discord.DiscordPlug

Connect to Discord as a bot.

Requirements

Extra name: discord

discord.py

emoji

Warning

Note that discord.py requires a minimum of Python 3.8 (IMMP itself only requires 3.7).

Config

token (str):

Discord token for the bot user.

message-content (bool):

Whether to use the privileged message content intent to receive the content of incoming messages. Without this, incoming messages will have no message text or attachments.

Before enabling here, you must enable the intent in Discord’s developer site, otherwise the underlying client will fail to connect.

members (bool):

Whether to use the privileged members intent to retrieve per-server member information. Without this, per-server nicknames and channel member lists will be unavailable.

Before enabling here, you must enable the intent in Discord’s developer site, otherwise the underlying client will fail to connect. For bots in large numbers of servers, this may cause a significantly longer startup time whilst members are initially retrieved.

webhooks ((str, str) dict):

Mapping from named Discord channels to webhook URLs, needed for custom message author names and avatars.

playing (str):

Optional game activity message to show as the bot’s presence.

Note that the token is neither a client ID nor client secret – you need to enable bot features for your app, and collect the token from there. New apps can be created from the My Apps page in the developer docs.

Channel sources should be Discord’s numerical IDs but quoted as strings, e.g. "123456789012". You can enable Advanced > Developer Mode in your Discord app settings in order to enable Copy ID menu options in various places across the UI.

Because gateway connections can’t customise the sender when pushing new messages, you may also want an incoming webhook configured for each channel you intend to send messages to. A new webhook can be created over the API, or in the UI via Edit Channel > Webhooks. A fallback style incorporating the user’s name in the message text will be used in lieu of a webhook, e.g. with direct messages.

GitHub#

Path: immp.plug.github.GitHubPlug

Listen for incoming GitHub webhooks.

Dependencies

WebHook

Config

route (str):

Path to expose the webhook request handler.

secret (str):

Shared string between the plug and GitHub’s servers. Optional but recommended, must be configured to match the webhook on GitHub.

Go to your repository > Settings > Webhooks > Add webhook, set the URL to match the configured route, and choose the events you wish to handle. Message summaries for each event will be emitted on channels matching the full name of each repository (e.g. user/repo).

Hangouts#

Path: immp.plug.hangouts.HangoutsPlug

Connect to Google Hangouts as a regular user.

Requirements

Extra name: hangouts

hangups

Config

cookie (str):

Path to a cookie text file read/written by hangups.get_auth_stdin().

read (bool):

True (default) to update conversation watermarks on every message, thus marking each message as read once processed.

The cookie file is used by hangups to store the access token. If the file doesn’t exist or is invalid, you will be prompted for Google account credentials at startup. You can generate a new cookie file manually by interacting with hangups directly:

$ python -m hangups.auth

This will generate a cookie file called refresh_token.txt in the current directory.

IRC#

Path: immp.plug.irc.IRCPlug

Connect to an IRC server.

Config

server:
host (str):

Hostname of the server.

port (int):

Non-SSL port of the server.

ssl (bool):

Whether to connect using SSL.

password (str):

Optional password required for the server.

user:
nick (str):

Primary nick for the bot user.

real-name (str):

Real name, as displayed in WHO queries.

perform (str list):

List of raw IRC lines to send during the initial connection (after NICK and USER). Only applies to the main plug user, not puppets.

quit (str):

Quit message, sent as part of disconnection from the server.

accept-invites (bool):

True to auto-join channels when an INVITE is received.

colour-nicks (bool):

True to apply IRC colour formatting to nicks when including author names in messages (i.e. when not using puppets).

quote-reply-to (bool):

True to include a snippet of the parent message, when the incoming one is a reply.

puppet (bool):

Whether to use multiple IRC clients for sending. If enabled, new client connections will be made when sending a message with an unseen username, and reused for later messages.

puppet-prefix (str):

Leading characters to include in nicks of puppet users.

send-delay (float):

Time in seconds to wait between sending each message (0.5 by default, i.e. 2 messages per second), in order to avoid being kicked for flooding.

You can reduce this if the connecting IRC user has been given higher limits on the server, or increase this for servers with stricter flood limits.

Channel sources should include the correct channel prefix or prefixes (typically just #) for shared channels, and bare IRC nicks for private channels.

Slack#

Path: immp.plug.slack.SlackPlug

Connect to a Slack workspace as a bot.

Requirements

Extra name: slack

aiohttp

emoji

Config

token (str):

Slack API user or bot token (xoxb prefix).

app-token (str):

Slack API app token, if using a modern app (xapp prefix).

fallback-image (str):

Avatar to display for incoming messages without a user or image (default: none).

thread-broadcast (bool):

True to always send outgoing thread replies back to the channel.

real-names (bool):

True to prefer user real names when sending messages, False to prefer usernames.

Slack supports multiple types of apps and legacy integrations; this plug supports most of them. If you’re starting fresh, you should create a new Slack App and follow the modern app steps below.

If you have an existing Slack App created on or after December 2019, then it is a modern app. Apps created before then are of classic type, and classic apps with an existing bot user should work without further setup; just enter the current bot API token in the token config field. You can alternatively use any tokens that have access to the RTM APIs, including those from legacy bot integrations and legacy tester tokens, if you have them.

The events and scopes listed below cover everything that’s supported by this plug – you are free to grant a subset of these as desired, with the obvious caveat that the corresponding features you deny access to will not work. Note that classic app bots do not have any channel management permissions, so cannot add or remove users in channels.

Modern apps (manifest):

  • Create an app if you haven’t already.

  • Socket Mode page – enable it for your app.

  • Event Subscriptions page – enable the following events:

    channel_archive, channel_left, channel_rename, channel_unarchive, group_archive, group_deleted, group_left, group_rename, group_unarchive, message.channels, message.groups, message.im, message.mpim, member_joined_channel, member_left_channel, team_join, team_rename, user_change

  • OAuth & Permissions page – grant the following scopes:

    channels:read, channels:history, channels:manage, groups:read, groups:history, im:read, im:history, im:write, mpim:read, mpim:history, chat:write, chat:write.customize, files:read, files:write, team:read, users:read

  • App Home page – enable the Messages tab and sending of messages, and add a bot user.

  • Install App page – install the app to your workspace, collect your bot OAuth token, and enter that in the token config field.

  • Basic Information page – generate or collect an app-level token with the connections:write scope, and enter that in the app-token config field.

Classic apps:

  • Create a classic app if you haven’t already.

  • OAuth & Permissions page – grant the bot scope.

  • App Home page – enable the Messages tab and sending of messages, and add a bot user.

  • Install App page – install the app to your workspace, collect your bot OAuth token, and enter that in the token config field.

If multiple Slack workspaces are involved, you will need a separate bot and plug setup per team. There is no special handling of Enterprise Grid workspaces.

Channel sources should be Slack’s channel IDs, typically of the form C12345678 where C is the channel type and the rest forms its random identifier. Note that using channel display names like #channel is not supported (it may work for sending, but each message received will only be attributed to its identifier rather than name).

Telegram#

Path: immp.plug.telegram.TelegramPlug

Connect to Telegram as a bot.

Requirements

Extra name: telegram

aiohttp

telethon:

Required for use of app features (client updates, user lookups, message history).

Config

token (str):

Telegram bot token for the bot API.

api-id (int):

Optional Telegram application ID for the MTProto API.

api-hash (str):

Corresponding Telegram application secret.

client-updates (bool):

True (when API credentials are configured) to listen for messages over the MTProto connection instead of long-polling with the bot API.

This allows you to maintain multiple connections with a single bot account, however it will not mark messages as read within the bot API. This means if you switch back to the bot API at a later date, you’ll receive a backlog of any messages not yet picked up.

session (str):

Optional path to store a session file, used to cache access hashes.

stickers (bool):

True to include stickers in messages as proprietary-format attachments (.tgs files).

Bots can be created by talking to @BotFather. Use the /token command to retrieve your API token. You should also call /setprivacy to grant the bot permission to see all messages as they come in.

Channel sources should be Telegram’s numerical IDs but quoted as strings, e.g. "12345678". Telegram supergroups and channels should include the -100 prefix. Note that channel usernames can’t be used as a source, though they can be passed to Plug.user_from_username() in order to reveal the corresponding identifier.

Telegram bots are rather limited by the bot API. To make use of some features (including lookup of arbitrary users and listing members in chats), you’ll need to combine bot authorisation with an MTProto application. This is done via app credentials applied to a bot session – the bot gains some extra permissions from the “app”, but accesses them itself.

Note that most objects in Telegram cannot be retrieved by ID until you’ve “seen” them via other methods. With a session file, you need only do this once, after which the reference to it (the “access hash”) is cached.