​
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. 
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 message becomes:
🧑‍🍳 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 15% 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 Interface in the Developer Portal

​
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?