Gravity Forms OneSignal Premium Add-on Setup Guide

Video walkthrough

4:52

Gravity Forms OneSignal Add-On Setup Guide: Push Notifications (WordPress Side)
Video setup guide: Gravity Forms OneSignal Watch on YouTube

The Gravity Forms OneSignal Premium Add-on connects your Gravity Forms to OneSignal so that every submission can send a web or mobile push notification to your audience. When someone fills in a form, the add-on creates a notification through the OneSignal REST API with a heading and content built from your form fields, sent to a segment, to specific external user ids, or to everyone who matches a data tag — and, when you want it, a launch URL, an image and custom data.

Everything happens on your own OneSignal app through the OneSignal REST API, with your own App ID and REST API key. The add-on never blocks your form: the visitor sees your normal confirmation, and the notification is created quietly on your server afterwards. A failed call is written to the entry as a clear note rather than shown to the person filling in the form.

What you need

• WordPress with Gravity Forms 2.9 or newer.
• PHP 7.4 or newer.
• An active license key for this add-on.
• A OneSignal account with an app set up for web or mobile push, and some subscribers.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else, so a form is never left half connected.

Get your OneSignal App ID and REST API key

The add-on signs in to OneSignal with two credentials of your own, and both are entirely self-serve. The App ID identifies the OneSignal app that is sending the notifications, and the REST API key authorises the request.

Sign in to OneSignal and open your app, then go to Settings → Keys & IDs. Copy your OneSignal App ID (it is a UUID), and copy or generate a REST API key. There is nothing to approve with us and no partner onboarding; the App ID and the key belong to your OneSignal account.

The settings page

Install and activate the add-on like any plugin, after Gravity Forms. Then open Forms → Settings → OneSignal. This one page holds the license key and your OneSignal connection.

Your App ID, your key and the Send test button

Enter the App ID and the REST API key you copied from OneSignal. The key is stored encrypted at rest, so the plain value is never left sitting in the database. After it is saved it is shown masked, and you can replace it at any time. If you would rather keep the key out of the database entirely, define the GFOS_APP_ID and GFOS_REST_API_KEY constants in wp-config.php and the add-on uses those instead.

Press Send test to send a short test notification to your Subscribed Users segment with the App ID and key above. If it arrives, you are connected. If something is wrong, the page shows a clear message — and that message never contains your App ID or key.

Add a notification to a form

Open the form you want to send notifications for, go to Settings → OneSignal on that form, and add a feed. A feed is one notification rule: it decides the heading, the content, who receives it and the extras.

Heading and content

Write the heading and the content using merge tags, so each notification carries the details of the submission. For example a heading of New message from {Name (First):1.3} and content that includes {Subject:3} and {Message:4}. The content is required; if it ends up empty after the merge tags are filled in, nothing is sent and a note explains why. Leave the heading empty to use your OneSignal app default.

Who to notify

Choose who receives the notification. Send to a segment (the default is Subscribed Users, and you can name any of your own segments, separated by commas); send to specific external user ids, which you can map from a field so the person who submitted the form gets their own notification; or send to everyone who matches a tag filter, for example the tag role equal to manager.

Extras, and the condition

Add an optional launch URL opened when the notification is tapped, an image URL shown with the notification, and custom data (one key: value per line) passed through for your app. Finally, use the condition to send a notification only when a rule is met, for example only when a priority field is set to “Urgent”.

What your visitors see

Nothing changes for the person filling in the form. They submit it and see your normal confirmation; the push notification is created on your server afterwards.

On the entry

Each entry keeps a note of what happened and the OneSignal notification id and recipient count, so you have a record of every notification. You can use the {onesignal_id} and {onesignal_recipients} merge tags in your own Gravity Forms notifications, and the add-on adds two notification events — OneSignal notification sent and OneSignal notification failed — that you can attach e-mails to.

Retries are safe

A notification is created once per entry. If you resend an entry, or a submission is processed twice, the add-on sees that it has already sent for that feed and does not create a second notification. A feed that is already running for an entry is never sent twice at the same time either.

Privacy and security

Your OneSignal REST API key is encrypted before it is stored, and it is never shown again, never written to an entry and never written to a log — even when OneSignal sends back an error that echoes it. The add-on only ever contacts the OneSignal REST API at api.onesignal.com over HTTPS, it never follows a redirect to another host, the key travels in the Authorization header and the App ID in the request body, never in the address. When you uninstall the add-on, its settings (including the encrypted key) are removed; notifications already delivered to your subscribers are, of course, left as they are.

Troubleshooting

• The test says the App ID or key is not valid. The App ID is a UUID and the REST API key is the long key from Settings → Keys & IDs in OneSignal. Copy both exactly.
• The note says no recipients, or the players are not subscribed. The segment or ids you targeted have no subscribed devices yet; add subscribers in OneSignal and try again.
• The entry note says the notification had no content or no target. The content is required and you must choose a segment, external ids or a tag; make sure the merge tags map to fields that are filled in.
• External user ids do not match. The ids must be the external user ids you set on your subscribers in OneSignal; map the right field into the External user ids box.