📘

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.

Legacy Customers only: Migrating to the new HubSpot integration (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

While it's not required, we recommend creating a new workflow to test the new integration before replacing the Actions in your existing Workflows. Some users also maintain separate staging and production HubSpot environments for testing purposes.

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.

After testing the workflow successfully, you can either replace the original Workflow with the copy, or make the same changes in the original workflow.

Install HubSpot on OneSignal

In OneSignal, go to your app's Data > Integrations page and under HubSpot select Activate.

Click Authenticate, then log in to your HubSpot account. You may be asked to choose which HubSpot account you'd like to use.

Once you agree to the terms and select Connect app, you will be redirected to your OneSignal app and will need to open the newly connected HubSpot account.

Set the OneSignal External ID

In order to match users in HubSpot with users in OneSignal, you will need to set the External ID identifier in OneSignal to be the same value as some unique user property you collect within HubSpot. You will use this to match within your HubSpot workflows described below.

External ID can be set in a number of ways, but it is highly recommended to use a property readily available in your mobile app or website so you can set it on your user's push Subscriptions with our SDK login method.

📘

Users & subscriptions

Please review our Users and Subscriptions docs for more details.

---

Define a HubSpot workflow

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

Select Contact-based and configure your enrollment.

To add the OneSignal action, click the + and search for OneSignal.

Our workflow actions allow you to set Tags (which are custom user properties or events) and send messages. To use either action, you must first define a couple properties:

OneSignal App field

This is the OneSignal app you connected to the HubSpot account during the initial setup instructions above.

External ID field

This is the property you set on your users in your OneSignal app that matches a property set in HubSpot.

📘

Users & subscriptions

Please review our Users and Subscriptions docs for more details.

Add or Edit a Users Tags in OneSignal

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

Tags field

Enter a JSON string with the format { "key1" : "value1", "key2" : "value2" } and press Save.

You can inject HubSpot properties as tags so they are stored in OneSignal. An example of this is adding the user's name as a tag so you can address the user by their name in their messages.

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. If the tag doesn't exist, it will be omitted.

📘

Sending in-app message with HubSpot

Using tags, you can create a segment for these users which can be used for in-app messages. See below FAQ: How can I send in-app messages with HubSpot? for details.

Send OneSignal notification

You can send a push notification by filling out the form provided or select predefined Templates.

It is recommended to Match by OneSignal external_id as the matching by Email is for legacy customers or if you set email using our addEmail SDK method.

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

Templates option

You can create Templates in the OneSignal dashboard or our API. By using templates, you can send SMS, Email, or push notifications.

Form fields option

If you don't use a template, you can only send push notifications using text into various fields (Title, Subtitle, Message, Image URL, Launch URL). Email and SMS can only be used via templates.

The benefit of this option is you can also use HubSpot contact data (e.g., First Name, favorite color) to personalize the notification fields. OneSignal will correctly format the message for different devices and messaging channels.

Click Save when finished.

---

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?

How can I send in-app messages with HubSpot?

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.