Expo Notifications

addPushTokenListener(listener)

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.

Example

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

• Subscription

A Subscription object represents the subscription of the provided listener.

getDevicePushTokenAsync()

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

Returns

• Promise<DevicePushToken>

getExpoPushTokenAsync(options)

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.

Example

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

Returns

• Promise<ExpoPushToken>

Returns a Promise that resolves to an object representing acquired push token.

removePushTokenSubscription(subscription)

Removes a push token subscription returned by an addPushTokenListener call.

Returns

• void

addNotificationReceivedListener(listener)

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

Example

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

Returns

• Subscription

A Subscription object represents the subscription of the provided listener.

addNotificationResponseReceivedListener(listener)

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

Example

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

Returns

• Subscription

A Subscription object represents the subscription of the provided listener.

addNotificationsDroppedListener(listener)

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.

Returns

• Subscription

A Subscription object represents the subscription of the provided listener.

getLastNotificationResponseAsync()

Returns

• Promise<NotificationResponse | null>

removeNotificationSubscription(subscription)

Removes a notification subscription returned by an addNotificationListener call.

Returns

• void

useLastNotificationResponse()

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.

Example

Responding to a notification tap by opening a URL that could be put into the notification's data (opening the URL is your responsibility and is not a part of the expo-notifications API):

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

Returns

• undefined | null | NotificationResponse

The hook may return one of these three types/values:

• undefined - until we're sure of what to return,
• null - if no notification response has been received yet,
• a NotificationResponse object - if a notification response was received.

setNotificationHandler(handler)

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.

Example

import * as Notifications from 'expo-notifications';

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

Returns

• void

registerTaskAsync(taskName)

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.

Example

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

Returns

• Promise<null>

unregisterTaskAsync(taskName)

Used to unregister tasks registered with registerTaskAsync method.

Returns

• Promise<null>

getPermissionsAsync()

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.

Example

import * as Notifications from 'expo-notifications';

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

Returns

• Promise<NotificationPermissionsStatus>

It returns a Promise resolving to an object represents permission settings (NotificationPermissionsStatus). On iOS, make sure you properly interpret the permissions response.

requestPermissionsAsync(permissions)

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.

Example

import * as Notifications from 'expo-notifications';

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

Returns

• Promise<NotificationPermissionsStatus>

It returns a Promise resolving to an object represents permission settings (NotificationPermissionsStatus). On iOS, make sure you properly interpret the permissions response.

getBadgeCountAsync()

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.

Returns

• Promise<number>

Returns a Promise resolving to a number that represents the current badge of the app icon.

setBadgeCountAsync(badgeCount, options)

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.

Returns

• Promise<boolean>

It returns a Promise resolving to a boolean representing whether the setting of the badge succeeded.

cancelAllScheduledNotificationsAsync()

Cancels all scheduled notifications.

Returns

• Promise<void>

A Promise that resolves once all the scheduled notifications are successfully canceled, or if there are no scheduled notifications.

cancelScheduledNotificationAsync(identifier)

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

Example

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

Returns

• Promise<void>

A Promise resolves once the scheduled notification is successfully canceled or if there is no scheduled notification for a given identifier.

getAllScheduledNotificationsAsync()

Fetches information about all scheduled notifications.

Returns

• Promise<NotificationRequest[]>

Returns a Promise resolving to an array of objects conforming to the Notification interface.

getNextTriggerDateAsync(trigger)

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

Example

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

Returns

• Promise<number | null>

If the return value is null, the notification won't be triggered. Otherwise, the return value is the Unix timestamp in milliseconds at which the notification will be triggered.

presentNotificationAsync(content, identifier)

Schedules a notification for immediate trigger.

Returns

• Promise<string>

It returns a Promise resolving with the notification's identifier once the notification is successfully scheduled for immediate display.

scheduleNotificationAsync(request)

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.

Example

Schedule the notification that will trigger once, in one minute from now

import * as Notifications from 'expo-notifications';

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

Schedule the notification that will trigger repeatedly, every 20 minutes

import * as Notifications from 'expo-notifications';

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

Schedule the notification that will trigger once, at the beginning of next hour

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

Returns

• Promise<string>

Returns a Promise resolving to a string which is a notification identifier you can later use to cancel the notification or to identify an incoming notification.

dismissAllNotificationsAsync()

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

Returns

• Promise<void>

A Promise which resolves once the request to dismiss the notifications is successfully dispatched to the notifications manager.

dismissNotificationAsync(notificationIdentifier)

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

Returns

• Promise<void>

A Promise which resolves once the request to dismiss the notification is successfully dispatched to the notifications manager.

getPresentedNotificationsAsync()

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.

Returns

• Promise<Notification[]>

A Promise which resolves with a list of notifications (Notification) currently present in the notification tray (Notification Center).

deleteNotificationChannelAsync(channelId)

Removes the notification channel.

Returns

• Promise<void>

A Promise which resolving once the channel is removed (or if there was no channel for given identifier).

deleteNotificationChannelGroupAsync(groupId)

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

Returns

• Promise<void>

A Promise which resolves once the channel group is removed (or if there was no channel group for given identifier).

getNotificationChannelAsync(channelId)

Fetches information about a single notification channel.

Returns

• Promise<NotificationChannel | null>

A Promise which resolves to the channel object (of type NotificationChannel) or to null if there was no channel found for this identifier. On platforms that do not support notification channels, it will always resolve to null.

getNotificationChannelGroupAsync(groupId)

Fetches information about a single notification channel group.

Returns

• Promise<NotificationChannelGroup | null>

A Promise which resolves to the channel group object (of type NotificationChannelGroup) or to null if there was no channel group found for this identifier. On platforms that do not support notification channels, it will always resolve to null.

getNotificationChannelGroupsAsync()

Fetches information about all known notification channel groups.

Returns

• Promise<NotificationChannelGroup[]>

A Promise which resoles to an array of channel groups. On platforms that do not support notification channel groups, it will always resolve to an empty array.

getNotificationChannelsAsync()

Fetches information about all known notification channels.

Returns

• Promise<NotificationChannel[]>

A Promise which resolves to an array of channels. On platforms that do not support notification channels, it will always resolve to an empty array.

setNotificationChannelAsync(channelId, channel)

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.

Returns

• Promise<NotificationChannel | null>

A Promise which resolving to the object (of type NotificationChannel) describing the modified channel or to null if the platform does not support notification channels.

setNotificationChannelGroupAsync(groupId, group)

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

Returns

• Promise<NotificationChannelGroup | null>

A Promise resolving to the object (of type NotificationChannelGroup) describing the modified channel group or to null if the platform does not support notification channels.

deleteNotificationCategoryAsync(identifier)

Deletes the category associated with the provided identifier.

Returns

• Promise<boolean>

A Promise which resolves to true if the category was successfully deleted, or false if it was not. An example of when this method would return false is if you try to delete a category that doesn't exist.

getNotificationCategoriesAsync()

Fetches information about all known notification categories.

Returns

• Promise<NotificationCategory[]>

A Promise which resolves to an array of NotificationCategorys. On platforms that do not support notification channels, it will always resolve to an empty array.

setNotificationCategoryAsync(identifier, actions, options)

Sets the new notification category.

Returns

• Promise<NotificationCategory>

A Promise which resolves to the category you just have created, or null on web

Notifications.setAutoServerRegistrationEnabledAsync(enabled)

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

Returns

• Promise<void>

Notifications.unregisterForNotificationsAsync()

Returns

• Promise<void>

AudioAttributes

AudioAttributes Properties

BeaconRegion

Extends: Region

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

BeaconRegion Properties

CalendarNotificationTrigger

A trigger related to a UNCalendarNotificationTrigger.

CalendarNotificationTrigger Properties

CircularRegion

Extends: Region

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

CircularRegion Properties

DailyNotificationTrigger

A trigger related to a daily notification.

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

DailyNotificationTrigger Properties

DailyTriggerInput

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

DailyTriggerInput Properties

ExpoPushToken

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

ExpoPushToken Properties

ExpoPushTokenOptions

ExpoPushTokenOptions Properties

FirebaseRemoteMessage

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

FirebaseRemoteMessage Properties

FirebaseRemoteMessageNotification

FirebaseRemoteMessageNotification Properties

IosNotificationPermissionsRequest

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

IosNotificationPermissionsRequest Properties

LocationNotificationTrigger

A trigger related to a UNLocationNotificationTrigger.

LocationNotificationTrigger Properties

NativeDevicePushToken

NativeDevicePushToken Properties

Notification

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

Notification Properties

NotificationAction

NotificationAction Properties

NotificationBehavior

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

NotificationCategory Properties

NotificationChannel

An object represents a notification channel.

NotificationChannel Properties

NotificationChannelGroup

An object represents a notification channel group.

NotificationChannelGroup Properties

NotificationChannelGroupInput

An object represents a notification channel group to be set.

NotificationChannelGroupInput Properties

NotificationChannelGroupManager

Extends: ProxyNativeModule

NotificationChannelGroupManager Properties

NotificationChannelManager

Extends: ProxyNativeModule

NotificationChannelManager Properties

NotificationHandler

NotificationHandler Properties

NotificationPermissionsRequest

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

NotificationPermissionsRequest Properties

NotificationPermissionsStatus

Extends: PermissionResponse

An object obtained by permissions get and request functions.

NotificationPermissionsStatus Properties

NotificationRequest

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

NotificationRequestInput

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

NotificationRequestInput Properties

NotificationResponse

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

PermissionResponse

An object obtained by permissions get and request functions.

PermissionResponse Properties

Region

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

Region Properties

TimeIntervalNotificationTrigger

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

TimeIntervalNotificationTrigger Properties

TimeIntervalTriggerInput

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

UnknownNotificationTrigger

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

UnknownNotificationTrigger Properties

WebDevicePushToken

WebDevicePushToken Properties

WeeklyNotificationTrigger

A trigger related to a weekly notification.

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

WeeklyNotificationTrigger Properties

WeeklyTriggerInput

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

YearlyNotificationTrigger

A trigger related to a yearly notification.

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

YearlyNotificationTrigger Properties

YearlyTriggerInput

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