Post message to Slack workspace

The f451 Communications module allows you to post messages to so-called Slack channels using a unified interface. In it’s simplest for form, you can post a plain text message to a given channel. But you can also post complex messages using so-called Slack blocks with styling, images, and more.

In order to use this service, you’ll need to set up an account with Slack. Once that is done, you get your API key and other relevant account credentials.

Note

Please refer to the “Configuration files” section for more detailed information on configuration requirements for Slack.

Todo

  • Create test using debug attribute

  • Create test using Slack block content attribute and debug flag

Core features

  • Post plain text messages to a Slack channel – Allows you to post simple messages to Slack channels.

  • Post formatted messages using Slack blocks – Allows to post complex multi-block messages.

Sending email using the slack.Slack object

You can send SMS using the send_message() method of the Slack object in the comms_slack sub-module as follows:

  1. Initialize the Slack object:

client = Slack(
            authToken,          # your Slack auth token
            fromName,           # your Slack username
            signingSecret,      # your Slack signing secret
            appToken,           # your Slack app token
            defaults            # optional default values
        )

  1. Call the send_message() method:

client.send_message(
            "Hello world!",     # plain text message
            attribs             # misc. attributes required to send message
        )

ALTERNATIVE: call send_message_with_blocks() method

client.send_message_with_blocks(
            blocks,             # message in form of list of Slack blocks
            attribs             # misc. attributes required to send message
        )

Slack blocks are a list of one or more dict structure. The following is a simple example:

{
    "type": "header",
    "text": {
        "type": "plain_text",
        "text": "Hello world!"
    }
}

Note

Please refer to Slack blocks documentation for more information of creating and styling message blocks.

Note

Please to section “Configuration files” for more details on defining secrets and config data.

Note

Please see below for a detailed description of options for attribs and note that some items are required in order to send messages via Slack. Also note that some values can be stored as default values when initializing the main Slack       `` object and the do not need to be included in the ``attribs argument.

Keywords and values for attribs argument

The following keywords and values are primarily used to pass additional arguments via the **kwargs parameter to the various send_message_<xxxx> functions. Please note that some keywords can also be used for defining API credentials and various default values for use in config files (e.g. config.ini).

  • account_sid
    • Required for:

      • SMS (Twilio) – Twilio account SID as str

    • Example .ini entry:

      • acct_sid = XX0x00x0x0xxxxx000x0x0x0x000xxx00x

    Warning

    Do NOT store this value in source code!

  • app_token
    • Required for:

      • Slack – Slack app token as str

    • Example .ini entry:

      • app_token = xapp-0-X00000000-000000000-00000000xxxxx00000000xxxxx00000000

    Warning

    Do NOT store this value in source code!

  • attachments
    • Optional for:

      • Email (Mailgun) – one or more file names as str or list of str

      • Slack – one or more file names as str or list of str

    • Examples:

      • Single attachment: {"attachments": path/to/file1.txt"}

      • Multiple attachments: {"attachments": ["path/to/file1.txt", "path/to/file2.txt"]}

  • auth_secret
    • Required for:

      • Twitter – Twitter auth secret as str

    • Example .ini entry:

      • auth_secret = xx0000000000xx000000x0000000x0xx00000xxx00000

    Warning

    Do NOT store this value in source code!

  • auth_token
    • Required for:

      • Slack – Slack auth token as str

      • SMS (Twilio) – Twilio auth token as str

      • Twitter – Twitter auth token as str

    • Example .ini entry:

      • auth_token = 000000000000000000000000000000000000000000000

    Warning

    Do NOT store this value in source code!

  • bcc_email
    • Optional for:

      • Email (Mailgun) – see to_email attribute

  • cc_email
    • Optional for:

      • Email (Mailgun) – see to_email attribute

  • channels
    • Required for:

      • Comms.send_message() method – one or more tags as str or list of str

    • Examples:

      • Send message to all available channels: {"channels": "all"}

      • Send message to Twitter and Slack: {"channels": ["f451_twitter", "f451_slack"]} or {"channels": "f451_twitter|f451_slack"}

    • Valid options:

      • all – all channels

      • f451_mailgun – email via Mailgun service

      • f451_slack – Slack message

      • f451_twilio – SMS via Twilio service

      • f451_twitter – Twitter status updates and DMs

    Note

    Use channel_map attribute to map custom keywords against channel names.

  • channel_map

    • Optional for: main section

    • Examples:

      • Map email and sms keywords: channel_map = email:f451_mailgun|sms:f451_twilio

  • debug

    • Reserved

  • file_title
    • Optional for:

      • Slack – file title as str

    • Examples:

      • Simple title: {"file_title": "List of Gotham City crime bosses"}

  • from

    • Optional for: main section. Complete sender info (e.g. name, phone, email, etc.) as str or list of str

    • Examples:

      • Complete sender info: from = name:Batman|email:batman@example.com|phone:+12125550001|slack:Batman|twitter:Batman

    Note

    Use from attribute instead of individual attributes (e.g from_name, from_email, from_phone, etc.).

  • from_domain
    • Required for:

      • Email (Mailgun) – Mailgun domain as str

    • Example .ini entry:

      • from_domain = xxxxxxx00000000000000000000.mailgun.org

    Warning

    Do NOT store this value in source code!

  • from_email

    • Reserved

  • from_name
    • Optional for:

      • Email (Mailgun) – sender name str

  • from_phone
    • Required for:

      • SMS (Twilio) – Twilio sender phone number as str

    • Example .ini entry:

      • from_phone = +12125150000

    Warning

    Do NOT store this value in source code!

  • from_slack
    • Optional for:

      • Slack – sender name str

  • from_twitter
    • Required for:
  • html
    • Optional for:

      • Email (Mailgun) – HTML version of email message as str

    • Example:

      • Simple: {"html": "<html>Hello world!</html>"}

  • icon_emoji
    • Optional for:

      • Slack – a str that represents the emoji short code.

    • Examples:

      • Use See No Evil emoji: {"icon_emoji": ":see_no_evil:"}

  • inline
    • Optional for:

      • Email (Mailgun) – one or more file names as str or list of str

    • Valid formats: .png, .jpg, .gif

    • Examples:

      • Single inline image: {"inline": path/to/image1.jpg"}

      • Multiple inline images: {"inline": ["path/to/image1.jpg", "path/to/image2.jpg"]}

  • log_level
    • Optional for:

      • all channels – int or str

    • Default: logging.INFO

    • Valid options:

      • -1 or OFF – no logging

      • int from 0 to 100 – log level is set to this value.

      • standard log levels defined in Python ‘logging’ package package as logging.<CONST> or equivalent string name

    • Examples:

      • Enable logging: {"log_level": logging.INFO} or {“log_level”: “INFO”}

      • Disable logging: {"log_level": -1} or {"log_level": "OFF"}

  • media
    • Optional for:

      • SMS (Twilio) – one or more file names as str or list of str

      • Twitter – one or more file names as str or list of str

    • Valid formats: .png, .jpg, .gif

    • Examples:

      • Single attachment: {"attachments": path/to/file1.txt"}

      • Multiple attachments: {"attachments": ["path/to/file1.txt", "path/to/file2.txt"]}

  • method_update

    • Reserved

  • method_dm
    • Optional for:

      • Twitter – boolean flag. If True message is sent as DM. This also requires at least one name listed in to_twitter attribute.

    • Default: False

    • Examples:

      • Send message as DM: {"method_dm": True}

  • name

    • Reserved

  • phone

    • Reserved

  • priv_api_key
    • Required for:

      • Email (Mailgun) – Mailgun private API key as str

    • Example .ini entry:

      • priv_api_key = key-00000000000000000000000000000000

    Warning

    Do NOT store this value in source code!

  • publ_val_key
    • Required for:

      • Email (Mailgun) – Mailgun public API key as str

    • Example .ini entry:

      • publ_val_key = pubkey-00000000000000000000000000000000

    Warning

    Do NOT store this value in source code!

  • recipient

    • Reserved

  • recipient_data
    • Optional for:

      • Email (Mailgun) – list of additional recipient info for batch emails as struct

    • Example:

      • Email address used as key: {"recipient_data": {"batman@example.com": {"name":"Batman", "lucky": 13}, ...}}

  • signing_secret
    • Required for:

      • Slack – signing secret as str

    • Example .ini entry:

      • signing_secret = xxxxx0000000000xxx000000000xxxx00000

    Warning

    Do NOT store this value in source code!

  • slack

    • Reserved

  • subject
    • Required for:

      • Email (Mailgun) – email subject line as str

    • Examples:

      • Simple: {"subject": "Hello world!"}

      • Personalized using recipients info: {"subject": "Hello %recipients.name%"}

  • suppress_errors
    • Optional for:

      • Email (Mailgun) – boolean flag. If True Mailgun exceptions are suppressed.

      • SMS (Twilio) – boolean flag. If True Twilio exceptions are suppressed.

      • Twitter DM – boolean flag. If True Twitter exceptions are suppressed.

    • Default: False

    • Examples:

      • Suppress errors: {"suppress_error": True}

  • tags
    • Optional for:

      • Email (Mailgun) – one or more (max 3) tags as str or list of str

    • Examples:

      • Single tag: {"tags": "greeting"}

      • Multiple tags: {"tags": ["greeting", "salutation"]} or {"tags": "greeting|salutation"}

  • testmode
    • Optional for:

      • Email (Mailgun) – boolean flag. If True test mode is enabled.

    • Default: False

    • Examples:

      • Enable test mode: {"testmode": True}

  • to

    • Optional for: main section. Complete recipient info (e.g. name, phone, email, etc.) as str or list of str

    • Examples:

      • Complete recipient info: from = name:Batman|email:batman@example.com|phone:+12125550001|slack:Batman|twitter:Batman

    Note

    Use to attribute instead of individual attributes (e.g to_name, to_email, to_phone, etc.).

  • to_channel
    • Required for:

      • Slack – one or more Slack channels as str or list of str

    • Examples:

      • Single channel: {"to_channel": "#GothamCrime"}

      • Multiple recipients: {"to_channel": ["#GothamCrime", "#NewVillains"]} or {"to_channel": "GothamCrime|NewVillains"}

  • to_email
    • Required for:

      • Email (Mailgun) – one or more email addresses as str or list of str

    • Examples:

      • Single recipient: {"to_email": "batman@example.com"}

      • Multiple recipients: {"to_email": ["batman@example.com", "robin@example.com"]} or {"to_email": "batman@example.com|robin@example.com"}

    Note

    If you send an email to multiple recipients, then also use the recipient_data attribute for additional recipient info.

  • to_phone
    • Required for:

      • SMS (Twilio) – one or more phone numbers as str or list of str

    • Examples:

      • Single recipient: {"to_phone": "+12125550000"}

      • Multiple recipients: {"to_phone": ["+12125550000", "+12125551111"]} or {"to_phone": "+12125550000|+12125551111"}

  • to_slack
    • Optional for:

      • Slack – one or more Slack user Names as str or list of str. Names listed here will be included with ‘@’ symbol in the beginning of the Slack message.

    • Examples:

      • Single name: {"to_slack": "batman"}

      • Multiple names: {"to_slack": ["batman", "robin"]} or {"to_slack": "batman|robin"}

  • to_twitter
    • Optional for:

      • Twitter – one or more Twitter user names as str or list of str. If method_dm is False, then names listed here will be included with ‘@’ symbol in the beginning of the Twitter status update message.

    • Examples:

      • Single name: {"to_twitter": "batman"}

      • Multiple names: {"to_twitter": ["batman", "robin"]} or {"to_twitter": "batman|robin"}

  • tracking
    • Optional for:

      • Email (Mailgun) – boolean flag. If True tracking is enabled.

    • Default: False

    • Examples:

      • Enable tracking: {"tracking": True}

  • twitter

    • Reserved

  • user_key
    • Required for:

      • Twitter – Twitter user key as str

    • Example .ini entry:

      • user_key = xxxxx0000000000xxx000000000xxxx00000

    Warning

    Do NOT store this value in source code!

  • user_secret
    • Required for:

      • Twitter – Twitter user secret as str

    • Example .ini entry:

      • user_secret = xxxxx0000000000xxx000000000xxxx00000xxxxx00000xxxxx0000

    Warning

    Do NOT store this value in source code!

  • webhook_sign_key
    • Required for:

      • Email (Mailgun) – Mailgun webhook sign key as str

    • Example .ini entry:

      • webhook_sign_key = key-xxxxx0000000000xxx000000000

    Warning

    Do NOT store this value in source code!

Note

Attributes that support str and list of str can process the lists either as a string using pipe character (|) as delimiter between values, or as a true lst of str:

  • list of values as simple str: "apple|banana|orange"

  • list of values as lst of str: ["apple", "banana", "orange"]

Examples

Example – attributes for simple Slack message:

attribs = {
    "to_channel": "#general",
}

Example – attributes for Slack message using Slack blocks:

attribs = {
    "to_channel": "#general",
    "attachments": ["path/to/joker.jpg", "path/to/riddler.jpg"],
}

Additional references