Configuration files

As the f451 Communications module is merely an abstraction layer for a several different of communication services, it relies on the calling application to provide all necessary API keys and other secrets and settings to properly authenticate with those services.

These keys and and secrets can be submitted ad hoc (via properly formatted dict structures) when the communications object is initialized. However, it is recommended to instead store these keys and secrets in so-called configuration files and then submit the filename and path to these files to the initialization method.

Furthermore, the f451 Communications module allows you to keep keys and secrets and default applications settings in separate files. For example, keys and secrets can be stored in a file called secrets.ini and miscellaneous settings and default values can be stored in config.ini.

Note

Any configuration file must use a format that the Python ConfigParser library can process.

Note

It’s not necessary to have a separate secrets.ini file for the just the f451 Communications module. As long as there is no conflict between section names, values required by f451 Communications can be co-located with values required by other modules and systems.

Sample `secrets.ini` file

The secrets.ini file should contain all keys and secrets required to authenticate against the services that you want to use with the f451 Communications module.

[f451_mailgun]
priv_api_key = _YOUR_PRIVATE_API_KEY_
publ_val_key = _YOUR_PUBLIC_API_KEY_
webhook_sign_key = _YOUR_WEBHOOK_SIGNING_KEY_
from_domain = _YOUR_DOMAIN_NAME_

[f451_slack]
auth_token = _YOUR_SLACK_AUTH_TOKEN_
app_token = _YOUR_SLACK_APP_TOKEN_
signing_secret = _YOUR_SLACK_SIGNING_SECRET_

[f451_twilio]
acct_sid = _YOUR_TWILIO_SID_
auth_token = _YOUR_TWILIO_TOKEN_
from_phone = _YOUR_TWILIO_FROM_PHONE_+15555550000

[f451_twitter]
user_key = _YOUR_TWITTER_USER_KEY_
user_secret = _YOUR_TWITTER_SECRET_KEY_
auth_token = _YOUR_TWITTER_AUTH_TOKEN_
auth_secret = _YOUR_TWITTER_AUTH_SECRET_

Sample config.ini file

The config.ini file can hold any optional settings and default values for the f451 Communications module.

[f451_main]
location = _YOUR_LOCATION_
location_tz = _YOUR_TIME_ZONE_
latitude = _YOUR_LATITUDE_
longitude = _YOUR_LONGITUDE_

channels = _DEFAULT_CHANNEL_ONE_|_DEFAULT_CHANNEL_TWO_
channel_map = email:f451_mailgun|sms:f451_twilio|twitter:f451_twitter|slack:f451_slack|forums:f451_slack

from = name:_DEFAULT_SENDER_NAME_|email:_DEFAULT_SENDER_EMAIL_|phone:_DEFAULT_SENDER_PHONE_|slack:_DEFAULT_SENDER_SLACK_NAME_|twitter:_DEFAULT_SENDER_TWITTER_NAME_
;from_name = _DEFAULT_SENDER_NAME_
;from_email = _DEFAULT_SENDER_EMAIL_
;from_phone = _DEFAULT_SENDER_PHONE_
;from_slack = _DEFAULT_SENDER_SLACK_NAME_
;from_twitter = _DEFAULT_SENDER_TWITTER_NAME_

to = name:_DEFAULT_TO_NAME_|email:_DEFAULT_TO_EMAIL_|phone:_DEFAULT_TO_PHONE_|slack:_DEFAULT_TO_SLACK_NAME_|twitter:_DEFAULT_TO_TWITTER_NAME_
;to_name = _DEFAULT_TO_NAME_
;to_email = _DEFAULT_TO_EMAIL_
;to_phone = _DEFAULT_TO_PHONE_
;to_slack = _DEFAULT_TO_SLACK_NAME_
;to_twitter = _DEFAULT_TO_TWITTER_NAME_

[f451_mailgun]
subject = _DEFAULT_EMAIL_SUBJECT_

[f451_slack]
icon_emoji = _USER_ICON_EMOJI_
to_channel = _DEFAULT_SLACK_CHANNEL_

[f451_twilio]

[f451_twitter]

Using `dict` structure during testing

It is recommended that permanent keys and secrets are stored in config files. However, some use cases may call for using temporary values (e.g. for testing) and to support that, the f451 Communications module also allows you to supply keys, secrets, and other configurations values via properly formatted dict structures.

data = {
    'section1_label': {
        'item1_key': 'value1',
        'item2_key': 'value2',
         ...
        'itemN_key': 'valueN',
    }
}

Such a dict structure is then converted internally to a ConfigParser object.

Keywords for managing secret keys and values

The f451 Communications module looks for specific section and item labels to be used as credentials for the supporting communication services.

Section f451_mailgun

Description: used for values related to Mailgun email service
Required: yes, if email channel is used
Items:
- priv_api_key – your private Mailgun API key string
- publ_val_key – your public Mailgun API key string
- webhook_sign_key – your Mailgun webhook signing key
- from_domain – your Mailgun domain name
Reference: Mailgun

Section f451_slack

Description: used for values related to Slack service
Required: yes, if Slack channel is used
Items:
- auth_token – your Slack auth token
- app_token – your Slack app token
- signing_secret – your Slack signing secret
Reference: Slack

Section f451_twilio

Description: used for values related to Slack service
Required: yes, if Slack channel is used
Items:
- acct_sid – your Twilio account SID
- auth_token – your Twilio auth token
- from_phone – your ‘from’ phone number
Reference: Twilio

Section f451_twitter

Description: used for values related to Twitter service
Required: yes, if Twitter channel is used
Items:
- user_key – your Twitter user key
- user_secret – your Twitter secret key
- auth_token – your Twitter auth token
- auth_secret – your Twitter auth secret
Reference: Twitter, Tweepy

Keywords for managing optional settings and values

The f451 Communications module looks for specific section and item labels to be used as optional setting or default values for the supporting communication services.

Section f451_main

Description: used for optional settings related to ???
Items:
- channels – list of default channels separated by ‘|’ character (e.g. ‘twitter|slack’)