Notifications

Get notified when sessions need input, request permissions, fail, or complete — via native app notifications, Telegram, Server酱 (ServerChan), Web Push, or voice.

Web Push needs no provider configuration: install the PWA and allow notifications. The channels below are optional.

Native app notifications

See Native apps for build, pairing and platform requirements.

For official Android and iOS apps, pair an updated hub and allow notifications. No Firebase project or Apple developer account is needed. Notification content is end-to-end encrypted through the official push relay, which also works when you access the hub through Tailscale or your own HTTPS setup. Android requires Google Play services and FCM connectivity.

Private app builds need matching Firebase/APNs credentials. An Android build without Firebase configuration has no FCM push. For a self-signed iOS build, the signing account, bundle ID and APNs environment must match the provider configuration; the official relay cannot deliver to an arbitrary self-build. See the native push contract for settings and delivery details. This push relay is independent of the --relay network tunnel.

Telegram Setup

Enable Telegram notifications and Mini App access:

1. Message @BotFather and create a bot
2. Set the bot token and public URL
3. Start the hub and bind your account

export TELEGRAM_BOT_TOKEN="your-bot-token"
export HAPI_PUBLIC_URL="https://your-public-url"

hapi hub

Then message your bot with /start, open the app, and bind using CLI_API_TOKEN:<namespace> (for example, your-token:default).

Related environment variables:

• TELEGRAM_NOTIFICATION - Enable/disable Telegram notifications (default: true)

Troubleshooting:

• If binding fails, verify HAPI_PUBLIC_URL is accessible from the internet
• Telegram Mini App requires HTTPS (not HTTP)

ServerChan (Server酱) Setup

Server酱 pushes notifications to WeChat and other channels. The hub sends ServerChan messages when a session is ready for input, requests a permission, a task fails, or a session completes.

1. Get a SendKey from sct.ftqq.com
2. Set the SendKey and start the hub:

export SERVERCHAN_SENDKEY="your-sendkey"
export HAPI_PUBLIC_URL="https://your-public-url"

hapi hub

Messages include a link back to the session, built from HAPI_PUBLIC_URL.

Related environment variables:

• SERVERCHAN_NOTIFICATION - Enable/disable ServerChan notifications (default: true)
• SERVERCHAN_BACKGROUND_ONLY - Only send ServerChan notifications when the namespace has no visible HAPI connection (default: false)

When SERVERCHAN_BACKGROUND_ONLY=true, a visible HAPI connection suppresses ServerChan for the entire namespace. Hidden, disconnected, or closed HAPI pages do not count as visible, so ServerChan can act as a background fallback. This is namespace-wide and does not select a particular device.

These values can also be set in settings.json (serverChanSendKey, serverChanNotification, serverChanBackgroundOnly).

Voice assistant setup

Enable voice control:

1. Get an API key from elevenlabs.io
2. Set the environment variable:

export ELEVENLABS_API_KEY="your-api-key"
hapi hub --relay

See Voice Assistant for usage details.