Notifications

Migrating from Expo's LegacyNotifications module? Here's a guide to help make the transition as easy as possible.

Features

• 📣 schedule a one-off notification for a specific date, or some time from now,
• 🔁 schedule a notification repeating in some time interval (or a calendar date match on iOS),
• 💯 get and set application badge icon number,
• 📲 fetch a native device push token so you can send push notifications with FCM and APNS,
• 😎 fetch an Expo push token so you can send push notifications with Expo,
• 📬 listen to incoming notifications in the foreground and background,
• 👆 listen to interactions with notifications,
• 🎛 handle notifications when the app is in foreground,
• 🔕 imperatively dismiss notifications from Notification Center/tray,
• 🗂 create, update, delete Android notification channels,
• 🎨 set custom icon and color for notifications on Android.

Installation

Config plugin setup (optional)

The iOS APNS entitlement is always set to 'development'. Xcode automatically changes this to 'production' during archive. Learn more.

{
  "expo": {
    ...
    "plugins": [
      [
        "expo-notifications",
        {
          "icon": "./local/path/to/myNotificationIcon.png",
          "color": "#ffffff",
          "sounds": ["./local/path/to/mySound.wav", "./local/path/to/myOtherSound.wav"]
        }
      ]
    ],
  }
}

Android

Common gotchas / known issues

Sending notifications directly through APNs and FCM

Fetching a push token takes a long time on iOS

This is not necessarily an error condition. The system may not have Internet connectivity at all because it is out of range of any cell towers or Wi-Fi access points, or it may be in airplane mode. Instead of treating this as an error, your app should continue normally, disabling only that functionality that relies on push notifications.

API

import * as Notifications from 'expo-notifications';

import Constants from 'expo-constants';
import * as Notifications from 'expo-notifications';
import React, { useState, useEffect, useRef } from 'react';
import { Text, View, Button, Platform } from 'react-native';

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

export default function App() {
  const [expoPushToken, setExpoPushToken] = useState('');
  const [notification, setNotification] = useState(false);
  const notificationListener = useRef();
  const responseListener = useRef();

  useEffect(() => {
    registerForPushNotificationsAsync().then(token => setExpoPushToken(token));

    notificationListener.current = Notifications.addNotificationReceivedListener(notification => {
      setNotification(notification);
    });

    responseListener.current = Notifications.addNotificationResponseReceivedListener(response => {
      console.log(response);
    });

    return () => {
      Notifications.removeNotificationSubscription(notificationListener.current);
      Notifications.removeNotificationSubscription(responseListener.current);
    };
  }, []);

  return (
    <View
      style={{
        flex: 1,
        alignItems: 'center',
        justifyContent: 'space-around',
      }}
    >
      <Text>Your expo push token: {expoPushToken}</Text>
      <View style={{ alignItems: 'center', justifyContent: 'center' }}>
        <Text>Title: {notification && notification.request.content.title} </Text>
        <Text>Body: {notification && notification.request.content.body}</Text>
        <Text>Data: {notification && JSON.stringify(notification.request.content.data)}</Text>
      </View>
      <Button
        title="Press to schedule a notification"
        onPress={async () => {
          await schedulePushNotification();
        }}
      />
    </View>
  );
}

async function schedulePushNotification() {
  await Notifications.scheduleNotificationAsync({
    content: {
      title: "You've got mail! 📬",
      body: 'Here is the notification body',
      data: { data: 'goes here' },
    },
    trigger: { seconds: 2 },
  });
}

async function registerForPushNotificationsAsync() {
  let token;
  if (Constants.isDevice) {
    const { status: existingStatus } = await Notifications.getPermissionsAsync();
    let finalStatus = existingStatus;
    if (existingStatus !== 'granted') {
      const { status } = await Notifications.requestPermissionsAsync();
      finalStatus = status;
    }
    if (finalStatus !== 'granted') {
      alert('Failed to get push token for push notification!');
      return;
    }
    token = (await Notifications.getExpoPushTokenAsync()).data;
    console.log(token);
  } else {
    alert('Must use physical device for Push Notifications');
  }

  if (Platform.OS === 'android') {
    Notifications.setNotificationChannelAsync('default', {
      name: 'default',
      importance: Notifications.AndroidImportance.MAX,
      vibrationPattern: [0, 250, 250, 250],
      lightColor: '#FF231F7C',
    });
  }

  return token;
}

Custom notification icon and colors (Android only)

Setting custom notification sounds

{
  "expo": {
    "plugins": [
      [
        "expo-notifications",
        {
          "sounds": ["local/path/to/mySoundFile.wav"]
        }
      ]
    ]
  }
}

await Notifications.setNotificationChannelAsync('new-emails', {
  name: 'E-mail notifications',
  sound: 'mySoundFile.wav', // Provide ONLY the base filename
});

await Notifications.scheduleNotificationAsync({
  content: {
    title: "You've got mail! 📬",
    sound: 'mySoundFile.wav', // Provide ONLY the base filename
  },
  trigger: {
    seconds: 2,
    channelId: 'new-emails',
  },
});

// Prepare the notification channel
await Notifications.setNotificationChannelAsync('new-emails', {
  name: 'E-mail notifications',
  importance: Notifications.AndroidImportance.HIGH,
  sound: 'email-sound.wav', // <- for Android 8.0+, see channelId property below
});

// Eg. schedule the notification
await Notifications.scheduleNotificationAsync({
  content: {
    title: "You've got mail! 📬",
    body: 'Open the notification to read them all',
    sound: 'email-sound.wav', // <- for Android below 8.0
  },
  trigger: {
    seconds: 2,
    channelId: 'new-emails', // <- for Android 8.0+, see definition above
  },
});

Manually adding notification sounds on iOS

On iOS, all that's needed is to place your sound file in your Xcode project (see the screenshot below), and then specify the sound file in your NotificationContentInput, like this:

await Notifications.scheduleNotificationAsync({
  content: {
    title: "You've got mail! 📬",
    body: 'Open the notification to read them all',
    sound: 'notification.wav',
  },
  trigger: {
    // ...
  },
});

Android push notification payload specification

export interface FirebaseData {
  title?: string;
  message?: string;
  subtitle?: string;
  sound?: boolean | string;
  vibrate?: boolean | number[];
  priority?: AndroidNotificationPriority;
  badge?: number;
}

Fetching tokens for push notifications

getExpoPushTokenAsync(options: ExpoTokenOptions): ExpoPushToken

Note: For Expo's backend to be able to send notifications to your app, you will need to provide it with push notification keys. This can be done using expo-cli (expo credentials:manager). Read more in the “Upload notifications credentials” guide.

Arguments

• experienceId (string) -- Although this is optional, we recommend explicitly passing it in. The ID of the experience to which the token should be attributed. Defaults to Constants.manifest.id exposed by expo-constants. When building with EAS Build, or in the bare workflow, this is required and you must provide a value which takes the shape @username/projectSlug, where username is the Expo account that the project is associated with, and projectSlug is your slug from app.json.
• devicePushToken (DevicePushToken) -- The device push token with which to register at the backend. Defaults to a token fetched with getDevicePushTokenAsync().
• applicationId (string) -- The ID of the application to which the token should be attributed. Defaults to Application.applicationId exposed by expo-application.
• development (boolean) -- Makes sense only on iOS, where there are two push notification services: sandbox and production. This defines whether the push token is supposed to be used with the sandbox platform notification service. Defaults to Application.getIosPushNotificationServiceEnvironmentAsync() exposed by expo-application or false. Most probably you won't need to customize that. You may want to customize that if you don't want to install expo-application and still use the sandbox APNS.

Returns

• type (string) -- Always expo.
• data (string) -- The push token as a string.

Examples

Fetching the Expo push token and uploading it to a server

import Constants from 'expo-constants';
import * as Notifications from 'expo-notifications';

export async function registerForPushNotificationsAsync(userId: string) {
  const expoPushToken = await Notifications.getExpoPushTokenAsync({
    experienceId: '@username/example',
  });

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

getDevicePushTokenAsync(): DevicePushToken

Returns

• type (string) -- Either ios, android or web.
• data (string or object) -- Either the push token as a string (for type == "ios" | "android") or an object conforming to the type below (for type == "web"):

  {
    endpoint: string;
    keys: {
      p256dh: string;
      auth: string;
    }
  }
  

addPushTokenListener(listener: PushTokenListener): Subscription

Arguments

Returns

Examples

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

removePushTokenSubscription(subscription: Subscription): void

Arguments

Listening to notification events

In the chart above, whenever NotificationResponseReceivedListener is triggered, the same would apply to the useLastNotificationResponse hook.

useLastNotificationResponse(): undefined | NotificationResponse | null

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

Returns

• 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

Examples

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

addNotificationReceivedListener(listener: (event: Notification) => void): void

Arguments

Returns

Examples

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

addNotificationsDroppedListener(listener: () => void): void

Arguments

Returns

addNotificationResponseReceivedListener(listener: (event: NotificationResponse) => void): void

Arguments

Returns

Examples

Registering a notification listener using a React hook

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

Handling push notifications with React Navigation

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

export default function App() {
  return (
    <NavigationContainer
      linking={{
        config: {
          // Configuration for linking
        },
        async getInitialURL() {
          // First, you may want to do the default deep link handling
          // Check if app was opened from a deep link
          const url = await Linking.getInitialURL();

          if (url != null) {
            return url;
          }

          // Handle URL from expo push notifications
          const response = await Notifications.getLastNotificationResponseAsync();
          const url = response?.notification.request.content.data.url;

          return url;
        }
        subscribe(listener) {
          const onReceiveURL = ({ url }: { url: string }) => listener(url);

          // Listen to incoming links from deep linking
          Linking.addEventListener('url', onReceiveURL);

          // Listen to expo push notifications
          const subscription = Notifications.addNotificationResponseReceivedListener(response => {
            const url = response.notification.request.content.data.url;

            // Any custom logic to see whether the URL needs to be handled
            //...

            // Let React Navigation handle the URL
            listener(url);
          });

          return () => {
            // Clean up the event listeners
            Linking.removeEventListener('url', onReceiveURL);
            subscription.remove();
          };
        },
      }}>
      {/* Your app content */}
    </NavigationContainer>
  );
}

removeNotificationSubscription(subscription: Subscription): void

Arguments

Handling incoming notifications when the app is in foreground

setNotificationHandler(handler: NotificationHandler | null): void

Arguments

• handleNotification ((Notification) => Promise\<NotificationBehavior>) -- (required) a function accepting an incoming notification returning a Promise resolving to a behavior (NotificationBehavior) applicable to the notification
• handleSuccess ((notificationId: string) => void) -- (optional) a function called whenever an incoming notification is handled successfully
• handleError ((error: Error) => void) -- (optional) a function called whenever handling of an incoming notification fails

Examples

import * as Notifications from 'expo-notifications';

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

Handling incoming notifications when the app is not in the foreground (not supported in Expo Go)

Please note: In order to handle notifications while the app is backgrounded on iOS, you must add remote-notification to the ios.infoPlist.UIBackgroundModes key in your app.json, and add "content-available": 1 to your push notification payload. Under normal circumstances, the “content-available” flag should launch your app if it isn’t running and wasn’t killed by the user, however, this is ultimately decided by the OS so it might not always happen.

registerTaskAsync(taskName: string): void

• data: The remote payload delivered by either FCM (Android) or APNs (iOS). See here 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);

unregisterTaskAsync(taskName: string): void

Fetching information about notifications-related permissions

getPermissionsAsync(): Promise<NotificationPermissionsStatus>

Returns

Examples

import * as Notifications from 'expo-notifications';

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

requestPermissionsAsync(request?: NotificationPermissionsRequest): Promise<NotificationPermissionsStatus>

Arguments

{
  android?: {};
  ios?: {
    allowAlert?: boolean;
    allowBadge?: boolean;
    allowSound?: boolean;
    allowDisplayInCarPlay?: boolean;
    allowCriticalAlerts?: boolean;
    provideAppNotificationSettings?: boolean;
    allowProvisional?: boolean;
    allowAnnouncements?: boolean;
  }
}

Returns

Examples

import * as Notifications from 'expo-notifications';

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

Interpreting the iOS permissions response

• NOT_DETERMINED: The user hasn't yet made a choice about whether the app is allowed to schedule notifications
• DENIED: The app isn't authorized to schedule or receive notifications
• AUTHORIZED: The app is authorized to schedule or receive notifications
• PROVISIONAL: The application is provisionally authorized to post noninterruptive user notifications
• EPHEMERAL: The app is authorized to schedule or receive notifications for a limited amount of time

Managing application badge icon

getBadgeCountAsync(): Promise<number>

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

Returns

setBadgeCountAsync(badgeCount: number, options?: SetBadgeCountOptions): Promise<boolean>

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

Arguments

{
  web?: badgin.Options
}

Returns

Scheduling notifications

getAllScheduledNotificationsAsync(): Promise<Notification[]>

Returns

presentNotificationAsync(content: NotificationContentInput, identifier?: string): Promise<string>

Note: This method has been deprecated in favor of using an explicit NotificationHandler and the scheduleNotificationAsync method. More info may be found at https://expo.fyi/presenting-notifications-deprecated.

Arguments

Returns

Examples

Presenting the notification to the user (deprecated way)

import * as Notifications from 'expo-notifications';

Notifications.presentNotificationAsync({
  title: 'Look at that notification',
  body: "I'm so proud of myself!",
});

Presenting the notification to the user (recommended way)

import * as Notifications from 'expo-notifications';

// First, set the handler that will cause the notification
// to show the alert

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

// Second, call the method

Notifications.scheduleNotificationAsync({
  content: {
    title: 'Look at that notification',
    body: "I'm so proud of myself!",
  },
  trigger: null,
});

scheduleNotificationAsync(notificationRequest: NotificationRequestInput): Promise<string>

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.

Arguments

Returns

Examples

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

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

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

cancelScheduledNotificationAsync(identifier: string): Promise<void>

Arguments

Returns

Examples

Scheduling and then canceling the notification

import * as Notifications from 'expo-notifications';

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

cancelAllScheduledNotificationsAsync(): Promise<void>

Returns

getNextTriggerDateAsync(trigger: SchedulableNotificationTriggerInput): Promise<number | null>

Arguments

Returns

Examples

Calculating next trigger date for a notification trigger

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

Dismissing notifications

getPresentedNotificationsAsync(): Promise<Notification[]>

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

Returns

dismissNotificationAsync(identifier: string): Promise<void>

Arguments

Returns

dismissAllNotificationsAsync(): Promise<void>

Returns

Managing notification channels (Android-specific)

Starting in Android 8.0 (API level 26), all notifications must be assigned to a channel. For each channel, you can set the visual and auditory behavior that is applied to all notifications in that channel. Then, users can change these settings and decide which notification channels from your app should be intrusive or visible at all. (source: developer.android.com)

getNotificationChannelsAsync(): Promise<NotificationChannel[]>

Returns

getNotificationChannelAsync(identifier: string): Promise<NotificationChannel | null>

Arguments

Returns

setNotificationChannelAsync(identifier: string, channel: NotificationChannelInput): Promise<NotificationChannel | null>

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 it's 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 "Setting custom notification sounds on Android".

Arguments

Returns

deleteNotificationChannelAsync(identifier: string): Promise<void>

Arguments

Returns

getNotificationChannelGroupsAsync(): Promise<NotificationChannelGroup[]>

Returns

getNotificationChannelGroupAsync(identifier: string): Promise<NotificationChannelGroup | null>

Arguments

Returns

setNotificationChannelGroupAsync(identifier: string, channel: NotificationChannelGroupInput): Promise<NotificationChannelGroup | null>

Arguments

Returns

deleteNotificationChannelGroupAsync(identifier: string): Promise<void>

Arguments

Returns

Managing notification categories (interactive notifications)

setNotificationCategoryAsync(identifier: string, actions: NotificationAction[], options: CategoryOptions): Promise<NotificationCategory | null>

Arguments

• identifier: A string to associate as the ID of this category. You will pass this string in as the categoryIdentifier in your NotificationContent to associate a notification with this category. Don't use the characters : or - in your category identifier. If you do, categories might not work as expected.
• actions: An array of NotificationActions, which describe the actions associated with this category. Each of these actions takes the shape:
  • identifier: A unique string that identifies this action. If a user takes this action (i.e. selects this button in the system's Notification UI), your app will receive this actionIdentifier via the NotificationResponseReceivedListener.
  • buttonTitle: The title of the button triggering this action.
  • textInput: Optional object which, if provided, will result in a button that prompts the user for a text response.
    • submitButtonTitle: (iOS only) A string which will be used as the title for the button used for submitting the text response.
    • placeholder: A string that serves as a placeholder until the user begins typing. Defaults to no placeholder string.
  • options: Optional object of additional configuration options.
    • opensAppToForeground: Boolean indicating whether triggering this action foregrounds the app (defaults to true). If false and your app is killed (not just backgrounded), NotificationResponseReceived listeners will not be triggered when a user selects this action.
    • isAuthenticationRequired: (iOS only) Boolean indicating whether triggering the action will require authentication from the user.
    • isDestructive: (iOS only) Boolean indicating whether the button title will be highlighted a different color (usually red). This usually signifies a destructive action such as deleting data.
• options: An optional object of additional configuration options for your category (these are all iOS only):
  • previewPlaceholder: Customizable placeholder for the notification preview text. This is shown if the user has disabled notification previews for the app. Defaults to the localized iOS system default placeholder (Notification).
  • intentIdentifiers: Array of Intent Class Identifiers. When a notification is delivered, the presence of an intent identifier lets the system know that the notification is potentially related to the handling of a request made through Siri. Defaults to an empty array.
  • categorySummaryFormat: A format string for the summary description used when the system groups the category’s notifications.
  • customDismissAction: A boolean indicating whether to send actions for handling when the notification is dismissed (the user must explicitly dismiss the notification interface- ignoring a notification or flicking away a notification banner does not trigger this action). Defaults to false.
  • allowInCarPlay: A boolean indicating whether to allow CarPlay to display notifications of this type. Apps must be approved for CarPlay to make use of this feature. Defaults to false.
  • showTitle: A boolean indicating whether to show the notification's title, even if the user has disabled notification previews for the app. Defaults to false.
  • showSubtitle: A boolean indicating whether to show the notification's subtitle, even if the user has disabled notification previews for the app. Defaults to false.
  • allowAnnouncement: A boolean indicating whether to allow notifications to be automatically read by Siri when the user is using AirPods. Defaults to false.

Returns

getNotificationCategoriesAsync(): Promise<NotificationCategory[]>

Returns

deleteNotificationCategoryAsync(identifier: string): Promise<boolean>

Arguments

Returns

Types

DevicePushToken

export interface NativeDevicePushToken {
  type: 'ios' | 'android';
  data: string;
}

export interface WebDevicePushToken {
  type: 'web';
  data: {
    endpoint: string;
    keys: {
      p256dh: string;
      auth: string;
    };
  };
}

export type DevicePushToken = NativeDevicePushToken | WebDevicePushToken;

PushTokenListener

Note: You should not call getDevicePushTokenAsync inside this function, as it triggers the listener and may lead to an infinite loop.

ExpoPushToken

export interface ExpoPushToken {
  type: 'expo';
  data: string;
}

Subscription

export type Subscription = {
  remove: () => void;
};

Notification

export interface Notification {
  date: number;
  request: NotificationRequest;
}

NotificationRequest

export interface NotificationRequest {
  identifier: string;
  content: NotificationContent;
  trigger: NotificationTrigger;
}

NotificationContent

export type NotificationContent = {
  // Notification title - the bold text displayed above the rest of the content
  title: string | null;
  // On iOS - subtitle - the bold text displayed between title and the rest of the content
  // On Android - subText - the display depends on the platform
  subtitle: string | null;
  // Notification body - the main content of the notification
  body: string | null;
  // Data associated with the notification, not displayed
  data: { [key: string]: unknown };
  // Application badge number associated with the notification
  badge: number | null;
  sound: 'default' | 'defaultCritical' | 'custom' | null;
  categoryIdentifier: string | null;
} & (
  | {
      // iOS-specific additions
      // See https://developer.apple.com/documentation/usernotifications/unnotificationcontent?language=objc
      // for more information on specific fields.
      launchImageName: string | null;
      attachments: {
        identifier: string | null;
        url: string | null;
        type: string | null;
      }[];
      summaryArgument?: string | null;
      summaryArgumentCount?: number;
      threadIdentifier: string | null;
      targetContentIdentifier?: string;
    }
  | {
      // Android-specific additions
      // See https://developer.android.com/reference/android/app/Notification.html#fields
      // for more information on specific fields.
      priority?: AndroidNotificationPriority;
      vibrationPattern?: number[];
      // Format: '#AARRGGBB'
      color?: string;
    }
);

NotificationContentInput

export interface NotificationContentInput {
  // Fields corresponding to NotificationContent
  title?: string;
  subtitle?: string;
  body?: string;
  data?: { [key: string]: unknown };
  badge?: number;
  sound?: boolean | string;

  // Android-specific fields
  // See https://developer.android.com/reference/android/app/Notification.html#fields
  // for more information on specific fields.
  vibrate?: boolean | number[];
  priority?: AndroidNotificationPriority;
  // Format: '#AARRGGBB', '#RRGGBB' or one of the named colors,
  // see https://developer.android.com/reference/kotlin/android/graphics/Color?hl=en
  color?: string;
  // If set to false, the notification will not be automatically dismissed when clicked.
  // The setting used when the value is not provided or is invalid is true (the notification
  // will be dismissed automatically). Corresponds directly to Android's `setAutoCancel`
  // behavior. In Firebase terms this property of a notification is called `sticky`.
  // See:
  // - https://developer.android.com/reference/android/app/Notification.Builder#setAutoCancel(boolean),
  // - https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#AndroidNotification.FIELDS.sticky
  autoDismiss?: boolean;
  // If set to true, the notification cannot be dismissed by swipe. This setting defaults
  // to false if not provided or is invalid. Corresponds directly do Android's `isOngoing` behavior.
  // See: https://developer.android.com/reference/android/app/Notification.Builder#setOngoing(boolean)
  sticky?: boolean;

  // iOS-specific fields
  // See https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent?language=objc
  // for more information on specific fields.
  launchImageName?: string;
  attachments?: {
    url: string;
    identifier?: string;

    typeHint?: string;
    hideThumbnail?: boolean;
    thumbnailClipArea?: { x: number; y: number; width: number; height: number };
    thumbnailTime?: number;
  }[];
}

NotificationRequestInput

export interface NotificationRequestInput {
  identifier?: string;
  content: NotificationContentInput;
  trigger: NotificationTriggerInput;
}

AndroidNotificationPriority

export enum AndroidNotificationPriority {
  MIN = 'min',
  LOW = 'low',
  DEFAULT = 'default',
  HIGH = 'high',
  MAX = 'max',
}

NotificationTrigger

export type NotificationTrigger =
  | PushNotificationTrigger
  | CalendarNotificationTrigger
  | LocationNotificationTrigger
  | TimeIntervalNotificationTrigger
  | DailyNotificationTrigger
  | UnknownNotificationTrigger;

PushNotificationTrigger

export type PushNotificationTrigger = { type: 'push' } & (
  | { payload: Record<string, unknown> } // iOS
  | { remoteMessage: FirebaseRemoteMessage } // Android
  | {}
);

FirebaseRemoteMessage

export interface FirebaseRemoteMessage {
  collapseKey: string | null;
  data: { [key: string]: string };
  from: string | null;
  messageId: string | null;
  messageType: string | null;
  originalPriority: number;
  priority: number;
  sentTime: number;
  to: string | null;
  ttl: number;
  notification: null | {
    body: string | null;
    bodyLocalizationArgs: string[] | null;
    bodyLocalizationKey: string | null;
    channelId: string | null;
    clickAction: string | null;
    color: string | null;
    usesDefaultLightSettings: boolean;
    usesDefaultSound: boolean;
    usesDefaultVibrateSettings: boolean;
    eventTime: number | null;
    icon: string | null;
    imageUrl: string | null;
    lightSettings: number[] | null;
    link: string | null;
    localOnly: boolean;
    notificationCount: number | null;
    notificationPriority: number | null;
    sound: string | null;
    sticky: boolean;
    tag: string | null;
    ticker: string | null;
    title: string | null;
    titleLocalizationArgs: string[] | null;
    titleLocalizationKey: string | null;
    vibrateTimings: number[] | null;
    visibility: number | null;
  };
}

TimeIntervalNotificationTrigger

export interface TimeIntervalNotificationTrigger {
  type: 'timeInterval';
  repeats: boolean;
  seconds: number;
}

DailyNotificationTrigger

export interface DailyNotificationTrigger {
  type: 'daily';
  hour: number;
  minute: number;
}

WeeklyNotificationTrigger

export interface WeeklyNotificationTrigger {
  type: 'weekly';
  weekday: number;
  hour: number;
  minute: number;
}

YearlyNotificationTrigger

export interface YearlyNotificationTrigger {
  type: 'yearly';
  day: number;
  month: number;
  hour: number;
  minute: number;
}

CalendarNotificationTrigger

export interface CalendarNotificationTrigger {
  type: 'calendar';
  repeats: boolean;
  dateComponents: {
    era?: number;
    year?: number;
    month?: number;
    day?: number;
    hour?: number;
    minute?: number;
    second?: number;
    weekday?: number;
    weekdayOrdinal?: number;
    quarter?: number;
    weekOfMonth?: number;
    weekOfYear?: number;
    yearForWeekOfYear?: number;
    nanosecond?: number;
    isLeapMonth: boolean;
    timeZone?: string;
    calendar?: string;
  };
}

LocationNotificationTrigger

export interface LocationNotificationTrigger {
  type: 'location';
  repeats: boolean;
  region: CircularRegion | BeaconRegion;
}

interface Region {
  type: string;
  identifier: string;
  notifyOnEntry: boolean;
  notifyOnExit: boolean;
}

export interface CircularRegion extends Region {
  type: 'circular';
  radius: number;
  center: {
    latitude: number;
    longitude: number;
  };
}

export interface BeaconRegion extends Region {
  type: 'beacon';
  notifyEntryStateOnDisplay: boolean;
  major: number | null;
  minor: number | null;
  uuid?: string;
  beaconIdentityConstraint?: {
    uuid: string;
    major: number | null;
    minor: number | null;
  };
}

UnknownNotificationTrigger

export interface UnknownNotificationTrigger {
  type: 'unknown';
}

NotificationTriggerInput

export type NotificationTriggerInput =
  | null
  | ChannelAwareTriggerInput
  | SchedulableNotificationTriggerInput;

SchedulableNotificationTriggerInput

export type SchedulableNotificationTriggerInput =
  | DateTriggerInput
  | TimeIntervalTriggerInput
  | DailyTriggerInput
  | WeeklyTriggerInput
  | YearlyTriggerInput
  | CalendarTriggerInput;

ChannelAwareTriggerInput

export type ChannelAwareTriggerInput = {
  channelId: string;
};

DateTriggerInput

export type DateTriggerInput = Date | number | { channelId?: string; date: Date | number };

TimeIntervalTriggerInput

export interface TimeIntervalTriggerInput {
  channelId?: string;
  repeats?: boolean;
  seconds: number;
}

DailyTriggerInput

export interface DailyTriggerInput {
  channelId?: string;
  hour: number;
  minute: number;
  repeats: true;
}

WeeklyTriggerInput

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

export interface WeeklyTriggerInput {
  channelId?: string;
  weekday: number;
  hour: number;
  minute: number;
  repeats: true;
}

YearlyTriggerInput

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

export interface YearlyTriggerInput {
  channelId?: string;
  day: number;
  month: number;
  hour: number;
  minute: number;
  repeats: true;
}

CalendarTriggerInput

Note: This type of trigger is only available on iOS.

export interface CalendarTriggerInput {
  channelId?: string;
  repeats?: boolean;
  timezone?: string;

  year?: number;
  month?: number;
  weekday?: number;
  weekOfMonth?: number;
  weekOfYear?: number;
  weekdayOrdinal?: number;
  day?: number;

  hour?: number;
  minute?: number;
  second?: number;
}

NotificationResponse

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

export interface NotificationResponse {
  notification: Notification;
  actionIdentifier: string;
  userText?: string;
}

NotificationBehavior

export interface NotificationBehavior {
  shouldShowAlert: boolean;
  shouldPlaySound: boolean;
  shouldSetBadge: boolean;
  priority?: AndroidNotificationPriority;
}

NotificationChannel

export enum AndroidNotificationVisibility {
  UNKNOWN,
  PUBLIC,
  PRIVATE,
  SECRET,
}

export enum AndroidAudioContentType {
  UNKNOWN,
  SPEECH,
  MUSIC,
  MOVIE,
  SONIFICATION,
}

export enum AndroidImportance {
  UNKNOWN,
  UNSPECIFIED,
  NONE,
  MIN,
  LOW,
  DEFAULT,
  HIGH,
  MAX,
}

export enum AndroidAudioUsage {
  UNKNOWN,
  MEDIA,
  VOICE_COMMUNICATION,
  VOICE_COMMUNICATION_SIGNALLING,
  ALARM,
  NOTIFICATION,
  NOTIFICATION_RINGTONE,
  NOTIFICATION_COMMUNICATION_REQUEST,
  NOTIFICATION_COMMUNICATION_INSTANT,
  NOTIFICATION_COMMUNICATION_DELAYED,
  NOTIFICATION_EVENT,
  ASSISTANCE_ACCESSIBILITY,
  ASSISTANCE_NAVIGATION_GUIDANCE,
  ASSISTANCE_SONIFICATION,
  GAME,
}

export interface AudioAttributes {
  usage: AndroidAudioUsage;
  contentType: AndroidAudioContentType;
  flags: {
    enforceAudibility: boolean;
    requestHardwareAudioVideoSynchronization: boolean;
  };
}

export interface NotificationChannel {
  id: string;
  name: string | null;
  importance: AndroidImportance;
  bypassDnd: boolean;
  description: string | null;
  groupId?: string | null;
  lightColor: string;
  lockscreenVisibility: AndroidNotificationVisibility;
  showBadge: boolean;
  sound: 'default' | 'custom' | null;
  audioAttributes: AudioAttributes;
  vibrationPattern: number[] | null;
  enableLights: boolean;
  enableVibrate: boolean;
}

NotificationChannelInput

export interface NotificationChannelInput {
  name: string | null;
  importance: AndroidImportance;
  // Optional attributes
  bypassDnd?: boolean;
  description?: string | null;
  groupId?: string | null;
  lightColor?: string;
  lockscreenVisibility?: AndroidNotificationVisibility;
  showBadge?: boolean;
  sound?: string | null;
  audioAttributes?: Partial<AudioAttributes>;
  vibrationPattern?: number[] | null;
  enableLights?: boolean;
  enableVibrate?: boolean;
}

NotificationChannelGroup

export interface NotificationChannelGroup {
  id: string;
  name: string | null;
  description?: string | null;
  isBlocked?: boolean;
  channels: NotificationChannel[];
}

NotificationChannelGroupInput

export interface NotificationChannelGroupInput {
  name: string | null;
  description?: string | null;
}

NotificationCategory

export interface NotificationCategory {
  identifier: string;
  actions: NotificationAction[];
  options: {
    // These options are ALL iOS-only
    previewPlaceholder?: string;
    intentIdentifiers?: string[];
    categorySummaryFormat?: string;
    customDismissAction?: boolean;
    allowInCarPlay?: boolean;
    showTitle?: boolean;
    showSubtitle?: boolean;
    allowAnnouncement?: boolean;
  };
}

NotificationAction

export interface NotificationAction {
  identifier: string;
  buttonTitle: string;
  textInput?: {
    submitButtonTitle: string;
    placeholder: string;
  };
  options: {
    isDestructive?: boolean;
    isAuthenticationRequired?: boolean;
    opensAppToForeground?: boolean;
  };
}

NotificationPermissionsStatus

export interface NotificationPermissionsStatus {
  status: 'granted' | 'undetermined' | 'denied'; // on iOS, you should check `ios.status`
  granted: boolean;
  expires: 'never' | number;
  canAskAgain: boolean;
  android?: {
    importance: number;
    interruptionFilter?: number;
  };
  ios?: {
    status: IosAuthorizationStatus;
    allowsDisplayInNotificationCenter: boolean | null;
    allowsDisplayOnLockScreen: boolean | null;
    allowsDisplayInCarPlay: boolean | null;
    allowsAlert: boolean | null;
    allowsBadge: boolean | null;
    allowsSound: boolean | null;
    allowsCriticalAlerts?: boolean | null;
    alertStyle: IosAlertStyle;
    allowsPreviews?: IosAllowsPreviews;
    providesAppNotificationSettings?: boolean;
    allowsAnnouncements?: boolean | null;
  };
}