Send messages to multiple channels

The f451 Communications module allows you to send messages to several channels at the same time via the unified send_message() method in the Comms object. You indicate which channels to use, as well as other message attributes, using the attribs argument. For example, you can send the same message via Twitter, Slack, and SMS with a single method call.

In order to use this command, you’ll need to set up an accounts with all services that you want to use. Once that is done, you get your API keys and other relevant account credentials which you’ll need in order to send messages.

Note

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

Todo

  • Create test using debug attribute

Core features

  • Send messages to several services – the send_message() method routes the request to all services listed in the ``channels`` attribute in ``attribs``.

  • Send messages using specific services using send_message_via_xxxx() methods – the Comms object also has wrapper methods for the individual services.

Send message to one or more channels

You can send messages using the unified send_message() method as follows:

STEP 1: initialize Comms object

comms = Comms(
            secrets,            # credentials required for services
            config              # optional settings
        )

STEP 2: call send_message() method

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

Note

Please refer 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 different items are required depending on which channels are used. Also note that some values can be stored as default values when initializing the main Comms object and then do not need to be included in the attribs argument when calling methods to send emails.

Send email using send_message_via_email()

You can send emails using the send_message_via_email() method as follows:

STEP 1: initialize Comms object

comms = Comms(
            secrets,            # credentials required for services
            config              # optional settings
        )

STEP 2: call send_message_via_email() method:

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

Note

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

Note

Please refer to section “Mailgun email” for additional details and examples for sending emails.

Note

Please see below for a detailed description of options for attribs and note that some items are required in order to send emails. Also note that some values can be stored as default values when initializing the Comms object and then do not need to be included in the attribs argument when calling this method.

Note

If send_message_via_email() is used, then channels attribute is not required in the attribs argument.

Send SMS using send_message_via_sms()

You can send messages via SMS using the send_message_via_sms() method as follows:

STEP 1: initialize Comms object

comms = Comms(
            secrets,            # credentials required for services
            config              # optional settings
        )

STEP 2: call send_message_via_sms() method:

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

Note

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

Note

Please refer to section “Twilio SMS” for additional details and examples for sending SMS.

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 SMS. Also note that some values can be stored as default values when initializing the Comms object and then do not need to be included in the attribs argument when calling this method.

Note

If send_message_via_sms() is used, then channels attribute is not required in the attribs argument.

Post Twitter status update using send_message_via_twitter()

You can post Twitter status updates using the send_message_via_twitter() method as follows:

STEP 1: initialize Comms object

comms = Comms(
            secrets,            # credentials required for services
            config              # optional settings
        )

STEP 2: call send_message_via_twitter() method:

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

Note

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

Note

Please refer to section “Twitter update & DM” for more details around posting Twitter status updates and sending DMs using the twitter.Twitter object and its methods.

Note

Please see below for a detailed description of options for attribs and note that some items are required in order to post Twitter status updates. Also note that some values can be stored as default values when initializing the Comms object and then do not need to be included in the attribs argument when calling this method.

Note

If send_message_via_twitter() is used, then channels attribute is not required in the attribs argument.

Post Slack status update using send_message_via_slack()

You can post Slack status updates using the send_message_via_slack() method as follows:

STEP 1: initialize Comms object

comms = Comms(
            secrets,            # credentials required for services
            config              # optional settings
        )

STEP 2: call send_message_via_slack() method:

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

Note

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

Note

Please refer to section “Slack message” for more details around posting Slack status updates using the slack.Slack object and its methods.

Note

Please see below for a detailed description of options for attribs and note that some items are required in order to post Slack status updates. Also note that some values can be stored as default values when initializing the Comms object and then do not need to be included in the attribs argument when calling this method.

Note

If send_message_via_slack() is used, then channels attribute is not required 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 – send simple message via multiple channels

 1 comms = Comms(secrets, config)              # Initialize ``Comms`` with credentials
 2                                             # and optional default settings
 3 msg = "Hello world!"
 4 attribs = {
 5     "channels": ["f451_mailgun", "f451_twilio", "f451_twitter", "f451_slack"],
 6     "to_phone": "+12125550000",
 7     "to_channel": "#GothamCrime",
 8     "to_email": "batman@example.com",
 9     "subject": "Hello!",
10 }
11
12 comms.send_message(msg, attribs)            # Send message via multiple channels