Included plugs

Dummy

Path: immp.plug.dummy.DummyPlug

For testing, a plug with no external network.

Messages with sequential identifiers are created and returned every 10 seconds. Any messages sent to the plug are cloned and returned as if a network had processed them.

Discord

Path: immp.plug.discord.DiscordPlug

Connect to Discord as a bot.

Config:
token (str):
Discord token for the bot user.
bot (bool):
Whether the token represents a bot user (true by default).
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.

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.

Note

This plug requires the discord.py Python module.

GitHub

Path: immp.plug.github.GitHubPlug

Listen for incoming GitHub webhooks.

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).

Note

This plug requires an active WebHook to receive incoming messages.

Hangouts

Path: immp.plug.hangouts.HangoutsPlug

Connect to Google Hangouts as a regular user.

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.

Note

This plug requires the hangups Python module.

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.
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.
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.

Messenger

Note

Not yet released.

Path: immp.plug.messenger.MessengerPlug

Connect to Facebook Messenger as a bot.

Config:
route (str):
Path to expose the webhook request handler.
access-token (str):
Facebook page token, with grants to use chat from the desired page.
verify-token (str):
Locally-generated string, given to Facebook and included with their requests to verify their authenticity.

This plug requires a Facebook page, and a Facebook app to provide API access. The getting started pages explain the needed setup. The webhook URL should combine the host/port where the WebHook server is accessible, with the route defined in the config.

Note

This plug requires an active WebHook to receive incoming messages.

Slack

Path: immp.plug.slack.SlackPlug

Connect to a Slack workspace as a bot.

Config:
token (str):
Slack API token for a bot user.
fallback-name (str):
Name to display for incoming messages without an attached user (default: IMMP).
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.

You’ll need to create either a full Slack App and add a bot, or a Bot Integration. In either case, you should end up with a token prefixed xoxb-.

You may alternatively use a full user account, with a token obtained from the Legacy tokens page. This is required to make use of adding or removing users in channels.

If multiple Slack workspaces are involved, you will need a separate bot and plug setup per team.

Telegram

Path: immp.plug.telegram.TelegramPlug

Connect to Telegram as a bot.

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.

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.

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.

Note

Use of app features requires the telethon Python module.

Terraria

Note

Not yet released.

Path: immp.plug.terraria.TerrariaPlug

Connect to a Terraria server running TShock.

Config:
url (str):
Websocket URL as configured with ChatSock.
world (str):
World name, shown in join/leave messages.

The ChatSock plugin for TShock exposes the server chat over a websocket, suitable for this hook to consume from and broadcast to.