Slouch api

class slouch.Bot(slack_token, config)[source]

A Bot connects to Slack using the RTM API and responds to public messages that are directed to it with username- or at-mentions.

Manage the Bot’s channels in Slack itself with the /join command. A Bot can be in multiple Slack channels (though state is not isolated by channel).


the same config dictionary passed to init.


the bot’s Slack id. Not available until prepare_connection().


a Logger (logging.getLogger(__name__)).


the bot’s Slack name. Not available until prepare_connection().


the bot’s Slack mention, equal to <@%s> % . Not available until prepare_connection().


a Slacker instance created with slack_token.


a WebSocketApp instance. Not available until prepare_connection().

__init__(slack_token, config)[source]

Do not override this to perform implementation-specific setup; use prepare_bot() instead.

No IO will be done until run_forever() is called (unless prepare_bot() is overridden to perform some).

  • slack_token – a Slack api token.
  • config – an arbitrary dictionary for implementation-specific configuration. The same object is stored as the config attribute and passed to prepare methods.

Override to perform implementation-specific setup.

This is called once by __init__() and is not called on connection restarts.


Override to perform per-connection setup.

This is called by run_forever and on connection restarts.


Run the bot, blocking forever.

classmethod command(*args, **kwargs)[source]

A decorator to convert a function to a command.

A command’s docstring must be a docopt usage string. See for what it supports.

Commands receive three arguments:

  • opts: a dictionary output by docopt
  • bot: the Bot instance handling the command (eg for storing state between commands)
  • event: the Slack event that triggered the command (eg for finding the message’s sender)

Additional options may be passed in as keyword arguments:

  • name: the string used to execute the command (no spaces allowed)

They must return one of three things:

  • a string of response text. It will be sent via the RTM api to the channel where the bot received the message. Slack will format it as per
  • None, to send no response.
  • a dictionary of kwargs representing a message to send via Use this to send more complex messages, such as those with custom link text or DMs. For example, to respond with a DM containing custom link text, return {‘text’: ‘<|my text>’, ‘channel’: event[‘user’], ‘username’:}. Note that this api has higher latency than the RTM api; use it only when necessary.
classmethod help_text()[source]

Return a slack-formatted list of commands with their usage.