Permitted notification types
All notifications must be tied to a specific action the user already took inside your Mini App, or an alert the user explicitly configured. The outcome must have resolved after the user left the app. If the user saw the result in your UI, no notification is needed.| Type | Rules | Examples |
|---|---|---|
| Event-driven | Triggered by a specific user action where the outcome resolved after they left the Mini App. | Allowed: Tournament the user entered ended while away; reward credited hours after a quest. Not allowed: “Tournament is now live” sent to all users (broadcast). |
| Status updates | Progress or completion of a user-initiated flow that resolved after they left. | Allowed: NFT minted after a multi-step process; order fulfilled hours later. Not allowed: “Step 2 of 5 complete” (micro-step within an active flow). |
| Time-sensitive alerts | Only for actions the user explicitly opted into within the Mini App. | Allowed: Price alert the user set; reminder the user configured. Not allowed: “Tournament ends Sunday” sent to all participants without prior opt-in. |
| Promotional: in-app offers | Your Mini App’s own in-app discounts, offers, and sales. First-party only, sent to users who have added your Mini App and enabled notifications. | Allowed: “20% off power-ups this weekend”; “Season pass is half price today.”, “The tournament you signed up for is now live.” Not allowed: third-party or cross-promo offers |
Core principle: Notifications are for events the user missed, not events the user witnessed. Use your in-app UI for real-time feedback; use notifications as the asynchronous catch-up channel for when the user is away.
Prohibited content
| # | Prohibited | Clarification |
|---|---|---|
| 1 | Financial advice or recommendations | Investment recommendations, yield projections, and price predictions. Factual status updates about the user’s own position are allowed (e.g., “Your vault APY changed from 5% to 3%“). |
| 2 | Impersonation of Startale | Mimicking Startale system notifications (e.g., fake “Funds received” or “Security alert”). |
| 3 | Offensive or illegal content | Hateful, discriminatory, or illegal content of any kind. |
| 4 | Deceptive content | False urgency, fake scarcity, misleading CTAs, misinformation. |
| 5 | Third-party promotions | Affiliate offers or cross-promotions from entities other than your own Mini App. |
Content format requirements
Payloads that violate character limits or contain prohibited formatting are rejected at ingestion with HTTP 400.| Field | Limit | Rules |
|---|---|---|
| Title | 32 chars | Plain text only. Sentence case. Must clearly describe the event. Do not repeat your Mini App name; it is already shown as the sender. |
| Body | 128 chars | Plain text only. No HTML or markdown. Include the key information the user needs to decide whether to tap through. |
| Target URL | Its origin must match your Mini App’s registered domain (senderId). A non-matching targetUrl is not delivered to that recipient (its token comes back in invalidTokens). | |
| Emoji | Max 1 per field | One emoji allowed in the title and one in the body. No emoji-only content. Emoji must not replace words. |
| Exclamation marks | Max 1 total | One across the entire notification (title + body combined). |
| ALL CAPS | Prohibited | No fully-capitalized words, except a short allow-list of recognized abbreviations (currently ETH, USDC, NFT). |
Examples: good vs. bad notifications
Examples: good vs. bad notifications
Good:
- Title: “Tournament ended” / Body: “You placed 3rd in the weekly tournament. 50 USDC reward credited to your wallet.”
- Title: “NFT minted” / Body: “Your Genesis Pass NFT has been minted. Tap to view in your collection.”
- Title: “Price alert triggered” / Body: “ETH dropped below $2,000, the threshold you set on March 15.”
- Title: “DON’T MISS THIS!!!” / Body: “CLAIM YOUR REWARD NOW BEFORE IT EXPIRES!!!” (all caps, multiple exclamation marks, false urgency)
- Title: “MiniGame: Update” / Body: “Check out what is new in MiniGame!” (Mini App name in title, vague, promotional)
- Title: "" / Body: “[emoji-only content]” (empty title, emoji-only body)
Rate limits
NS enforces the limits below. When a recipient is throttled, its token comes back in therateLimitedTokens array of the send response. There is no separate error code, reason, or Retry-After returned to the sender. Retry later with backoff; don’t hammer.
| Layer | Limit |
|---|---|
| Per-(user, Mini App) daily cap | 10 notifications per user per day |
| Per-Mini-App fan-out | 500 unique recipients / minute |
senderId), not per company. Both limits are enforced inside NS and surface only through rateLimitedTokens. An additional API gateway (Kong) rate-limit layer is planned but not yet live; when it ships it will cap raw requests per IP/domain (1,000 per minute with a 50-per-second burst cap) and return HTTP 429.
Frequency guidance
- There is no recommended weekly cap. Every permitted notification type is user-initiated or user-opted-in, so volume scales naturally with user activity.
- Quality over quantity. Only notify for meaningful state changes the user would care about. Don’t notify for micro-steps within a flow (“Step 2 of 5 complete”) or for confirmations the user already saw in your UI.
- The hard ceiling above (10 notifications per user per day, per Mini App) is the actual limit.
- Health signal: if your Mini App’s mute rate exceeds 20% of users within 7 days of their first notification, your notifications likely aren’t relevant enough. In v2, mute rates above 30% will trigger automatic review.
User opt-out
- You must stop sending to a user immediately upon receiving a
notifications_disabledorminiapp_removedwebhook event. - Attempting to re-subscribe a user who has opted out is a violation and grounds for immediate suspension.
- NS does not expose per-user mute state to senders. You only see per-token outcomes in the send response (
successfulTokens/invalidTokens/rateLimitedTokens). Treat the lifecycle webhooks as the source of truth and don’t try to probe or work around delivery state.
Language
- Notifications should be in English.
- If your Mini App has a Japanese version, we highly recommend sending its notifications in Japanese.
Partner onboarding
- You must review and sign off on this policy before sending notifications in production.
- There is no separate notification allow-list to apply for. A Mini App that ships in Startale App is already registered with the backend, so notification access activates as soon as your backend implements the webhook and stores the per-user tokens NS delivers. Coordinate production rollout timing with your Startale contact.
- There is no API key. Notification access works through the per-user tokens NS delivers to your backend via the webhook. Treat those tokens as secrets: store them server-side and never share or reuse them across Mini Apps.
Payload validation
- Title: 32 characters max. Body: 128 characters max. Payloads exceeding these are rejected with
HTTP 400. - Title and body are plain text only. HTML and markdown are not supported.
targetUrl’s origin must match your Mini App’s registered domain (senderId). NS compares the host (and the path prefix, if yoursenderIdincludes a path); it does not enforce the URL scheme. AtargetUrlthat does not match is not rejected with a400. Instead that recipient’s token is returned ininvalidTokensand the notification is not delivered to it.- Use a stable
notificationIdper send. NS dedupes on it: re-sending the samenotificationIdto the same user does not deliver twice, so reuse the same id on retries. It is not returned in the send response.
Violation consequences
Notifications that breach this policy may result in warnings, temporary suspension, or permanent revocation of your notification access, depending on the severity and frequency of the violation. Serious abuse, such as impersonating Startale, security abuse, or illegal content, may lead to immediate suspension. The detailed enforcement process is still being finalized. Reach out to your Startale contact with any questions.Recalling a notification
You can recall a notification within 5 minutes of sending through the API, using itsnotificationId. Recall is best-effort: pushes already delivered to a device remain on the device; only the in-app inbox copy is suppressed. Use it for misfire recovery only (wrong cohort, content bug, typo caught immediately); it is not a moderation tool.