SMS and Push Notifications - wiso-forschungslabor/hroot-documentation GitHub Wiki

This page describes the SMS Reminders, Custom SMS Messages, and Web Push Notifications systems in hroot version 4.0.

[!NOTE] All SMS and Push notifications features can be toggled on/off in Site Settings -> Communication Matrix and are subject to user-specific preference toggles inside their participant profiles.

Table of Contents

  1. SMS Reminders
  2. Custom SMS Messages
  3. Web Push Notifications
  4. Gateway Integration & Server Setup (sms-gate.app)
  5. Pairing the Smartphone (Server Mode)
  6. Local Server Mode
  7. Developer Interception (Non-Production)

1. SMS Reminders

To improve attendance rates, hroot can automatically send text message reminders to participants before a session begins.

  • Dual Reminders: The system supports two separate reminder triggers:
    • First SMS Reminder: Sent at a configured number of hours before the session start (e.g. 48 hours).
    • Second SMS Reminder: Sent closer to the session start (e.g. 2 hours) as a final warning.
  • Custom Templates: Default SMS text templates can be defined globally under Site Settings (Options > Emails) and overridden on a per-experiment level.
  • Opt-In/Out: Participants can manage their mobile numbers and opt in or out of SMS reminders under their profile settings (account/sms_reminder).

2. Custom SMS Messages

Experimenters with the send_session_messages privilege can send direct custom SMS messages to participants:

  • Individual SMS: Send a custom text message to a specific registered participant via the session participants action menu.
  • Bulk SMS: Send a text announcement to all participants registered in a session at once.

3. Web Push Notifications

Participants using modern desktop or mobile browsers can subscribe to Web Push Notifications.

  • VAPID Keys: Built-in VAPID keys (VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY in .env) handle encryption handshake between the server and the browser push service.
  • Subscription Prompt: Users are prompted to allow push notifications when logging in or via a prompt on their account panel (account/push_prompt).
  • Push Notification Types:
    • Invitations: Notifies when invited to a new experiment.
    • Digests: Notifies when a new digest list is compiled.
    • Confirmations: Triggers upon registration confirmation.
    • Waiting List: Alerts when a seat becomes available on a session's waiting list.
    • Reminders: Standard browser-level session reminders.
    • Warnings: Alerts on no-shows or account retention (e.g., 1-year inactivity warnings).

4. Gateway Integration & Server Setup (sms-gate.app)

Outbound SMS is handled via direct API integrations to the open-source gateway server android-sms-gateway/server (also known as sms-gate.app).

The SMS Gateway services (sms-gateway and sms-gateway-worker) are defined in docker-compose.yml under the sms Compose profile.

  • When SMS is enabled, COMPOSE_PROFILES=sms is set in .env and Docker starts both the server and worker.
  • If a lab chooses not to use SMS, COMPOSE_PROFILES= can be left empty, completely omitting the SMS containers to save system resources.

Option A: Subpath on Main Domain (Default & Recommended)

This serves the SMS Gateway API directly under your primary domain at https://your-domain.com/sms-gateway.

  • No extra DNS record needed: Reuses your main domain without requiring IT departments to grant additional subdomains.
  • Shared SSL Certificate: Utilizes the existing Let's Encrypt certificate of your main HROOT domain.
  • Nginx Reverse Proxy: Pre-configured via docker/nginx/vhost.d/default_location to transparently route /sms-gateway/ to the gateway container while supporting WebSockets and SSE.

Configuration in .env:

COMPOSE_PROFILES=sms
SMS_FEATURE_ENABLED=true
SMS_SEND_MODE=api
SMS_GATEWAY_API_URL=https://your-hroot-domain.com/sms-gateway/api/3rdparty/v1/messages
SMS_GATEWAY_PRIVATE_TOKEN=your_generated_pairing_token
SMS_GATEWAY_API_USERNAME=hroot
SMS_GATEWAY_API_PASSWORD=your_gateway_password

Option B: Hosting on a Dedicated Subdomain

If you prefer complete separation via a dedicated subdomain (e.g. sms.your-hroot-domain.com):

  1. Create a DNS A-record or CNAME for sms.your-hroot-domain.com pointing to your server.
  2. In .env, configure: 
    COMPOSE_PROFILES=sms
SMS_FEATURE_ENABLED=true
SMS_SEND_MODE=api
SMS_GATEWAY_DOMAIN=sms.your-hroot-domain.com
SMS_GATEWAY_API_URL=https://sms.your-hroot-domain.com/api/3rdparty/v1/messages
SMS_GATEWAY_PRIVATE_TOKEN=your_generated_pairing_token
SMS_GATEWAY_API_USERNAME=hroot
SMS_GATEWAY_API_PASSWORD=your_gateway_password
  3. The built-in nginx-proxy and acme-companion will automatically obtain and renew an independent SSL certificate for the subdomain.

Option C: Host-Level Nginx / Custom Port (Port 3001)

If you run HROOT with an external host-level Nginx (e.g. using docker/overrides/app-only.yml or a Bare-Metal installation):

  1. The gateway container binds internally to host port 127.0.0.1:3001.
  2. Add a location proxy block to your host Nginx configuration: 
    location /sms-gateway/ {
    proxy_pass http://127.0.0.1:3001/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location = /sms-gateway {
    return 301 $scheme://$http_host/sms-gateway/;
}

5. Pairing the Smartphone (Server Mode)

To send SMS messages using either Server Option A, B, or C, you must pair an Android smartphone:

  1. Install App: Install the official Android SMS Gateway app on your Android device (available via Google Play Store, F-Droid, or sms-gate.app releases).
  2. Grant Permissions: Ensure that Android system permissions for sending SMS and background battery activity are granted.
  3. Configure Private Server in App:
    • Open the app on your Android device.
    • Go to Settings -> Private Server (or Cloud Server).
    • Server URL:
      • For Subpath (Option A): https://your-hroot-domain.com/sms-gateway
      • For Subdomain (Option B): https://sms.your-hroot-domain.com
    • Private Token: Enter the SMS_GATEWAY_PRIVATE_TOKEN generated during bin/install or from your .env.
    • Tap Connect / Save.
  4. Enter API Credentials in hroot:
    • Once connected, the app generates and displays an API Username and Password.
    • Open the hroot Web Wizard at /setup (under the SMS Gateway tab) or edit .env:
      • Enter SMS_GATEWAY_API_USERNAME (default hroot) and SMS_GATEWAY_API_PASSWORD.
    • Click Save in /setup.
  5. Test Connection & Live Status:
    • On the /setup page, use the Send Test SMS input field to send a test message to your mobile number.
    • In the hroot administration panel under Site Settings > Communication (/options/communication), you can observe the real-time device connection status (Online/Offline, battery, last seen timestamp).

6. Option D: Local Server Mode (No Gateway Server Container Needed)

If both your hroot server and the Android phone reside on the same local network/WiFi (e.g. local developer machine or local university lab network), you can completely bypass hosting a gateway server container. The smartphone app itself starts a built-in web server.

  1. In the Android SMS Gateway app settings, enable Local Server mode.
  2. The app will generate and display:
    • A local HTTP address (e.g. http://192.168.1.50:8080)
    • A random Username
    • A random Password
  3. Configure your hroot .env file to point directly to the phone: 
    COMPOSE_PROFILES=
SMS_FEATURE_ENABLED=true
SMS_SEND_MODE=api
SMS_GATEWAY_API_URL=http://192.168.1.50:8080/message
SMS_GATEWAY_API_USERNAME=<Username_from_app>
SMS_GATEWAY_API_PASSWORD=<Password_from_app>
  4. hroot will now send POST requests directly to the phone's IP address. No background docker container or server setup is required.

7. Developer Interception (Non-Production)

In development or staging environments, real SMS and Push notifications are intercepted to avoid spamming actual phone numbers:

  • SMS Interception: Configured via SMS_INTERCEPTOR_NUMBER in .env.
  • Push Interception: Configured via INTERCEPTOR_EMAIL in .env.
  • When active, real outbound messages are blocked, and notification payloads are printed directly to the environment logs for verification.