How to send push notifications to your visitors

In a TeleportHQ web app, you can send push notifications: short messages that pop up on a visitor's phone or computer, even when your site is closed. Visitors subscribe through a Subscribe to Push workflow step, usually behind a "Turn on notifications" button. You set push up once by clicking Set up push notifications in the step. A Send Push Notification step then sends a title, a text and a link to everyone subscribed, to one signed-in user or to one browser.

Before you start#

• Push notifications are sent by workflows, so your project must be a web app. On a website, starting a workflow opens the Enable Web App features? window first. See How to turn a website into a web app.
• They only work on your published site. Publish after you set them up. See How to publish a web app.
• iPhone and iPad only show notifications from a site the visitor added to their Home Screen. To let them, tick Make this site installable (PWA) in the Installable app section of the Publish window. See How to make your site installable as an app (PWA).
• To send to one signed-in user, your site needs user accounts. See How to add sign-up and login to your site.

Steps#

This example lets a bakery's customers get a notification when fresh croissants come out of the oven.

1. Let visitors subscribe#

Browsers ask visitors for permission before they show notifications. Safari and Firefox only ask after the visitor clicks something, so start the Subscribe to Push step from a button.

1. Add a button with the text Turn on notifications to your page, and select it.
2. In the right panel, in the Workflows section, click On Click, then Create new workflow. See How to run a workflow when a button is clicked.
3. In the workflow, click the round + (Add node) below the trigger box.

4. In the Add Node menu, type push in Search nodes.... Two categories are left: Push Notifications and Browser.

   

5. Point at Browser and click Subscribe to Push.
6. In the right panel, the step's settings say "Push notifications are not set up yet." Click Set up push notifications. TeleportHQ creates the keys that sign your notifications, and a table in your TeleportHQ database for the browsers that subscribe (it creates the database first if the project has none).
7. A message confirms "Push notifications are set up. Publish your project to start using them." The step now says "Push notifications are set up for this project."

You set push up once per project. Every push step shows the same setup box, and any of them can do it.

2. Send a notification#

1. Open the workflow that should send the notification. For example, a Scheduled (Cron) workflow that runs every morning at 7 AM. See How to run a workflow on a schedule.
2. Click the round + (Add node) where the notification should go.
3. Point at Push Notifications and click Send Push Notification.
4. In the right panel, fill in the notification:
   • Title (required, up to 200 characters): Fresh croissants are out!
   • Text (up to 1000 characters): Order before noon and pick them up warm.
   • Link: /menu. This is the page that opens when the notification is clicked: a path of your site or an https address. Leave it empty to open your home page.
5. Under Send to, choose who receives it:
   • Everyone subscribed: every browser that subscribed.
   • One signed-in user: fill in User with that user's id, for example from the Context panel. Every browser they subscribed from while signed in receives it.
   • One browser: fill in Subscription with the endpoint that a Subscribe to Push step returned.
6. Optional settings:
   • Image: a large https picture that some systems show in the notification.
   • Icon: a small picture. Your app's icon, or the favicon, is used when it's empty.
   • Tag: a later notification with the same tag replaces this one instead of stacking, for example daily-bake.
   • Urgency: Very low, Low, Normal or High. High reaches phones in battery saving sooner.
   • Keep trying for (seconds): how long to keep trying a device that's offline, up to 28 days. One day when it's empty.
   • Require interaction: Yes keeps the notification on screen until it's clicked or dismissed.
   • Silent: Yes shows it without sound or vibration.
7. Publish your site.

Send Push Notification runs on the server, so it also works in scheduled and webhook workflows. Subscriptions that a browser dropped or that expired are removed from your list along the way.

3. Let visitors turn notifications off#

Two more steps in the Browser category of the TeleportHQ Add Node menu help visitors manage their subscription:

• Unsubscribe from Push stops notifications to this browser and deletes its saved subscription. Put it on a Turn off notifications button's On Click workflow.
• Get Push Subscription checks, without asking the visitor anything, whether this browser can receive notifications and whether it's subscribed. Run it when the page loads to show the right button: its results include supported, permission and subscribed.

Visitors can also block notifications from your site in their browser's settings.

Check that it worked#

1. Open your published site, click Turn on notifications and allow notifications when the browser asks.
2. Run the workflow that sends the notification. A scheduled workflow runs at its next time.
3. The notification appears on your device, even if the site's tab is closed. Click it: your Link page opens.

The Send Push Notification step returns sent, failed and removed counts. Push steps can't be run with Test this node… in the editor, so check them on your published site.

Troubleshooting#

"Push notifications are not set up yet. Setting them up creates the keys that sign your notifications and a table in your TeleportHQ database for the browsers that subscribe." Click Set up push notifications in the step, then publish.

"This project has no private key for push notifications: a copied project does not bring its keys along. Set them up again to create new ones." The project is a copy, and a copy doesn't bring its push keys along. Click Set up push notifications to create new keys, then publish.

"Push notifications could not be set up. Please try again." Click Set up push notifications again. Setting up is safe to repeat: it only adds what's missing.

The browser never asks the visitor for permission Start Subscribe to Push from a click, not when the page loads. Safari and Firefox ignore requests made while a page loads.

A visitor on iPhone or iPad gets nothing They need to add your site to their Home Screen first. Tick Make this site installable (PWA) in the Installable app section of the Publish window, then publish. See How to make your site installable as an app (PWA).

Good to know#

• Your push keys are in Project settings → Integrations → Push notifications, which appears once push is set up. Create new keys there only if the private key was shared by mistake. See What are the Custom files and Push notifications settings?.
• Show Notification in the Browser category is different: it shows a notification only while the visitor has your page open. Push notifications reach visitors when your site is closed.
• Very large audiences: when sending takes long, the rest is sent in the background, and the step's complete result is false.
• Subscribe to Push links the subscription to the signed-in user, if there is one, so One signed-in user can reach every browser that person subscribed from.