Notifications

Updated: Mar 25, 2026

Notifications let you reach players outside of active game sessions — to bring them back for a new challenge, notify them that it is their turn, or re-engage lapsed players. Under Zero Permissions, the notification system uses player IDs (instead of App-Scoped User IDs) and app access tokens (instead of user access tokens), making it simpler and more consistent with the rest of the SDK.

How Notifications Are Delivered

Notifications can reach players through three channels. Facebook automatically filters notifications to prevent spam — not every notification you send will be delivered to every channel.

Channel	Description
Messenger bot message	Delivered as a bot message if your game has a configured bot and the player has subscribed to it.
Facebook Jewel	Appears in the Facebook notification bell (the "jewel" icon in the top navigation).
Gaming Tab	Appears in the Facebook Gaming Tab notification area.

Sending Notifications

All notification APIs use the Gaming Domain Graph API at graph.fb.gg with an app access token. Request bodies must be JSON-formatted.

Send a Notification

Endpoint:POST graph.fb.gg/{app_id}/notifications

Headers:

Content-Type: application/json

Query parameter:access_token={app_access_token}

Body parameters:

Parameter	Required	Description
player_id	Yes	The player's game-scoped ID (from FBInstant.player.getID()).
message	Yes	Content object with title, body, and optional media_url.
label	No	A label to group similar notification types. Used for filtering when cancelling.
payload	No	Custom data attached to the game URL. When the player taps the notification, this data is accessible in the launched game session.
schedule_interval	No	Delay in seconds before delivery. Range: 300–2,592,000 (5 minutes to 30 days). Maximum 5 pending scheduled notifications per recipient.
bot_message_payload_elements	No	Advanced bot message XMA configuration for richer Messenger bot messages.

Example request:

curl -X POST "https://graph.fb.gg/{app_id}/notifications?access_token={app_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "player_id": "8504197016307157",
    "message": {
      "title": "Your turn!",
      "body": "Your opponent just played. Come back and take your turn!",
      "media_url": "https://example.com/images/notification.png"
    },
    "label": "turn_reminder",
    "payload": "{\"contextID\": \"abc123\"}"
  }'

Schedule a Notification

To send a notification with a delay, include the schedule_interval parameter:

{  
  "player_id": "8504197016307157",  
  "message": {  
    "title": "We miss you!",  
    "body": "Your daily challenge is waiting. Come back and play!"  
  },  
  "label": "daily_challenge",  
  "schedule_interval": 86400  
}

This schedules the notification for delivery 24 hours (86,400 seconds) later. You can have at most 5 pending scheduled notifications per recipient.

Cancel Scheduled Notifications

Endpoint:POST graph.fb.gg/{app_id}/notifications_cancel_all

Parameter	Required	Description
player_id	Yes	The player whose scheduled notifications should be cancelled.
label	No	If provided, only cancels notifications with this label. If omitted, cancels all pending scheduled notifications for the player.

Example — cancel all scheduled notifications for a player:

curl -X POST "https://graph.fb.gg/{app_id}/notifications_cancel_all?access_token={app_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "player_id": "8504197016307157"
  }'

Example — cancel only turn reminders:

{  
  "player_id": "8504197016307157",  
  "label": "turn_reminder"  
}

Setting Up Bot Messages (Optional)

To enable richer notifications through Messenger bot messages:

• Create a game bot on the App Dashboard.
• Request pages_messaging permissions through App Review.
• Players subscribe to your bot via FBInstant.player.subscribeBotAsync() in your game.

A webhook is no longer required for bot message delivery. Once the bot is configured and a player is subscribed, notifications automatically include bot messages in Messenger.

Migration from Existing Notification APIs

If you previously used the App-to-User Notifications Graph API with App-Scoped User IDs:

• Existing APIs continue to work for players who have App-Scoped User IDs.
• New Zero Permissions-only users do not have App-Scoped User IDs, so the existing API cannot reach them.
• Recommendation: Migrate to the new graph.fb.gg endpoint with player IDs to ensure you can notify all users, regardless of when they started playing.

Next Steps

• Custom Updates, Invites, and Shares — In-session sharing and updates via the SDK.
• API Reference — Full SDK reference including bot subscription methods.
• App Onboarding and Migration — Setup guide for configuring your app.