gancio.notification

A tool for sending Gancio event notifications.

This is intended to be a dumb tool that fetches Gancio events for the current day through its API and sends a formatted digest of events through various notification channels. As of now it supports:

• Telegram
• IRC
• Mastodon

Building

The build system is based on Task. For a list of available tasks run task -l.

• To build the project in your development environment:

task build

• To build a Docker image (even outside of a working Go development environment):

task docker:build

Configuration

• JSON config file: copy/edit the sample config file
• Environment: check the sample env file

Note

Environment variables override the values in config file

Usage

• With env file:

set -a && . /path/to/.env && set +a && ./gancio.notification

• With config file:

./gancio.notification -config /path/to/config.json

• Setting/overriding individual options:

LOG_LEVEL="debug" ./gancio.notification -config /path/to/config.json

• Print version:

./gancio.notification -version

Docker

• use docker run:

task docker:run -- /path/to/config.json

• use docker compose up -d with a similar compose.yaml.

API and Dashboard

An HTTP server is automatically started to serve a REST API and a web dashboard for most common operations:

• Sending custom service messages to channels (e.g. for maintainance, important news or alerts)
• Marking and unmarking events as Important: important events will be notified daily regardless of their start date, until they are over
• Controlling the scheduler times and status

Default port is 8080 unless changed via HTTP_ADDR env variable.

• Web dashboard is available at /.
• REST API is available at /api
• REST API docs is available at /api/docs

Bot Commands

The bot responds to commands on Telegram and IRC to query events on demand.

Note

Command receiving can be disabled per channel by setting "EnableCommands": false in the channel configuration. When disabled, the bot will only send notifications and will not respond to commands. If not specified, command receiving is enabled by default.

Available Commands

Command	Description
help	Show this help message
oggi	Events happening today
domani	Events happening tomorrow
settimana	Events for the rest of this week
prossimi	Upcoming events for the rest of this month
cerca <query>	Search events by title or place name
version	Show version info

Telegram

Prefix any command with /. Example: /oggi shows today's events.

IRC

• In a channel: address the bot by its nick, followed by : or ,. Example: BotNick: oggi
• In a private message: send the command directly without any prefix. Example: /msg BotNick oggi

Rate Limiting

Each user is limited to 5 commands per minute; the bot also has a global limit of 30 commands per minute. When the rate limit is exceeded, a warning message is sent to the user (or silently dropped for the global limit).