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 which returns the notification response that was received most recently (a notification response designates an interaction with a notification, such as tapping on it).

To clear the last notification response, use clearLastNotificationResponseAsync().

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,
  }),
});

Call registerTaskAsync to set a callback (task) that will run in response to when a notification is received while the app is in foreground, background, or terminated. When app is terminated, only a data message (Android) / background notification (iOS) triggers the task execution. However, the OS may decide not to deliver the notification to your app in some cases (e.g. when the device is in Doze mode on Android, or when you send too many notifications - Apple recommends to not "send more than two or three per hour").

Under the hood, this function is run using expo-task-manager. You must define the task first, with TaskManager.defineTask and register it with registerTaskAsync.

Make sure you define and register the task in the module scope of a JS module which is required early by your app (e.g. in the index.js file). expo-task-manager loads your app's JS bundle in the background and executes the task, as well as any side effects which may happen as a consequence of requiring any JS modules.

The callback function you define with TaskManager.defineTask receives 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,
    },
  });
}

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: {
    type: SchedulableTriggerInputTypes.TIME_INTERVAL,
    seconds: 60,
  },
});

import * as Notifications from 'expo-notifications';

Notifications.scheduleNotificationAsync({
  content: {
    title: 'Remember to drink water!',
  },
  trigger: {
    type: SchedulableTriggerInputTypes.TIME_INTERVAL,
    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: After a channel has been created, you can modify only its name and description. This limitation is imposed by the Android OS.

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.

Clears the notification response that was received most recently. May be used when an app selects a route based on the notification response, and it is undesirable to continue selecting the route after the response has already been handled.

If a component is using the useLastNotificationResponse hook, this call will also clear the value returned by the hook.

Gets the notification response that was received most recently (a notification response designates an interaction with a notification, such as tapping on it).

• null - if no notification response has been received yet
• a NotificationResponse object - if a notification response was received

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

A trigger related to a UNCalendarNotificationTrigger.

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

A trigger related to a daily notification.

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

Object which contains the Expo push token in the data field. Use the value from data to send notifications via Expo Notifications service.

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

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

A trigger related to a UNLocationNotificationTrigger.

A trigger related to a monthly notification.

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

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

An object which 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.

An object which represents a notification channel.

An object which represents a notification channel group.

An object which represents a notification channel group to be set.

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

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).

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

An object which represents user's interaction with the notification.

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

An object obtained by permissions get and request functions.

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

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

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

A trigger related to a weekly notification.

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

A trigger related to a yearly notification.

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