Notifications
Features & Guidelines
Guidelines
To maintain high-quality notifications, please adhere to the following guidelines:
- Notifications should be purely functional, not marketing-related.
- Notifications must be directly related to the mini app.
- Notifications must be relevant to the user.
Username Substitution
It's extremely easy to personalize your notifications, by using usernames.
Use the special string ${username} in your notification message, and it will substitute in
the recipient's username.
Request
curl -X POST "https://developer.worldcoin.org/api/v2/minikit/send-notification" \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"app_id": "app_id",
"wallet_addresses": ["0x123", "0x456"],
"title": "title",
"message": "đ§âđŗ We're cooking something special for you ${username}",
"mini_app_path": "worldapp://mini-app?app_id=[app_id]&path=[path]"
}'
when sent to users, the messagebecomes:
đ§âđŗ We're cooking something special for you mistico
đ§âđŗ We're cooking something special for you tute
đ§âđŗ We're cooking something special for you struck
and so on.
Notification Badges
If a user has pending notifications for your miniapp, and you maintain a 7 day rolling average open rate of 10% or higher, we'll show a badge on the user's home screen, next to your miniapp's icon.
It's cleared once the miniapp is opened.
Notification badges increase your miniapp's visibility on the home screen, leading to higher user engagement and traffic.
Notification Quality Enforcement
Given that notifications can be disruptive and reflect negatively on the entire miniapp ecosystem, we enforce additional rules based on open rates. If your miniapp's notification permissions are enabled, we evaluate your notification open rates weekly (from May 5th 2025 on).
If your miniapp's 7 day rolling average is less than 10%, we will pause any further notifications for a week. This is a signal for you to rethink your strategy. After the pause, your permissions will be resumed, and up for reevaluation the following week.
Open Rate Goal
An excellent goal to aim for is a 25% open rate. This % means your notifications drive strong traffic to the miniapp. You can see this stat in your dashboard in Developer Portal .
Use Emoji & Curiosity in Titles
Increases visual salience and emotion.
Examples:
đĨ You're missing out on rewards
đšī¸ A new level just unlocked
đ¤ What's waiting inside the vault today?