Expo Notifications

In rare situations, a push token may be changed by the push notification service while the app is running. When a token is rolled, the old one becomes invalid and sending notifications to it will fail. A push token listener will let you handle this situation gracefully by registering the new token with your backend right away.

import React from 'react';
import * as Notifications from 'expo-notifications';

import { registerDevicePushTokenAsync } from '../api';

export default function App() {
  React.useEffect(() => {
    const subscription = Notifications.addPushTokenListener(registerDevicePushTokenAsync);
    return () => subscription.remove();
  }, []);

  return (
    // Your app content
  );
}

Returns a native FCM, APNs token or a PushSubscription data that can be used with another push notification service.

Returns an Expo token that can be used to send a push notification to the device using Expo's push notifications service.

This method makes requests to the Expo's servers. It can get rejected in cases where the request itself fails (for example, due to the device being offline, experiencing a network timeout, or other HTTPS request failures). To provide offline support to your users, you should try/catch this method and implement retry logic to attempt to get the push token later, once the device is back online.

For Expo's backend to be able to send notifications to your app, you will need to provide it with push notification keys. For more information, see credentials in the push notifications setup.

import * as Notifications from 'expo-notifications';

export async function registerForPushNotificationsAsync(userId: string) {
  const expoPushToken = await Notifications.getExpoPushTokenAsync({
   projectId: 'your-project-id',
  });

  await fetch('https://example.com/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      userId,
      expoPushToken,
    }),
  });
}

Removes a push token subscription returned by an addPushTokenListener call.

Listeners registered by this method will be called whenever a notification is received while the app is running.

import React from 'react';
import * as Notifications from 'expo-notifications';

export default function App() {
  React.useEffect(() => {
    const subscription = Notifications.addNotificationReceivedListener(notification => {
      console.log(notification);
    });
    return () => subscription.remove();
  }, []);

  return (
    // Your app content
  );
}

Listeners registered by this method will be called whenever a user interacts with a notification (for example, taps on it).

import React from 'react';
import { Linking } from 'react-native';
import * as Notifications from 'expo-notifications';

export default function Container() {
  React.useEffect(() => {
    const subscription = Notifications.addNotificationResponseReceivedListener(response => {
      const url = response.notification.request.content.data.url;
      Linking.openURL(url);
    });
    return () => subscription.remove();
  }, []);

  return (
    // Your app content
  );
}

Listeners registered by this method will be called whenever some notifications have been dropped by the server. Applicable only to Firebase Cloud Messaging which we use as a notifications service on Android. It corresponds to onDeletedMessages() callback. More information can be found in Firebase docs.

Removes a notification subscription returned by an addNotificationListener call.

A React hook always returns the notification response that was received most recently (a notification response designates an interaction with a notification, such as tapping on it).

If you don't want to use a hook, you can use Notifications.getLastNotificationResponseAsync() instead.

import * as Notifications from 'expo-notifications';
import { Linking } from 'react-native';

export default function App() {
  const lastNotificationResponse = Notifications.useLastNotificationResponse();
  React.useEffect(() => {
    if (
      lastNotificationResponse &&
      lastNotificationResponse.notification.request.content.data.url &&
      lastNotificationResponse.actionIdentifier === Notifications.DEFAULT_ACTION_IDENTIFIER
    ) {
      Linking.openURL(lastNotificationResponse.notification.request.content.data.url);
    }
  }, [lastNotificationResponse]);
  return (
    // Your app content
  );
}

When a notification is received while the app is running, using this function you can set a callback that will decide whether the notification should be shown to the user or not.

When a notification is received, handleNotification is called with the incoming notification as an argument. The function should respond with a behavior object within 3 seconds, otherwise, the notification will be discarded. If the notification is handled successfully, handleSuccess is called with the identifier of the notification, otherwise (or on timeout) handleError will be called.

The default behavior when the handler is not set or does not respond in time is not to show the notification.

import * as Notifications from 'expo-notifications';

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});

When a notification is received while the app is backgrounded, using this function you can set a callback that will be run in response to that notification. Under the hood, this function is run using expo-task-manager. You must define the task first, with TaskManager.defineTask. Make sure you define it in the global scope.

The callback function you define with TaskManager.defineTask will receive an object with the following fields:

• data: The remote payload delivered by either FCM (Android) or APNs (iOS). See PushNotificationTrigger for details.
• error: The error (if any) that occurred during execution of the task.
• executionInfo: JSON object of additional info related to the task, including the taskName.

import * as TaskManager from 'expo-task-manager';
import * as Notifications from 'expo-notifications';

const BACKGROUND_NOTIFICATION_TASK = 'BACKGROUND-NOTIFICATION-TASK';

TaskManager.defineTask(BACKGROUND_NOTIFICATION_TASK, ({ data, error, executionInfo }) => {
  console.log('Received a notification in the background!');
  // Do something with the notification data
});

Notifications.registerTaskAsync(BACKGROUND_NOTIFICATION_TASK);

Used to unregister tasks registered with registerTaskAsync method.

Calling this function checks current permissions settings related to notifications. It lets you verify whether the app is currently allowed to display alerts, play sounds, etc. There is no user-facing effect of calling this.

import * as Notifications from 'expo-notifications';

export async function allowsNotificationsAsync() {
  const settings = await Notifications.getPermissionsAsync();
  return (
    settings.granted || settings.ios?.status === Notifications.IosAuthorizationStatus.PROVISIONAL
  );
}

Prompts the user for notification permissions according to request. Request defaults to asking the user to allow displaying alerts, setting badge count and playing sounds.

import * as Notifications from 'expo-notifications';

export function requestPermissionsAsync() {
  return await Notifications.requestPermissionsAsync({
    ios: {
      allowAlert: true,
      allowBadge: true,
      allowSound: true,
      allowAnnouncements: true,
    },
  });
}

Fetches the number currently set as the badge of the app icon on device's home screen. A 0 value means that the badge is not displayed.

Note: Not all Android launchers support application badges. If the launcher does not support icon badges, the method will always resolve to 0.

Sets the badge of the app's icon to the specified number. Setting it to 0 clears the badge. On iOS, this method requires that you have requested the user's permission for allowBadge via requestPermissionsAsync, otherwise it will automatically return false.

Note: Not all Android launchers support application badges. If the launcher does not support icon badges, the method will resolve to false.

Cancels all scheduled notifications.

Cancels a single scheduled notification. The scheduled notification of given ID will not trigger.

import * as Notifications from 'expo-notifications';

async function scheduleAndCancel() {
  const identifier = await Notifications.scheduleNotificationAsync({
    content: {
      title: 'Hey!',
    },
    trigger: { seconds: 60, repeats: true },
  });
  await Notifications.cancelScheduledNotificationAsync(identifier);
}

Fetches information about all scheduled notifications.

Allows you to check what will be the next trigger date for given notification trigger input.

import * as Notifications from 'expo-notifications';

async function logNextTriggerDate() {
  try {
    const nextTriggerDate = await Notifications.getNextTriggerDateAsync({
      hour: 9,
      minute: 0,
    });
    console.log(nextTriggerDate === null ? 'No next trigger date' : new Date(nextTriggerDate));
  } catch (e) {
    console.warn(`Couldn't have calculated next trigger date: ${e}`);
  }
}

Schedules a notification for immediate trigger.

Schedules a notification to be triggered in the future.

Note: Please note that this does not mean that the notification will be presented when it is triggered. For the notification to be presented you have to set a notification handler with setNotificationHandler that will return an appropriate notification behavior. For more information see the example below.

import * as Notifications from 'expo-notifications';

Notifications.scheduleNotificationAsync({
  content: {
    title: "Time's up!",
    body: 'Change sides!',
  },
  trigger: {
    seconds: 60,
  },
});

import * as Notifications from 'expo-notifications';

Notifications.scheduleNotificationAsync({
  content: {
    title: 'Remember to drink water!',
  },
  trigger: {
    seconds: 60 * 20,
    repeats: true,
  },
});

import * as Notifications from 'expo-notifications';

const trigger = new Date(Date.now() + 60 * 60 * 1000);
trigger.setMinutes(0);
trigger.setSeconds(0);

Notifications.scheduleNotificationAsync({
  content: {
    title: 'Happy new hour!',
  },
  trigger,
});

Removes all application's notifications displayed in the notification tray (Notification Center).

Removes notification displayed in the notification tray (Notification Center).

Fetches information about all notifications present in the notification tray (Notification Center).

This method is not supported on Android below 6.0 (API level 23) – on these devices it will resolve to an empty array.

Removes the notification channel.

Removes the notification channel group and all notification channels that belong to it.

Fetches information about a single notification channel.

Fetches information about a single notification channel group.

Fetches information about all known notification channel groups.

Fetches information about all known notification channels.

Assigns the channel configuration to a channel of a specified name (creating it if need be). This method lets you assign given notification channel to a notification channel group.

Note: For some settings to be applied on all Android versions, it may be necessary to duplicate the configuration across both a single notification and its respective notification channel.

For example, for a notification to play a custom sound on Android versions below 8.0, the custom notification sound has to be set on the notification (through the NotificationContentInput), and for the custom sound to play on Android versions above 8.0, the relevant notification channel must have the custom sound configured (through the NotificationChannelInput). For more information, see Set custom notification sounds on Android.

Assigns the channel group configuration to a channel group of a specified name (creating it if need be).

Deletes the category associated with the provided identifier.

Fetches information about all known notification categories.

Sets the new notification category.

Sets the registration information so that the device push token gets pushed to the given registration endpoint

AudioAttributes Properties

Extends: Region

A region used to detect the presence of iBeacon devices. Based on Core Location CLBeaconRegion class.

BeaconRegion Properties

A trigger related to a UNCalendarNotificationTrigger.

CalendarNotificationTrigger Properties

Extends: Region

A circular geographic region, specified as a center point and radius. Based on Core Location CLCircularRegion class.

CircularRegion Properties

A trigger related to a daily notification.

The same functionality will be achieved on iOS with a CalendarNotificationTrigger.

DailyNotificationTrigger Properties

A trigger that will cause the notification to be delivered once per day.

DailyTriggerInput Properties

Borrowing structure from DevicePushToken a little. You can use the data value to send notifications via Expo Notifications service.

ExpoPushToken Properties

ExpoPushTokenOptions Properties

A Firebase RemoteMessage that caused the notification to be delivered to the app.

FirebaseRemoteMessage Properties

FirebaseRemoteMessageNotification Properties

Available configuration for permission request on iOS platform. See Apple documentation for UNAuthorizationOptions to learn more.

IosNotificationPermissionsRequest Properties

A trigger related to a UNLocationNotificationTrigger.

LocationNotificationTrigger Properties

NativeDevicePushToken Properties

An object represents a single notification that has been triggered by some request (NotificationRequest) at some point in time.

Notification Properties

NotificationAction Properties

An object represents behavior that should be applied to the incoming notification.

On Android, setting shouldPlaySound: false will result in the drop-down notification alert not showing, no matter what the priority is. This setting will also override any channel-specific sounds you may have configured.

NotificationBehavior Properties

NotificationCategory Properties

An object represents a notification channel.

NotificationChannel Properties

An object represents a notification channel group.

NotificationChannelGroup Properties

An object represents a notification channel group to be set.

NotificationChannelGroupInput Properties

Extends: ProxyNativeModule

NotificationChannelGroupManager Properties

Extends: ProxyNativeModule

NotificationChannelManager Properties

NotificationHandler Properties

An interface representing the permissions request scope configuration. Each option corresponds to a different native platform authorization option.

NotificationPermissionsRequest Properties

Extends: PermissionResponse

An object obtained by permissions get and request functions.

NotificationPermissionsStatus Properties

An object represents a request to present a notification. It has content — how it's being represented, and a trigger — what triggers the notification. Many notifications (Notification) may be triggered with the same request (for example, a repeating notification).

NotificationRequest Properties

An object represents a notification request you can pass into scheduleNotificationAsync.

NotificationRequestInput Properties

An object represents user's interaction with the notification.

Note: If the user taps on a notification actionIdentifier will be equal to Notifications.DEFAULT_ACTION_IDENTIFIER.

NotificationResponse Properties

An object obtained by permissions get and request functions.

PermissionResponse Properties

The region used to determine when the system sends the notification.

Region Properties

A trigger related to an elapsed time interval. May be repeating (see repeats field).

TimeIntervalNotificationTrigger Properties

A trigger that will cause the notification to be delivered once or many times (depends on the repeats field) after seconds time elapse.

On iOS, when repeats is true, the time interval must be 60 seconds or greater. Otherwise, the notification won't be triggered.

TimeIntervalTriggerInput Properties

Represents a notification trigger that is unknown to expo-notifications and that it didn't know how to serialize for JS.

UnknownNotificationTrigger Properties

A trigger related to a weekly notification.

The same functionality will be achieved on iOS with a CalendarNotificationTrigger.

WeeklyNotificationTrigger Properties

A trigger that will cause the notification to be delivered once every week.

Note: Weekdays are specified with a number from 1 through 7, with 1 indicating Sunday.

WeeklyTriggerInput Properties

A trigger related to a yearly notification.

The same functionality will be achieved on iOS with a CalendarNotificationTrigger.

YearlyNotificationTrigger Properties

A trigger that will cause the notification to be delivered once every year.

Note: all properties are specified in JavaScript Date's ranges.

YearlyTriggerInput Properties