Post Twitter status updates and send DMs

The f451 Communications module allows you to post Twitter status updates and send DMs to a given recipient using a unified interface. In it’s simplest for form, you can post plain text message status update. But you can also send DMs to specific recipients.

In order to use this service, you’ll need to set up an account with Twitter. 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 Twitter status updates and DMs.

Core features

  • Post status updates – Status updates can be text-only as well as include images.

  • Send DMs to multiple recipients – Allows you to send Twitter DM messages to multiple recipients

Post status updates using the main Comms object

You can send Twitter status updates using the unified send_message() method of the Comms object 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
        )

ALTERNATIVE: 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 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 emails. Also note that some values can be stored as default values when initializing the main Comms object and the do not need to be included in the attribs argument.

Note

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

Post status updates using the comms_twitter.Twitter object

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

  1. Initialize the Twitter object:

client = Twitter(
            usrKey,             # your Twitter user key
            usrSecret,          # your Twitter user secret
            authToken,          # your Twitter auth/access token
            authSecret,         # your Twitter auth/access token secret
            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
        )

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 Twitter status updates or DMs. Also note that some values can be stored as default values when initializing the main Comms 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 – structure for simple Twitter status update:

attribs = {
    "channels": "f451_twitter",
}

Example – structure for simple Twitter DM:

attribs = {
    "channels": "f451_twitter",
    "to_twitter": "batman",
    "method_dm": True,
}

Example – structure for simple Twitter status update with ‘@’ some Twitter users:

attribs = {
    "channels": "f451_twitter",
    "to_twitter": ["batman", "robin"],
    "method_dm": False,
}

Additional references