Blog

Expo push notifications: the complete implementation guide

Kyle SeylerKyle SeylerFebruary 24, 2026
Expo Push Notifications: The Complete Implementation Guide (SDK 52+) — cover

Push notifications reach your users when they aren't in your app. In Expo, one library, expo-notifications, handles permissions, push tokens, local scheduling, and remote push. Getting a token takes a few lines. Push that arrives reliably also takes the right permission flow, the right credentials, receipt checks, and a fallback for users push can't reach.


Prerequisites

Before you write any notification code, you need:

  • A device or a supported emulator. Per Expo's setup guide, you can test push on a physical Android or iOS device, on an Android Emulator with Google Play services, or on an iOS Simulator running Xcode 14 or later (macOS 13+, iOS 16+).
  • A recent Expo SDK. The code in this guide follows the SDK 58 docs. From SDK 53, Expo Go doesn't support push notifications, so test push in a development build (Expo's push FAQ).
  • An EAS project (recommended). It gives you the projectId that getExpoPushTokenAsync() needs, and Expo Build (the eas CLI) manages your push credentials. You can configure credentials manually if you'd rather.

Install the required libraries:

Terminal
npx expo install expo-notifications expo-constants

Then add the config plugin to your app.json (or app.config.js):

JSON
{
  "expo": {
    "plugins": ["expo-notifications"]
  }
}

Local vs. remote notifications: which do you need?

Local and remote notifications use the same library but solve different problems, so decide which one you need first.

Local notificationsRemote (push) notifications
Triggered byThe app itself, on the deviceA remote server
Requires server?NoYes (your backend, Expo push service, or Courier)
Works offline?Yes, scheduled locallyNo, requires network to receive
Use casesReminders, timers, alarms, habit trackingMessages, alerts, marketing, transactional updates
Token required?NoYes: ExpoPushToken or native device token
Works in Expo Go?YesNot from SDK 53, so use a development build
App stateScheduled while app is open; fires regardless of stateDelivered regardless of app state
APIscheduleNotificationAsync()Expo Push API or direct FCM/APNs
Credential setupNoneFCM (Android) and APNs (iOS) credentials required

Rule of thumb: If the trigger originates from outside the device (another user sent a message, a price changed, a deployment failed), you need remote push. If the trigger is something the device already knows about (a scheduled reminder, a countdown), use local.

Local notification example

TypeScript
import * as Notifications from "expo-notifications";

await Notifications.scheduleNotificationAsync({
  content: {
    title: "Daily standup",
    body: "Standup starts in 5 minutes",
  },
  trigger: {
    type: Notifications.SchedulableTriggerInputTypes.DAILY,
    hour: 9,
    minute: 55,
  },
});

On Android 12 and later, a scheduled notification arrives at an approximate time unless your app has the SCHEDULE_EXACT_ALARM permission. Declare it in your app.json:

JSON
{
  "expo": {
    "android": {
      "permissions": ["android.permission.SCHEDULE_EXACT_ALARM"]
    }
  }
}

Declaring it isn't enough on Android 14 and later, which deny it by default for new installs. Check it with getExactAlarmPermissionsAsync(). If it's denied, requestExactAlarmPermissionsAsync() opens the system settings screen where the user can allow it.


Expo push vs. Firebase (FCM): which should you use?

Expo push and Firebase Cloud Messaging (FCM) aren't alternatives. Expo's push service uses FCM to reach Android devices and APNs to reach iOS devices. The real decision is whether you call FCM and APNs yourself or let Expo's service do it.

Expo push serviceDirect FCM + APNs
SetupOne API, one token type (ExpoPushToken)Separate FCM and APNs integrations
PlatformsiOS and Android in a single callConfigure each platform yourself
CostFree to send, capped at 600 notifications per second per projectFCM is no-cost; APNs credentials need a paid Apple Developer account
CredentialsManaged for you with eas credentialsYou manage FCM keys and APNs certificates
ControlStandard cross-platform payloadsFull access to platform-specific features
Best forMost Expo apps; fastest path to shippingApps that already run FCM, or need platform features Expo doesn't expose

Start with Expo's service. The choice isn't locked in: getDevicePushTokenAsync() returns the native FCM or APNs token whenever you need it.

For the full side-by-side, see Expo vs. Firebase FCM. For the FCM-direct path in React Native, see the React Native push notifications guide.


Permissions setup

Permissions work differently on iOS and Android, and getting them wrong means notifications silently never arrive.

How permissions work

On iOS, the system shows the permission dialog once. If the user denies it, only Settings can turn notifications back on.

On Android 13 and later, users must opt in to notifications through a permission prompt, and the prompt doesn't appear until you've created at least one notification channel. Older Android versions grant notification permission by default.

The permission flow

TypeScript
import * as Notifications from "expo-notifications";
import Constants from "expo-constants";
import { Platform } from "react-native";

async function registerForPushNotificationsAsync(): Promise<string | undefined> {
  // On Android, create a notification channel before requesting permissions
  if (Platform.OS === "android") {
    await Notifications.setNotificationChannelAsync("default", {
      name: "Default",
      importance: Notifications.AndroidImportance.MAX,
      vibrationPattern: [0, 250, 250, 250],
      lightColor: "#FF231F7C",
    });
  }

  // Check existing permission status
  const { status: existingStatus } = await Notifications.getPermissionsAsync();
  let finalStatus = existingStatus;

  // Only request if not already granted
  if (existingStatus !== "granted") {
    const { status } = await Notifications.requestPermissionsAsync();
    finalStatus = status;
  }

  if (finalStatus !== "granted") {
    throw new Error(
      "Notification permission denied. On iOS, the user must enable notifications in Settings."
    );
  }

  // Get the Expo push token, tied to your EAS project
  const projectId =
    Constants?.expoConfig?.extra?.eas?.projectId ??
    Constants?.easConfig?.projectId;

  if (!projectId) {
    throw new Error(
      "Project ID not found. Ensure your app is configured with EAS."
    );
  }

  const token = (
    await Notifications.getExpoPushTokenAsync({ projectId })
  ).data;

  return token;
}

Because you get one shot at the iOS dialog, don't call requestPermissionsAsync() cold. Ask with your own dialog first:

TypeScript
import { Alert } from "react-native";

async function requestWithSoftPrompt(): Promise<string | undefined> {
  const { status } = await Notifications.getPermissionsAsync();

  if (status === "granted") {
    return registerForPushNotificationsAsync();
  }

  // Show a custom dialog before the system prompt
  return new Promise((resolve) => {
    Alert.alert(
      "Enable notifications?",
      "We'll send you updates about order status and delivery. You can turn these off anytime in Settings.",
      [
        { text: "Not now", style: "cancel", onPress: () => resolve(undefined) },
        {
          text: "Enable",
          onPress: async () => {
            const token = await registerForPushNotificationsAsync();
            resolve(token);
          },
        },
      ]
    );
  });
}

If the user taps Not now, the system dialog is still unused and you can ask again later, ideally right after they do something that needs notifications.


Sending push notifications

Once you have a user's ExpoPushToken, your server sends to it through Expo's push service, either with a plain HTTP request or with Expo's server SDK.

Option 1: Expo Push API directly

Send a POST request to Expo's push endpoint. It needs no authentication by default. If you turn on enhanced push security in the Expo dashboard, add an Authorization: Bearer header with your Expo access token (with the server SDK, pass accessToken to new Expo()).

TypeScript
async function sendPushNotification(expoPushToken: string) {
  const message = {
    to: expoPushToken,
    sound: "default",
    title: "Order shipped",
    body: "Your order #4821 is on its way",
    data: { orderId: "4821", screen: "OrderDetail" },
  };

  const response = await fetch("https://exp.host/--/api/v2/push/send", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Accept-Encoding": "gzip, deflate",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(message),
  });

  const ticket = await response.json();
  // Save ticket.data.id to check receipt later
}

Limits: 600 notifications per second per project, and up to 100 messages per request. Go over them and Expo returns TOO_MANY_REQUESTS or PUSH_TOO_MANY_NOTIFICATIONS. The expo-server-sdk package below handles both for you.

Checking delivery receipts

Expo returns a push ticket immediately. A ticket with status ok means Expo received your payload, not that the device got it. The receipt confirms whether Expo's attempt to hand the notification to FCM or APNs worked. Expo recommends checking receipts 15 minutes after sending, and it clears them after 24 hours:

Terminal
# 1. Send the notification
curl -X POST https://exp.host/--/api/v2/push/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
    "title": "Test",
    "body": "Hello from the server"
  }'

# 2. Check the receipt using the ticket ID
curl -X POST https://exp.host/--/api/v2/push/getReceipts \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"]
  }'

Check receipts in production. Receipt errors include DeviceNotRegistered, InvalidCredentials, and MessageTooBig, and a ticket won't show you the last two.

Option 2: Expo server SDK (Node.js)

For production backends, use the official SDK instead of raw fetch:

TypeScript
import { Expo } from "expo-server-sdk";

const expo = new Expo();

const messages = [
  {
    to: "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
    sound: "default" as const,
    title: "Welcome",
    body: "Thanks for signing up!",
  },
];

const chunks = expo.chunkPushNotifications(messages);

for (const chunk of chunks) {
  const ticketChunk = await expo.sendPushNotificationsAsync(chunk);
  // Store tickets for receipt checking
}

The SDK splits your messages into batches with chunkPushNotifications, gzips the requests, and throttles them for you.


Receiving and handling notifications

Your app handles two events: a notification arriving while it's in the foreground, and the user tapping a notification.

TypeScript
import { useState, useEffect } from "react";
import * as Notifications from "expo-notifications";

// Configure how notifications appear when the app is in the foreground
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldPlaySound: true,
    shouldSetBadge: true,
    shouldShowBanner: true,
    shouldShowList: true,
  }),
});

export default function App() {
  const [expoPushToken, setExpoPushToken] = useState("");

  useEffect(() => {
    registerForPushNotificationsAsync()
      .then((token) => setExpoPushToken(token ?? ""))
      .catch(console.error);

    // Fires when a notification is received while app is foregrounded
    const receivedSub = Notifications.addNotificationReceivedListener(
      (notification) => {
        console.log("Received:", notification.request.content);
      }
    );

    // Fires when the user taps a notification
    const responseSub = Notifications.addNotificationResponseReceivedListener(
      (response) => {
        const data = response.notification.request.content.data;
        // Navigate based on notification data
        if (typeof data?.screen === "string") {
          // router.push(data.screen)
        }
      }
    );

    return () => {
      receivedSub.remove();
      responseSub.remove();
    };
  }, []);

  // ... your UI
}

In SDK 58 and later, a foregrounded notification shows by default. In SDK 57 and earlier, it doesn't show at all unless your handler says so.

Notification behavior by app state

App stateWhat happensYour control
ForegroundhandleNotification callback fires; you decide whether to show itFull: show it, hide it, or render your own UI
BackgroundOS displays the notification automaticallyNone: the OS controls presentation
TerminatedOS displays the notification automaticallyNone: the OS controls presentation

Courier + Expo: end-to-end integration

Once you send on more than one channel (push, email, SMS, Slack), each one is another provider API to integrate. With Courier, you make one API call and Courier routes it to the right provider, with failover, templates, and message logs built in.

Step 1: Configure Expo as a provider in Courier

  1. Sign up at app.courier.com (the Developer plan is free and includes 10,000 sends a month)
  2. Go to Integrations and enable Expo as a push provider
  3. Expo doesn't need any credentials in Courier. Courier delivers using the Expo push tokens on each recipient's profile.
  4. Copy your Courier API key into an environment variable on your server. It never goes in the app.

Step 2: Register the push token with Courier

Courier stores each user's Expo push token on their profile. Your app can't call Courier with your API key, because anything in the app bundle can be extracted. So the app sends the token to your backend, and your backend saves it to Courier.

In your app, after you get the token, send it to your own endpoint, authenticated with your own session:

TypeScript
async function saveTokenOnServer(expoPushToken: string, sessionToken: string) {
  await fetch("https://api.your-app.com/push-token", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${sessionToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ expoPushToken }),
  });
}

const token = await registerForPushNotificationsAsync();
if (token) {
  await saveTokenOnServer(token, session.accessToken);
}

On your backend, resolve the user from the session and save the token to their Courier profile:

TypeScript
import Courier from "@trycourier/courier";

const courier = new Courier({ apiKey: process.env.COURIER_API_KEY });

// Handler for POST /push-token. Take userId from your session, not the request body.
export async function savePushToken(userId: string, expoPushToken: string) {
  await courier.profiles.create(userId, {
    profile: {
      expo: {
        token: expoPushToken,
      },
    },
  });
}

profiles.create calls POST /profiles/{user_id}, which merges into the profile and creates it if it doesn't exist. To reach several devices, pass an array to expo.tokens instead. Courier's Expo docs cover both forms.

Step 3: Send through Courier

Now send notifications from your backend. Naming expo in routing.channels sends through the Expo provider:

TypeScript
import Courier from "@trycourier/courier";

const courier = new Courier({ apiKey: process.env.COURIER_API_KEY });

async function sendViaCourier(userId: string) {
  const { requestId } = await courier.send.message({
    message: {
      to: {
        user_id: userId,
      },
      content: {
        title: "Your order shipped",
        body: "Order #4821 is on the way. Tap to track.",
      },
      routing: {
        method: "single",
        channels: ["expo"],
      },
    },
  });

  return requestId;
}

Step 4: Multi-channel routing with failover

Send push first. If it can't be delivered, Courier tries SMS, then email:

TypeScript
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user-123",
    },
    content: {
      title: "Payment failed",
      body: "We couldn't charge your card for your subscription. Update your payment method to keep your plan.",
    },
    routing: {
      method: "single",
      channels: ["expo", "sms", "email"],
    },
  },
});

Courier reads the Expo token, phone number, and email address from the user's profile, tries each channel in order, and stops at the first one that delivers. A channel fails when the user has no address for it or the provider returns an error (Courier retries transient errors first), and Courier moves to the next. A user who never granted push permission gets the SMS.

Why route Expo push through Courier?

Direct Expo Push APIExpo push via Courier
Push onlyPush, email, SMS, Slack, and 50+ providers
No fallback logicConfigurable failover chains
Raw token managementUser profiles that hold device tokens and addresses for every channel
Build your own analyticsBuilt-in delivery analytics and logs

Expo's push service still does the last mile to APNs and FCM. Courier sits between your backend and Expo, and any Expo message field you need (ttl, sound, and the rest) goes through providers.expo.override, as Courier's Expo docs show.


How much do Expo push notifications cost?

Expo's push notification service is free: there's no per-notification charge. It isn't uncapped, though. Expo limits sends to 600 notifications per second per project.

Delivery pathCost
Expo push serviceFree
Apple Push Notification service (APNs)Credentials need a paid Apple Developer account
Firebase Cloud Messaging (FCM)No-cost
Expo Build (optional, for credentials and builds)Free tier, paid plans for higher usage

Real costs start when you add other channels. Email and SMS run through paid providers like SendGrid and Twilio, and wiring several of them together is where the engineering time goes. Courier's Developer plan is free and includes 10,000 sends a month.


Troubleshooting

ExpoPushToken not generating

Symptoms: getExpoPushTokenAsync() hangs indefinitely or throws an error.

CauseFix
Unsupported simulator or emulatorUse a physical device, an Android Emulator with Google Play services, or an iOS Simulator on Xcode 14 or later (macOS 13+, iOS 16+).
Missing projectIdPass projectId explicitly: getExpoPushTokenAsync({ projectId }). Get it from Constants.expoConfig.extra.eas.projectId.
No internet connectionThe device must reach Expo's servers to register for a token. Check connectivity.
Testing push in Expo Go, SDK 53+Expo Go doesn't support push notifications from SDK 53. Build a development build.

Notifications not showing in a simulator or emulator

Remote push won't arrive on an Android Emulator without Google Play services or on an iOS Simulator below Expo's minimum (Xcode 14, macOS 13, iOS 16). You can still test your handler and listener code there: schedule a local notification with scheduleNotificationAsync(), then confirm remote push on a physical device.

Push notification not received in background state

Symptoms: Notifications arrive when the app is in the foreground but not when backgrounded or killed.

CauseFix
Low priorityExpo's default priority is normal on Android and high on iOS. Set priority: "high" in your push message so Android delivers promptly, especially with battery optimization enabled.
Missing notification channel (Android)Create a channel with setNotificationChannelAsync() before sending. Android 8+ requires channels.
Battery optimization killing the appSome Android manufacturers (Xiaomi, Huawei, Samsung) aggressively kill background apps. Direct users to dontkillmyapp.com for device-specific instructions.
Silent notification not waking the app (iOS)For a silent or data-only notification, set contentAvailable: true in your Expo push message. Apple recommends no more than two or three of these per hour.
Revoked or missing credentialsAPNs push keys don't expire, but revoking one stops push for every app that uses it until you upload a replacement. Check your credentials with eas credentials.

Notifications work in development but not in production

This almost always means credentials are misconfigured.

  • Android: You need FCM V1 credentials. Follow the FCM credentials guide.
  • iOS: Development and production builds need your own APNs push key. Run eas credentials to generate one.

DeviceNotRegistered error

The device can't receive push notifications anymore, usually because the user uninstalled the app. Stop sending to this token and remove it from your database.

Notification icon is a gray/white square (Android)

Android needs a notification icon that's all white on a transparent background. Anything with color or an opaque background shows up as a solid square. Set a 96x96 PNG in the config plugin:

JSON
{
  "expo": {
    "plugins": [
      ["expo-notifications", { "icon": "./assets/notification-icon.png" }]
    ]
  }
}

The icon is baked into the binary, so rebuild the app after you change it.


Full working example

This component registers for push, sends itself a test notification, and shows what it receives. Sending from the app is fine for a test. In production, send from your server.

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

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

async function registerForPushNotificationsAsync(): Promise<string | undefined> {
  if (Platform.OS === "android") {
    await Notifications.setNotificationChannelAsync("default", {
      name: "Default",
      importance: Notifications.AndroidImportance.MAX,
      vibrationPattern: [0, 250, 250, 250],
      lightColor: "#FF231F7C",
    });
  }

  const { status: existingStatus } = await Notifications.getPermissionsAsync();
  let finalStatus = existingStatus;

  if (existingStatus !== "granted") {
    const { status } = await Notifications.requestPermissionsAsync();
    finalStatus = status;
  }

  if (finalStatus !== "granted") {
    alert("Permission denied. Enable notifications in Settings.");
    return;
  }

  const projectId =
    Constants?.expoConfig?.extra?.eas?.projectId ??
    Constants?.easConfig?.projectId;

  if (!projectId) {
    alert("Project ID not found");
    return;
  }

  return (await Notifications.getExpoPushTokenAsync({ projectId })).data;
}

async function sendPushNotification(token: string) {
  await fetch("https://exp.host/--/api/v2/push/send", {
    method: "POST",
    headers: {
      Accept: "application/json",
      "Accept-Encoding": "gzip, deflate",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: token,
      sound: "default",
      title: "It works!",
      body: "Push notification received successfully.",
      data: { test: true },
    }),
  });
}

export default function App() {
  const [expoPushToken, setExpoPushToken] = useState("");
  const [notification, setNotification] = useState<
    Notifications.Notification | undefined
  >();

  useEffect(() => {
    registerForPushNotificationsAsync()
      .then((token) => setExpoPushToken(token ?? ""))
      .catch(console.error);

    const receivedSub = Notifications.addNotificationReceivedListener(
      (notification) => setNotification(notification)
    );

    const responseSub =
      Notifications.addNotificationResponseReceivedListener((response) => {
        console.log("User tapped notification:", response);
      });

    return () => {
      receivedSub.remove();
      responseSub.remove();
    };
  }, []);

  return (
    <View
      style={{
        flex: 1,
        alignItems: "center",
        justifyContent: "space-around",
        padding: 20,
      }}
    >
      <Text selectable>Token: {expoPushToken}</Text>
      <View style={{ alignItems: "center" }}>
        <Text>Title: {notification?.request.content.title}</Text>
        <Text>Body: {notification?.request.content.body}</Text>
        <Text>
          Data: {notification && JSON.stringify(notification.request.content.data)}
        </Text>
      </View>
      <Button
        title="Send test notification"
        onPress={() => sendPushNotification(expoPushToken)}
      />
    </View>
  );
}

Frequently asked questions

Does the ExpoPushToken expire?

No. Expo says an ExpoPushToken never expires. On Android, reinstalling the app may generate a new token. On iOS, the token survives reinstalls. If a user uninstalls, you'll receive a DeviceNotRegistered error: stop sending to that token.

Can I send push notifications to multiple devices at once?

Yes. The to field in the Expo push API takes a single token or an array of tokens, and one request can carry up to 100 messages. The server SDK's chunkPushNotifications splits a longer list into batches for you. With Courier, store several tokens in the profile's expo.tokens array and send to the user_id.


What's next

Push is one channel. If you also send receipts by email, verification codes by SMS, or updates to an in-app inbox, each one is another SDK, another set of credentials, and another log to check. Courier puts them behind one API: connect Expo, Firebase FCM, APNs, SendGrid, Twilio, or any of 50+ providers, then send to any channel with one call, with routing, failover, and user preferences handled for you.

Start free with 10,000 sends a month.