Notification API Reference

Send a Ding to all subscribers of a channel. For any channel other than the system ding channel, only the channel owner may broadcast.

curl -X POST https://go.ding.fyi/broadcast \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"topic":"my-channel","title":"Doors open!","message":"Come on in 🎉"}'

{
  "success": true,
  "notification": { "id": "…", "title": "Doors open!", "channel": "my-channel", "openCount": 0, "readCount": 0 },
  "broadcast": { "success": true, "messageId": "projects/…/messages/…" }
}

Legacy: create a Ding on the system ding channel and push it to everyone. Accepts title, message, imageUrl, attachments (defaults: "Proximity Alert" / "Wristband outside of designated area."). Prefer /broadcast.

Schedule a future broadcast. Non-ding channels must exist and be owned by you.

{ "success": true, "scheduledNotification": { "id": "…", "status": "pending", "scheduledAt": "2026-07-25T09:00:00.000Z", "timeType": "global" } }

List your pending scheduled Dings. Returns {"success": true, "scheduled": […]}.

List your scheduled Dings that have already fired (status: "sent") — useful for syncing a Sent box. Returns {"success": true, "sent": […]}.

Reschedule a pending Ding you created. Body: {"id": "…", "scheduledAt": "…", "timeType"?: "local"|"global"} — only the schedule is mutable. 403 if you're not the creator.

Cancel a scheduled Ding you created. Body: {"id": "…"}.

List notifications, newest first. Targeted notifications addressed to another user are filtered out. Items include engagement fields: openCount, readCount, sponsorClickCount, and reactions (map of emoji → user IDs).

curl https://go.ding.fyi/notifications -H "Authorization: Bearer $TOKEN"

Fetch one notification. Content-negotiated: API clients get JSON (enriched with channelName and channelAvatar); browsers (Accept: text/html) get a shareable landing page that deep-links into the app.

Attach free-text notes to a notification. Body: {"id": "…", "notes": "…"}.

Delete one notification (and its read-tracking data). Body: {"id": "…"}. Only the notification's creator or the channel owner may delete — otherwise 403.

Mark a notification opened/read by the calling user. Idempotent per user — only the first open increments the counters. Optional body: {"source": "app"}. Returns the updated openCount / readCount.

Toggle an emoji reaction. Body: {"emoji": "👍"}. Calling again with the same emoji removes your reaction. Returns the full reactions map.

Record a sponsor-link click. Optional body: {"link": "…", "sponsorText": "…", "source": "app"} (falls back to the notification's sponsor data). Not idempotent — every call counts a click.

Full analytics for a Ding: counts, per-user opens, sponsor-click users, and the 50 most recent sponsor clicks. Only the sender or the channel owner may view — otherwise 403.

Bulk read-state check: pass up to 50 comma-separated IDs, get back {"success": true, "readIds": […]} — the subset the calling user has opened.

List channels. Private channels are hidden unless you own them. Query params:

Create a channel you own; you're auto-subscribed as owner. Returns 201 with the full channel including joinUrl and a qrCode data URL, or 409 if the name is taken.

Permanently delete a channel you own, plus all of its notifications and scheduled Dings. 403 if you're not the owner. No undo.

Subscribe the calling user; also subscribes their registered FCM tokens to the channel's push topic. Optional body: {"timezone": "America/New_York"} (used if your profile has no timezone). Idempotent.

Remove the calling user and detach their device tokens from the channel's push topic. No body required.

Compact list of channels you're subscribed to — {"channels": [{"id", "name", "avatarUrl"}]}. Handy for re-subscribing FCM topics on a new device. (Not billing — see Plans & Billing.)

Shareable HTML landing page for a channel with an "Open in app" deep link. This is the URL encoded in each channel's QR code — meant for humans, not API clients.

Register an FCM device token for the calling user and subscribe it to the topics of every channel they already follow. Body: {"token": "…"}. Duplicates are ignored.

Remove a token (e.g. on sign-out) and unsubscribe it from all channel topics. Body: {"token": "…"}.

Your full profile, including plan and subscription fields. 404 with {"success": false, "profile": null} if no profile exists yet.

Create or update your profile. First-time creation also triggers a welcome Ding, a welcome email, and auto-subscription to the #ding channel.

Limited public profile of any user: name, age range, location, timezone. No email.

Update just your timezone. Body: {"timezone": "America/New_York"}. Propagates to your subscriber entries across channels in the background.

GDPR-style data export: your profile, subscription summary, owned channels, and usage stats in one JSON payload.

Permanently delete your account and all associated data — owned channels, notifications, scheduled Dings, subscription records, and the Firebase Auth user. If the response includes "clientAuthDeleteRequired": true, the client must finish deleting the Auth user itself.

File a support ticket. Body: {"name", "email", "subject", "message", "category"?}. Returns {"success": true, "ticketId": "…"}.

Liveness check. Returns {"status": "healthy", "timestamp": "…"}.

The plan catalog: keys, product IDs, tiers, intervals, prices, entitlements, and whether Stripe direct purchase is available per plan.

Your effective plan, subscription status, and entitlements. Query params: includeTransactions (default true; pass false to skip) and limit (1–50, default 10) for recent purchase transactions.

Create a Stripe Checkout session for a plan. Body identifies the plan (e.g. {"planKey": "starter_monthly"}). Redirect the user to the returned url; plan activation happens via webhook after payment.

Create a Stripe Billing Portal session (manage/cancel a web subscription). Returns {"url": "…"}. Requires an existing Stripe customer.

Server Stripe configuration summary — use to detect test vs. live mode and whether web checkout is enabled.

Report a native in-app purchase or restore for server-side verification. Requires platform ("ios" | "android") plus plan and store receipt/token fields. Returns verification status, updated entitlements, and the recorded transaction. 402 if verification fails.

Send a rich HTML share email for a channel or Ding. Body: {"toEmail", "shareType", "channelName", "link"} required; dingTitle, dingMessage, dingTimestamp, attachments optional. Your email address is never exposed to the recipient.

Email a channel's invite QR code. Body: {"channelId", "channelName", "inviteUrl"} required, toEmail optional (defaults to your email). 403 unless you own the channel.