> ## Documentation Index
> Fetch the complete documentation index at: https://hercules.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Push Notifications

> Send push notifications to users. Setup, permissions, manual sends, event-triggered, and scheduled notifications.

Send notifications to your users' devices. Hercules manages push notifications end-to-end: setup, permissions, and delivery.

<div className="screenshot candy">
  <img src="https://mintcdn.com/zeus-0f6dadbf/vyfZOWPi9KdyCPiO/images/apps/push-notification-example.png?fit=max&auto=format&n=vyfZOWPi9KdyCPiO&q=85&s=b0079c82517697b33986f472be7cebfd" alt="Send push notifications in Hercules" width="874" height="699" data-path="images/apps/push-notification-example.png" />
</div>

## Set up push notifications

Just ask Hercules to: `Set up push notifications for my app, making sure to handle enabled, disabled, and not available states`.

### Prompt users to opt into notifications

We strongly recommend your app handles all of the following 4 permission states.

| Status                      | What to show                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------ |
| **Not enabled**             | Show a pre-prompt explaining why notifications are valuable, then request permission |
| **Explicitly enabled**      | n/a (Notifications work normally)                                                    |
| **Explicitly disabled**     | Guide user to device settings to re-enable (you cannot re-prompt them to enable)     |
| **Not available on device** | Hide notification-related UI or explain limitations                                  |

<Tip>
  For the best experience, prompt users when notifications are most relevant (e.g. after they place
  an order) rather than immediately on first visit.
</Tip>

## Send notifications

### From the Hercules UI

Go to the **Push Notifications** tab to send notifications manually.

<Steps>
  <Step title="Select recipients">
    Choose to send to all subscribers, or search and select specific users.

    <div className="screenshot purple">
      <img src="https://mintcdn.com/zeus-0f6dadbf/vyfZOWPi9KdyCPiO/images/apps/push-notification-select-users.png?fit=max&auto=format&n=vyfZOWPi9KdyCPiO&q=85&s=e351db0670b6943d3181532e37663992" alt="Select users to send push notifications" width="2372" height="1278" data-path="images/apps/push-notification-select-users.png" />
    </div>
  </Step>

  <Step title="Compose your message">
    Write a title (required) and body (optional). Keep messages short and valuable.

    <div className="screenshot purple">
      <img src="https://mintcdn.com/zeus-0f6dadbf/vyfZOWPi9KdyCPiO/images/apps/push-notification-example.png?fit=max&auto=format&n=vyfZOWPi9KdyCPiO&q=85&s=b0079c82517697b33986f472be7cebfd" alt="Compose push notification message" width="874" height="699" data-path="images/apps/push-notification-example.png" />
    </div>
  </Step>

  <Step title="Send">Click **Send Notification** to deliver immediately.</Step>
</Steps>

### Triggered by events

Send notifications automatically when something happens in your app. Ask Hercules:

* *"Send a notification when an order is placed"*
* *"Notify users when their order ships"*
* *"Send a notification when an order is out for delivery"*
* *"Notify users when their order is delivered"*

### Scheduled from your app

Schedule notifications to send at specific times or after delays. Ask Hercules:

* *"Send a welcome notification 1 hour after sign up"*
* *"Remind users about abandoned carts after 24 hours"*
* *"Let me schedule notifications from an admin page"*

## Test push notifications

Push notifications **do not work in Hercules preview**. Follow the [mobile app testing instructions](/apps/mobile/test-mobile) to test on a real device:

1. Publish your app
2. Install on a real device (Add to Home Screen)
3. Grant notification permission when prompted
4. Send a test notification from **Mobile → Push Notifications**

## FAQ

<AccordionGroup>
  <Accordion title="Do notifications work in Hercules preview?">
    No. Push notifications do not work inside the Hercules preview. You must test on a published URL
  </Accordion>

  <Accordion title="Can I send notifications to specific users?">
    Yes. From the Push Notifications UI, search by email, name, or visitor ID to select specific
    users.
  </Accordion>

  <Accordion title="How do I re-request permission if a user denied?">
    You can't re-prompt programmatically. Guide users to their device settings to enable notifications
    for your app. Show a helpful message with instructions.
  </Accordion>

  <Accordion title="Do notifications work on iOS Safari?">
    Yes, as of iOS 16.4+. Users must add your PWA to home screen first. Notifications won't work from
    Safari directly, only from the installed PWA.
  </Accordion>

  <Accordion title="What can I customize in a notification?">
    * **Title:** Bold headline (keep it short, max 200 characters) - **Body:** Main message (optional,
      max 500 characters) **Known limitation:** Notifications currently can't deep-link to a specific
      screen. They open the app generically. Deep linking is planned.
  </Accordion>
</AccordionGroup>