📘

Blog post

Four Ways to Use the OneSignal Integration with HubSpot to Boost Engagement Across Channels

HubSpot and OneSignal have partnered to automate sending push notifications, email, SMS and edit data tags for showing in-app messages using Workflows. You can also view OneSignal activity on contacts' timelines and segment users based on OneSignal activity.

You need to use OneSignal independently for more advanced functionality like A/B testing, intelligent delivery, throttling, retargeting etc.

Requirements

• You must be a HubSpot Super Admin or have App Market Permissions in your HubSpot account.
• Create A OneSignal Account if you do not already have one.
• The OneSignal Mobile SDK and/or Web SDK from which you want to send data.

Setup

📘

Updated integration

At the end of 2024, HubSpot will be deprecating their OneSignal app, and OneSignal now provides our own HubSpot app to provide the same functionality.

Follow the steps below if you previously used the HubSpot integration and need to migrate to the new version.

Migrating to the new HubSpot integration steps (click to expand)

Installing the new HubSpot integration

As described in the general guide, users will now need to activate the HubSpot integration from their OneSignal dashboard, in the Integrations section of their App's Settings.

Migrating your workflows

We strongly recommend creating a new workflow to test the new integration before replacing the Actions in your existing Workflows.

Clone your workflow

On the Workflows page in HubSpot, you can click the Clone button next to your existing workflow to create a new copy of it.

Remove triggers from the new workflow

After cloning it, you should first remove any triggers in the newly created Workflow. This will ensure that you can publish the new workflow without inadvertently triggering it automatically.

Update legacy OneSignal actions with the new versions

You can then go through your workflow, removing all legacy OneSignal actions and replcaing them with the new one. Since you will likely have both the legacy OneSignal app installed while also using the new OneSignal-built integration, it will be important to be careful to ensure that you are creating actions from the new app. The legacy app will have the text "Built by HubSpot".

Test the workflow

After you replace the workflow actions and save & publish your workflow, you will be able to manually enroll contacts to test the workflow. We recommend you do this with just a single test contact at first, to ensure the workflow works correctly.

After enrolling the contact, you will be able to view the enrollment history of the workflow to see if actions were successful. If you have any unexpected errors, please contact OneSignal support.

Install HubSpot on OneSignal

In OneSignal, go to your app's Integrations page, then select Activate under HubSpot. Click Authenticate, then log in to your HubSpot account. You may be asked to select which one of your accounts you'd like to use.

Define the HubSpot workflow

Within HubSpot, navigate to Automation > Workflows and click Create workflow.

In the left panel, select Contact-based and Next in the top right.

Set your enrollment triggers, then click + to add an action.

In the left panel, under OneSignal, choose an option:

Send OneSignal Notification Workflow Action

First, Select your OneSignal App.

Second, choose how the contact will be mapped to a OneSignal user - either by External ID or email.

• Select Email if you are going to be sending an email with a OneSignal template.
• If you select External ID, then you must select which HubSpot Contact Property contains OneSignal External IDs. We recommend against using the "Record ID" field, as that field can potentially change when HubSpot contacts are merged. One option is to create Custom Properties in HubSpot and populate them with OneSignal External IDs.

You will then have the option to send a message using a template or by defining a push notification directly inside the workflow

Click Save when finished.

Edit OneSignal tags workflow action

OneSignal uses Data Tags for adding custom properties onto users. Tags can be used to add HubSpot Contact Properties into OneSignal for Message Personalization and/or Segmentation and sending In-App Messages.

Select your OneSignal App, a mapping field that identifies your contact with a OneSignal External ID and enter a JSON string with the format { "key" : "value" } and press Save.

You can delete tags by setting the "value" to an empty string like this: { "key" : "" }. This is helpful if you have tag data in OneSignal you want deleted.

Within the OneSignal Dashboard Audience, select New Segment. Give it a name based on the tags selected and select the User Tag filter.

Input the "key" and "value" set in HubSpot and click Create Segment.

Navigate to Messages > In-App and select New In-App.

Name your new IAM so you can identify it in the dashboard.

Under "1. Audience" select Show to Particular Segment(s) and select your newly created segment.

As users go through the HubSpot workflow, they will get tagged which will put them immediately into this segment. Note: getting a tag does not trigger the IAM. More details below in Trigger Options.

For "2. Message" follow the Sending In-App Messages Guide for details on creating your In-App Message.

Trigger options

In-App Messages need to be triggered to show on the device. Triggers can be time-based or programmatic. Note: a tag is not a trigger. If the tag is added while the device is currently using the app, the IAM will not display. The In-App Message will show the next time the user returns to your app in a new session. New sessions are counted upon the app being out-of-focus for 30 seconds.

Under "3. Triggers" you can set the IAM to display based on the following triggers:

• On App Open
• Session Duration > or < a set number of seconds
• Duration since another IAM was shown
• Programmatically with the OneSignal SDK

Triggers can be combined with "AND" operators and separated into multiple options with "OR" operators.

See How to trigger an IAM guide for more details.

Workflow history

Navigate to your HubSpot Workflows and within the desired Workflow select the History tab.
Here you will be able to see which contacts were sent notifications and updated tags.

Error messages

1. "No OneSignal Devices matched this contact's external_user_id property [THE_VALUE_OF_EXTERNAL_ID_HUBSPOT_CONTACT_PROPERTY]"
   In these cases, the targeted user does not have a matching External ID.
2. "No OneSignal Devices matched any of this contact's email addresses [[email protected]]"
   The targeted user does not have a matching email address in OneSignal.
3. An unknown error occurred
   This can occur for various reasons internal to HubSpot. One potential situation in which this error appears is when you are trying to send a Contact through your workflow and your OneSignal workflow action is configured to use a HubSpot Custom Property that is not defined for the Contact.

FAQ

What data is shared between HubSpot and OneSignal?

Additional Details

Please check HubSpot for more information.