# Notification Service


The Notification Service provides a streamlined, configuration-driven approach

This guide covers what the Notification Service is, how it differs from the A2U API and Messenger-based notifications, how to set up and configure notifications, notification types, scheduling options, API details, and best practices.

## What Is the Notification Service?

The Notification Service is a managed notification system built into the Facebook Instant Games platform. It abstracts away much of the complexity of sending notifications by providing:

- **Pre-defined notification types** for common game events
- **Built-in scheduling** so you can set up recurring or delayed notifications without running your own cron jobs
- **Platform-managed delivery** with automatic rate limiting and optimization
- **Integration with the Instant Games SDK** for player opt-in and delivery

The Notification Service sits between the simplicity of in-game [Custom Updates](https://developers.facebook.com/documentation/games/retain/custom-updates) (which require the player to be in-game) and the full flexibility of the [A2U API](https://developers.facebook.com/documentation/games/retain/notifications/a2u-api) (which requires server-side integration). It is a good fit for games that want reliable, scheduled notifications without building a full notification backend.

## How It Differs from A2U and Messenger

| Aspect | A2U API | Game Updates (Messenger) | Notification Service |
|--------|---------|--------------------------|---------------------|
| **Management** | You manage everything (timing, targeting, sending) | You manage through Messenger bot | Facebook manages delivery infrastructure |
| **Setup** | Build server-side API integration | Build Messenger bot + webhook | Configure in App Dashboard + SDK calls |
| **Scheduling** | You build your own scheduler | You build your own scheduler | Built-in scheduling |
| **Rate limiting** | You must track and respect limits | Messenger platform manages | Platform manages automatically |
| **Customization** | Full control over content and timing | Full control over content and templates | Defined notification types with customization |
| **Best for** | Complex, data-driven notification strategies | Rich, conversational experiences | Standard notification patterns with minimal server work |

## Setting Up the Notification Service

### Step 1: Configure in the App Dashboard

1. Open the [App Dashboard](https://developers.facebook.com/apps/).
2. Select your app and navigate to **Instant Games** > **Details**.
3. Find the **Notifications** section.
4. Enable the Notification Service for your game.
5. Configure the notification types you want to use (see Notification Types below).

### Step 2: Implement Player Opt-In

Players must opt in to receive notifications. Use the SDK to manage the opt-in flow:

```javascript
async function setupNotifications() {
  try {
    const canSubscribe = await FBInstant.player.canSubscribeBotAsync();

    if (canSubscribe) {
      // Show the player a prompt explaining the value of notifications
      const shouldSubscribe = await showNotificationOptInPrompt();

      if (shouldSubscribe) {
        await FBInstant.player.subscribeBotAsync();
        console.log('Player subscribed to notifications');
      }
    }
  } catch (error) {
    console.error('Notification setup failed:', error);
  }
}
```

### Step 3: Schedule Notifications

Once the player has opted in and you have configured your notification types, you can schedule notifications through the SDK or API.

## Notification Types

The Notification Service supports several notification types designed for common game re-engagement scenarios.

### Idle Player Notification

Sent to players who have not played for a configurable period. This is one of the most effective notification types for re-engaging lapsed players.

**Configuration:**
- **Trigger:** Player has been inactive for X hours/days
- **Message:** Customizable text (e.g., "Your daily reward is waiting!")
- **Deep link:** Where in the game the player should land

### Game Event Notification

Sent when a specific game event occurs, such as a tournament starting, a friend beating a score, or a new content release.

**Configuration:**
- **Trigger:** Server-side event or scheduled time
- **Message:** Event-specific text with personalization tokens
- **Deep link:** Event-specific landing screen

### Scheduled Notification

Sent at a specific time, either once or on a recurring schedule. Useful for daily reminders, weekly events, or time-based game mechanics.

**Configuration:**
- **Schedule:** One-time or recurring (daily, weekly, custom)
- **Time:** Specific time of day (can be adjusted for player's time zone)
- **Message:** Customizable text
- **Deep link:** Relevant game screen

### Social Notification

Sent when a social event relevant to the player occurs, such as a friend starting to play the game or a friend's score change.

**Configuration:**
- **Trigger:** Friend activity (new player, score update, challenge)
- **Message:** Social context with friend names
- **Deep link:** Social feature screen (leaderboard, challenge, etc.)

## Scheduling Notifications

### Using the Server-Side API

For more complex scheduling scenarios, you can use the server-side API to schedule notifications:

```javascript
// Node.js server example
async function scheduleServerNotification(playerId, notification) {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/${playerId}/notifications`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        access_token: APP_ACCESS_TOKEN,
        template: notification.message,
        href: notification.deepLink,
        schedule_time: notification.scheduledTime, // Unix timestamp
      }),
    }
  );

  const data = await response.json();
  return data;
}

// Example: Schedule a tournament start notification for tomorrow at noon
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
tomorrow.setHours(12, 0, 0, 0);

scheduleServerNotification('player_12345', {
  message: 'The Weekend Tournament starts now! Compete with friends for the top spot.',
  deepLink: '/tournament',
  scheduledTime: Math.floor(tomorrow.getTime() / 1000),
});
```

### Canceling Scheduled Notifications

If a scheduled notification is no longer relevant (e.g., the player returned before the reminder was sent), you can cancel it:

```javascript
async function cancelScheduledNotifications() {
  try {
    await FBInstant.notifications.cancelScheduledAsync();
    console.log('Scheduled notifications cancelled');
  } catch (error) {
    console.error('Failed to cancel notifications:', error);
  }
}
```

A common pattern is to cancel pending notifications at the start of each game session, then schedule new ones as needed:

```javascript
async function onGameSessionStart() {
  // Cancel any pending notifications since the player is here now
  await cancelScheduledNotifications();

  // ... game logic ...
}

async function onGameSessionEnd() {
  // Schedule a reminder for the next relevant event
  await scheduleReminder(
    14400, // 4 hours
    'Your energy is fully recharged! Come back and play.',
    { type: 'energy_full' }
  );
}
```

## Handling Notification Entry

When a player taps a notification and enters your game, you can read the notification payload to determine what action to take:

```javascript
async function handleNotificationEntry() {
  await FBInstant.initializeAsync();

  const entryPointData = FBInstant.getEntryPointData();

  if (entryPointData) {
    try {
      const data = typeof entryPointData === 'string'
        ? JSON.parse(entryPointData)
        : entryPointData;

      switch (data.type) {
        case 'energy_full':
          showGameplayScreen();
          break;
        case 'tournament_start':
          showTournamentLobby();
          break;
        case 'daily_reward':
          showDailyRewardScreen();
          break;
        case 'friend_score':
          showLeaderboard();
          break;
        default:
          showMainMenu();
      }
    } catch (parseError) {
      showMainMenu();
    }
  } else {
    showMainMenu();
  }

  await FBInstant.startGameAsync();
}
```

## Rate Limits

The Notification Service enforces rate limits automatically to protect the player experience:

- **Per-player daily limit:** A maximum number of notifications can be delivered to a single player per day. The platform manages this limit; excess notifications are queued or dropped.
- **Frequency optimization:** The platform may adjust delivery timing to optimize for player engagement (e.g., delivering at times when the player is most likely to be active).
- **Aggregate limits:** Your app has an overall daily notification budget that scales with your active user count.

Because the platform manages rate limiting automatically, you do not need to build your own rate limiting logic. However, you should still be thoughtful about how many notifications you schedule -- scheduling more notifications than necessary wastes processing and may result in lower-priority notifications being dropped.

## Next Steps

- **[Notification Best Practices](https://developers.facebook.com/documentation/games/retain/notifications/best-practices)** -- Consolidated best practices across all notification channels.
- **[Notification Guidelines](https://developers.facebook.com/documentation/games/retain/notifications/notification-guidelines)** -- Content formatting and quality criteria for notification messages.
- **[A2U API](https://developers.facebook.com/documentation/games/retain/notifications/a2u-api)** -- Full control over notification sending from your server.
- **[Game Updates via Messenger](https://developers.facebook.com/documentation/games/retain/notifications/game-updates-messenger)** -- Rich, interactive messages through Messenger.
- **[Notifications Overview](https://developers.facebook.com/documentation/games/retain/notifications/overview)** -- Compare all notification channels.
- **[Home Screen Shortcut](https://developers.facebook.com/documentation/games/retain/home-screen-shortcut)** -- Another powerful retention tool: getting your game on the player's home screen.