OneSignal Push Integration with Novu

This guide walks you through the entire process of configuring and using OneSignal with Novu, from getting your credentials to sending your first notification. OneSignal supports sending messages via both Apple Push Notification Service (APNs) and Firebase Cloud Messaging (FCM).

Configure Onesignal with Novu

Before you can send push notifications via OneSignal from Novu, you need to connect your OneSignal credentials.

Step 1: Get your OneSignal credentials

To configure the OneSignal integration, you need an active account that has credentials for APNS, FCM, or both, and have access to two values from OneSignal app’s settings:

App ID
App API Key

Follow this OneSignal guide to see how to access your OneSignal App ID and App API key.

Step 2: Connect Onesignal to Novu

Next, add these keys to your OneSignal integration in the Novu dashboard.

Open the Novu Dashboard.

Open Integration Store

On the Novu dashboard, navigate to the Integration Store.

Connect a provider

In the Integration Store, click Connect provider to begin setup.

Select Push tab

Select OneSignal

In the Push tab, choose OneSignal from the provider list.

Paste credentials

In the OneSignal integration form, paste your App ID and App API Key into the corresponding fields.

Create the integration

Review your credentials, then click Create Integration to save.

Using Onesignal with Novu

Once your integration is configured, you can start sending push notifications by registering your subscribers’ player_id tokens and triggering a workflow.

Step 1: Add subscriber device token

When you set up the OneSignal SDK in your application, your users are automatically assigned a unique OneSignal player_id. This ID is used to target the user for push notifications. To target a OneSignal user from Novu, you must register their player_id as the deviceToken for their Novu subscriber profile. You can do this by making an API call to update the subscriber’s credentials.

import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";

const novu = new Novu({ secretKey: "<NOVU_SECRET_KEY>" });

await novu.subscribers.credentials.update(
  {
    providerId: ChatOrPushProviderEnum.OneSignal,
    integrationIdentifier: "string",
    credentials: { deviceTokens: ["token1", "token2", "token3"] },
  },
  "subscriberId"
);

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.subscribers.credentials.update(
        subscriber_id="subscriberId",
        update_subscriber_channel_request_dto={
            "provider_id": novu_py.ChatOrPushProviderEnum.ONESIGNAL,
            "credentials": {"deviceTokens": ["token1", "token2", "token3"]},
            "integration_identifier": "string",
        },
    )

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Subscribers.Credentials.Update(context.Background(), "subscriberId", components.UpdateSubscriberChannelRequestDto{
    ProviderID: components.ChatOrPushProviderEnumOneSignal,
        IntegrationIdentifier: novugo.String("string"),
    Credentials: components.ChannelCredentials{
        DeviceTokens: []string{"token1", "token2", "token3"},
    },
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()->setSecurity('<NOVU_SECRET_KEY>')->build();

$sdk->subscribersCredentials->update(
    subscriberId: 'subscriberId',
    updateSubscriberChannelRequestDto: new Components\UpdateSubscriberChannelRequestDto(
        providerId: Components\ChatOrPushProviderEnum::OneSignal,
        integrationIdentifier: 'string',
        credentials: new Components\ChannelCredentials(
            deviceTokens: ['token1', 'token2', 'token3'],
        ),
    ),
);

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.Subscribers.Credentials.UpdateAsync(
    subscriberId: "subscriberId",
    updateSubscriberChannelRequestDto: new UpdateSubscriberChannelRequestDto() {
        ProviderId = ChatOrPushProviderEnum.OneSignal,
        IntegrationIdentifier = "string",
        Credentials = new ChannelCredentials() {
            DeviceTokens = new List<string> { "token1", "token2", "token3" },
        },
    });

import co.novu.Novu;
import co.novu.models.components.*;
import java.util.List;

Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

novu.subscribers().credentials().update()
    .subscriberId("subscriberId")
    .body(UpdateSubscriberChannelRequestDto.builder()
        .providerId(ChatOrPushProviderEnum.ONESIGNAL)
            .integrationIdentifier("string")
        .credentials(ChannelCredentials.builder()
            .deviceTokens(List.of("token1", "token2", "token3"))
            .build())
        .build())
    .call();

curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
  "providerId": "one-signal",
  "credentials": {
    "deviceTokens": [
      "token1",
      "token2",
      "token3"
    ]
  },
  "integrationIdentifier": "string"
}'

Step 2: Send a notification

import { Novu } from '@novu/api';

const novu = new Novu({ secretKey: "<NOVU_SECRET_KEY>" });

await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: "SUBSCRIBER_ID", },
  payload: {},
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "SUBSCRIBER_ID"},
        payload={},
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "SUBSCRIBER_ID",
    }),
    Payload: map[string]any{},
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()->setSecurity('<NOVU_SECRET_KEY>')->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'SUBSCRIBER_ID'),
        payload: {},
    ),
);

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() { SubscriberId = "SUBSCRIBER_ID" }),
    Payload = {},
});

import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder().subscriberId("SUBSCRIBER_ID").build()))
        .payload({})
        .build())
    .call();

curl --location 'https://api.novu.co/v1/events/trigger' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": [
        "SUBSCRIBER_ID"
    ],
    "payload": {}
}'

Using overrides to customize notifications

import { Novu } from '@novu/api';

const novu = new Novu({ secretKey: "<NOVU_SECRET_KEY>" });

await novu.trigger({
  workflowId: "workflowId",
  to: { subscriberId: "subscriberId", },
  payload: {
    "abc": "def"
},
  overrides: {
    "subtitle": "This is subtitle value",
    "mutableContent": "Mutable content value",
    "channelId": "category_id",
    "categoryId": "Category id",
    "icon": "https://image.com/icon.png",
    "sound": "sound file url"
},
});

import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="workflowId",
        to={"subscriber_id": "subscriberId"},
        payload={
        "abc": "def"
},
        overrides={
        "subtitle": "This is subtitle value",
        "mutableContent": "Mutable content value",
        "channelId": "category_id",
        "categoryId": "Category id",
        "icon": "https://image.com/icon.png",
        "sound": "sound file url"
},
    ))

import (
    "context"
    "os"

    novugo "github.com/novuhq/novu-go"
    "github.com/novuhq/novu-go/models/components"
)

s := novugo.New(novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")))

res, err := s.Trigger(context.Background(), components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
    }),
    Payload: map[string]any{
    "abc": "def"
},
    Overrides: map[string]any{
    "subtitle": "This is subtitle value",
    "mutableContent": "Mutable content value",
    "channelId": "category_id",
    "categoryId": "Category id",
    "icon": "https://image.com/icon.png",
    "sound": "sound file url"
},
}, nil)

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()->setSecurity('<NOVU_SECRET_KEY>')->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId'),
        payload: {
        "abc": "def"
},
        overrides: {
        "subtitle": "This is subtitle value",
        "mutableContent": "Mutable content value",
        "channelId": "category_id",
        "categoryId": "Category id",
        "icon": "https://image.com/icon.png",
        "sound": "sound file url"
},
    ),
);

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "<NOVU_SECRET_KEY>");

await sdk.TriggerAsync(triggerEventRequestDto: new TriggerEventRequestDto() {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto() { SubscriberId = "subscriberId" }),
    Payload = {
    "abc": "def"
},
    Overrides = {
    "subtitle": "This is subtitle value",
    "mutableContent": "Mutable content value",
    "channelId": "category_id",
    "categoryId": "Category id",
    "icon": "https://image.com/icon.png",
    "sound": "sound file url"
},
});

import co.novu.Novu;
import co.novu.models.components.*;

Novu novu = Novu.builder().secretKey("<NOVU_SECRET_KEY>").build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("workflowId")
        .to(To2.of(SubscriberPayloadDto.builder().subscriberId("subscriberId").build()))
        .payload({
        "abc": "def"
})
        .overrides({
        "subtitle": "This is subtitle value",
        "mutableContent": "Mutable content value",
        "channelId": "category_id",
        "categoryId": "Category id",
        "icon": "https://image.com/icon.png",
        "sound": "sound file url"
})
        .build())
    .call();

curl --location 'https://api.novu.co/v1/events/trigger' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
    "name": "workflowId",
    "to": [
        "subscriberId"
    ],
    "payload": {
        "abc": "def"
    },
    "overrides": {
        "subtitle": "This is subtitle value",
        "mutableContent": "Mutable content value",
        "channelId": "category_id",
        "categoryId": "Category id",
        "icon": "https://image.com/icon.png",
        "sound": "sound file url"
    }
}'

Using external user ID

By default, Novu uses player_id to send notifications, but you can select the External ID option in the OneSignal integration settings in Novu. If External ID option is selected, then deviceTokens stored in subscriber credentials for the OneSignal provider, are used as external user IDs. By default, Novu uses player IDs to send notifications. If your OneSignal integration uses external user IDs, then you can switch this behavior in the OneSignal integration settings in Novu.

Once enabled, the deviceTokens stored in subscriber credentials are treated as external user IDs instead of player IDs.

​Configure Onesignal with Novu

​Step 1: Get your OneSignal credentials

​Step 2: Connect Onesignal to Novu

​Using Onesignal with Novu

​Step 1: Add subscriber device token

​Step 2: Send a notification

​Using overrides to customize notifications

​Using external user ID