Notifications

Your agents work while you're away — watching a price, digesting an inbox, waiting for an OTP. Notifications are how they reach you: when something needs your approval, when a task finishes, when an email lands, or when a deal you asked about actually drops. You get pinged even when the app is closed, on whichever channel you've set up.

The channels

pocket agent can reach you three ways, and it uses all of the ones you've enabled at once:

Channel	Reaches	How you turn it on
Telegram	Your Telegram chat with the bot	Open the app inside Telegram — it links automatically
Web Push	Desktop web, installed PWA, mobile web	Settings → Enable notifications
Native push	The iOS / Android app	Grant the permission prompt on first launch

Each channel is independent and fail-soft: if a channel isn't configured on the server, or a particular send fails, it's quietly skipped. Notifications are always best-effort and run off to the side — a failed push can never break a payment or an agent run.

How a notification reaches you

When something notable happens, the backend calls one function that fans the message out to every channel you've got:

The fan-out is parallel and non-blocking. Dead subscriptions (a browser that cleared its data, an uninstalled app) are pruned automatically when the push service reports them gone.

What triggers a notification

Notifications are tied to real events, not noise. The main triggers:

Event	Example message
Approval needed	🛒 Your agent wants to buy: Nike Pegasus · $128 — open Approvals to approve or deny.
Purchase complete	🛍️ Order confirmed — $128.00
Agent update (during a run)	🤖 Shopper: found 3 options under your budget, comparing now…
Reminder (you asked the agent to remind you)	⏰ Reminder: renew the domain
Email received (an agent's inbox)	📧 Shopper got an email from orders@store.com — "Your receipt"
Identity check (KYC)	✅ Your identity check passed — you can finish setting up your card.
Referral reward	💰 Someone you invited funded their first card — +100 GOLD
Deals / price drops / back-in-stock	Sent by background tasks via the agent's notify ability

Approvals and purchases are the ones you'll notice most: an agent completes everything up to the moment money moves, then pings you so you can approve with a single tap. See Security & control for how approvals keep you in charge.

Telegram

pocket agent runs as a Telegram Mini App, so once you've opened it inside Telegram, the bot can message you directly.

• Linking is automatic and secure. When you open the app in Telegram, it sends Telegram's signed initData to the backend, which verifies the HMAC signature before trusting your chat ID. This is the only trusted source of your chat ID — a client can't claim to be someone else and hijack their notifications.
• It's a one-time setup and earns you 30 GOLD the first time you link (see GOLD & referrals).
• After linking, the bot sends you plain messages for every event above — no need to have the app open.

Web Push (web & PWA)

Web Push delivers notifications to your browser or installed PWA, even when the tab or app is closed. Turn it on from Settings → Enable notifications:

Get pushes for approvals, reminders and agent updates — on this device, even when the app is closed.

What happens when you enable it:

1. The app asks the browser for notification permission (this must be from your tap — a browser requirement).
2. It subscribes your browser against the app's public VAPID key and registers that subscription with the backend.
3. From then on, the backend can push to this browser; the service worker shows the notification, and tapping it focuses the app (or opens it) at the right screen.
4. You earn 20 GOLD the first time (one-time).

Enrollment is per browser / per device — enable it on each device you want pinged. In Settings you'll see whether it's On, with a Turn off option. If notifications are blocked at the browser level, the app tells you plainly:

Notifications are blocked in your browser settings. Allow them for this site to turn them on.

iOS needs the PWA installed

On iPhone and iPad, Web Push only works once you've added pocket agent to your Home Screen (iOS 16.4+). Install the PWA first (Share → Add to Home Screen), then enable notifications from inside the installed app.

Native push (iOS & Android)

The native apps use the operating system's own push. On first launch (once you're signed in) the app asks for notification permission; if you grant it, the app registers the device's push token with the backend, and delivery flows through the Expo Push Service → APNs (iOS) / FCM (Android). Notifications show even while the app is in the foreground. This also grants the one-time 20 GOLD for enabling notifications.

Managing notifications

Everything lives under Settings → Notifications:

• Enable / turn off push for the current device.
• A clear state when the browser or OS has blocked notifications, with what to do about it.
• Telegram linking happens automatically when you use the Telegram Mini App — there's no separate switch.

Turning push off unsubscribes just that device; your other channels and devices keep working.

Privacy & safety notes

• Chat IDs are verified, never trusted blindly. Your Telegram chat ID is only accepted after the signed initData HMAC check passes — the app never takes a chat ID from the client at face value.
• No raw secrets stored for push. Web Push subscriptions are keyed by their endpoint and refreshed on change; dead ones are pruned automatically.
• Notifications never carry an action you didn't start. A push can tell you an approval is waiting, but approving still happens inside the app, by you. Agents running in the background can send you updates but cannot move money or do anything irreversible on their own — that always waits for your tap. See Security & control.

Configuration status

Notifications are feature-gated on the server and degrade gracefully:

Channel	Enabled by	When unset
Telegram	TELEGRAM_BOT_TOKEN	No-op (other channels still work)
Web Push	VAPID_PUBLIC + VAPID_PRIVATE	Web/PWA push unavailable; the Settings toggle reports it's not configured yet
Native push	Expo credentials (provisioned at EAS build)	Native push unavailable

With none configured, the app works exactly as before — you just won't get pinged outside it.

Related

• Platforms — where each channel is available.
• Security & control — approvals, spend limits, and what agents can't do unattended.
• GOLD & referrals — linking Telegram and enabling push both earn GOLD.