What is botschaft?
Botschaft is unified messaging & notifications appliance. Want to text yourself when a long-running task completes, but don’t want to remember your account id or store credentials on your job server? Or maybe you want to send a slack message, a discord message, and an SNS message, all at once? Define a botschaft topic and hit it whenever you want.
It’s as easy as
No, what is ‘botschaft’?
Botschaft, German, noun, feminine (genitive Botschaft, plural Botschaften)
Botschaft is “message” in German. The “bot” prefix seemed appropriate for what is essentially a notification bot.
- Dead simple HTTP API
- Declarative configuration
- “Topics”, flexible, customizable groups of destinations
Botschaft currently supports the following notification “providers”:
All providers are supported out of the box, and are enabled by specifying the corresponding section and parameters in the botschaft config file (see next section)
Topics are custom groups of provider destinations for a single message, for instance: Slack #alerts + Discord #general.
Botschaft optionally supports bearer token authentication, configured by setting the
BOTSCHAFT__ACCESS_TOKEN environment variable. When that variable is not set, the API is unauthenticated.
Botschaft Config File
The botschaft config file can be defined as
toml. Any combination of providers can be defined.
Botschaft will try its best to verify a valid configuration at start-up. If a topic requires a specific provider, it will make sure that provider section is specified in the config.
When any AWS providers are configured (currently only SNS), botschaft will load the AWS credentials and test the connection to AWS at startup (using sts.get_caller_identity).
Botschaft will first try loading the AWS credentials and profile via boto3 (environment, shared config file, aws cli configuration, etc.), but will fall back to optional Access Key and Secret Key values in the botschaft config file.
See the example configuration files here.
To start a botschaft instance, define your config file and start the container like so:
docker run -v /path/to/my/botschaft.toml:/botschaft.toml -p8000:8000 -it ttymck/botschaft:latest
Or use docker-compose, like the example here
Web API Reference
A running botschaft instance provides OpenAPI docs at
You can view a copy of the OpenAPI docs here: mrindoc viewer
Every provider exposes a
GET and a
POST route, accepting the
message and any other provider-specific parameters (see below) as either query parameters or a json body, respectively. The behavior of the
POST are identical, you are free to use either one based on personal perference (or, if your messages are too long for URLs, the
POST will accomodate them).
Every route takes a
message, which can be given by the
message_base64 parameter (if both are set,
message is used).
message_base64 will first be base64 decoded before being sent.
Each provider may take further parameters, generally to indicate the specific destination channel (Slack channel, SMS phone number, etc). These may correspond to the provider configuration