HubSpot

Integrating OneSignal with HubSpot

📘

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

Setup

1. Install OneSignal on HubSpot

In HubSpot, click the Marketplace icon in the main navigation bar, then select App Marketplace. Search for and select the OneSignal integration, then click Install app.

2048

Navigate to your OneSignal Dashboard Settings > Keys & IDs to copy-paste the App ID and REST API Key into your app. You can add multiple OneSignal Apps if needed.

645

2. Map a OneSignal Property to HubSpot

Within HubSpot Settings > Integrations > Connected Apps > OneSignal > Your preferences select the HubSpot Contact property you wish to match to OneSignal. This should be available client-side and accessible to the OneSignal SDK.

Using the OneSignal SDK on your app or website, set the External ID to match the selected HubSpot Contact Property. It is recommended to call this method whenever the user logs into your Website, Android, and/or iOS Apps.

3. Defining 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

Select your OneSignal App and matching option. You will then have the option to send a message using a template or a custom configuration.

918
OptionDescription
Use templatesYou can create Templates in the OneSignal Dashboard for your common use cases. Notification, SMS, and Email templates created in OneSignal will be pulled into HubSpot.
Use custom configurationYou can also select “Create custom message” as an option and use various fields (Title, Subtitle, Message, Image URL, Launch URL) to create the push notification. Email and SMS uses templates only.

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.

Edit OneSignal device's 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 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.

912

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.

4. 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.

3754

Error Messages

"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.

"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.

FAQ

What data is shared between HubSpot and OneSignal?

HubSpotDirectionOneSignal AppDescription
Contacts➡️UsersHubSpot Contact email addresses are used to match OneSignal Users / Devices
Events⬅️MessageOneSignal messages are logged on Contact Activity Timeline and available for List segmentation in HubSpot
Workflows⬅️Message TemplatesOneSignal Message Templates are available for selection in HubSpot Workflows

Additional Details

Please check HubSpot for more information.

Can I connect multiple HubSpot accounts to a single OneSignal app?

Yes, as long as the External ID in the OneSignal app matches a property in the HubSpot projects, you can setup OneSignal on multiple HubSpot projects.