Skip to content

Notifications

Jump to bottom
Daniel Heinen edited this page May 9, 2026 · 1 revision

Notifications (Apprise)

ankerctl supports push notifications via Apprise, which can deliver to over 80 services including Discord, Telegram, Slack, Pushover, Matrix, MQTT, and email.

ankerctl does not bundle Apprise itself — it talks to a separate Apprise API server that you run alongside it.

Architecture

[ankerctl] ──HTTP POST──▶ [Apprise API] ──fan-out──▶ [Discord, Telegram, ...]

The Apprise API server holds the credentials for every notification channel. ankerctl only knows the server URL and a per-event toggle.

Run an Apprise API server

The simplest option is the official Docker image:

# Add to your docker-compose.yaml
services:
  apprise:
    image: caronc/apprise
    container_name: apprise
    ports:
      - "8000:8000"
    volumes:
      - ./apprise/config:/config
    restart: unless-stopped

Then configure a notification key (e.g. ankerctl) in the Apprise web UI at http://localhost:8000 and add your destination URLs (discord://..., tgram://..., etc.).

For other deployment options see the Apprise API repo.

Configure ankerctl

Two paths — env vars or the web UI.

Via web UI

Open Setup → Notifications and fill in:

  • Server URL — http://localhost:8000 (or wherever your Apprise API runs)
  • Key — the notification key you set up in Apprise
  • Tag — optional Apprise tag filter
  • Toggle the events you want
  • Click Save, then Send test to verify

Via environment variables

APPRISE_ENABLED=true
APPRISE_SERVER_URL=http://apprise:8000
APPRISE_KEY=ankerctl
APPRISE_TAG=critical          # optional

# Event toggles
APPRISE_EVENT_PRINT_STARTED=true
APPRISE_EVENT_PRINT_FINISHED=true
APPRISE_EVENT_PRINT_FAILED=true
APPRISE_EVENT_GCODE_UPLOADED=true
APPRISE_EVENT_PRINT_PROGRESS=true

# Progress tuning
APPRISE_PROGRESS_INTERVAL=25                # notify at 25%, 50%, 75%, 100%
APPRISE_PROGRESS_INCLUDE_IMAGE=false
APPRISE_PROGRESS_MAX=0                      # 0 = auto-detect MQTT scale

# Snapshot tuning
APPRISE_SNAPSHOT_QUALITY=hd                 # sd | hd | fhd
APPRISE_SNAPSHOT_FALLBACK=true              # use G-code preview if live capture fails
APPRISE_SNAPSHOT_LIGHT=false                # turn on printer light for snapshot

See Configuration → Apprise notifications for the full table with defaults.

Events

Event Trigger
EVENT_PRINT_STARTED ct=1000 value=1 (state machine entered "printing")
EVENT_PRINT_FINISHED ct=1000 value=0 after a successful print
EVENT_PRINT_FAILED ct=1000 value=0 after a stop/cancel, or ct=1000 value=8 (touchscreen abort)
EVENT_GCODE_UPLOADED File transfer completed
EVENT_PRINT_PROGRESS At every APPRISE_PROGRESS_INTERVAL percent threshold

Snapshot attachments

When an image-attaching event fires, ankerctl:

  1. Asks VideoQueue for a JPEG snapshot at APPRISE_SNAPSHOT_QUALITY
  2. If APPRISE_SNAPSHOT_LIGHT=true, briefly turns on the printer LED
  3. Falls back to the G-code preview image if live capture fails and APPRISE_SNAPSHOT_FALLBACK=true
  4. Sends a text-only notification if neither image source works

Quality options:

Value Resolution
sd 848 × 480
hd 1280 × 720 (default)
fhd 1920 × 1080

fhd uses the printer's snapshot-only mode — no live stream interruption.

Test the setup

Three ways to verify end-to-end:

# Web UI
# Setup → Notifications → Send test

# REST
curl -X POST http://localhost:4470/api/notifications/test \
     -H "X-Api-Key: my-secret-key"

# CLI (for protocol debugging — not a notification path)
./ankerctl.py mqtt monitor      # see what events fire during a real print

You should receive a "Test notification from ankerctl" message in your configured channels within a few seconds.

Tips

  • Tags let you scope which Apprise destinations receive which events. Set up tags in the Apprise UI (@critical, @info, etc.) and put the matching tag in APPRISE_TAG.
  • Per-printer settings are not currently supported — Apprise notifications use the active printer.
  • Multiple Apprise keys are not supported either — point the URL at a single key with multiple destination URLs underneath it.
  • Progress at 100% is sent as a separate "finished" event, not as a final progress notification.

Troubleshooting

See Troubleshooting → Notification issues for common problems (Apprise unreachable, wrong key, missing snapshots).

ankerctl Wiki

Links

Clone this wiki locally