> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldvisagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OneSignal Push Integration with WorldVisa

> Connect OneSignal to WorldVisa to send push notifications to mobile and web through workflows. Store your OneSignal app ID and API key in the WorldVisa dashboard.

This guide walks you through the entire process of configuring and using [OneSignal](https://onesignal.com/) with WorldVisa, from getting your credentials to sending your first notification.

OneSignal supports sending messages via both [Apple Push Notification Service](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server) (APNs) and [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) (FCM).

## Configure Onesignal with WorldVisa

Before you can send push notifications via OneSignal from WorldVisa, 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](https://developer.apple.com/help/account/keys/create-a-private-key) to see how to access your OneSignal `App ID` and `App API key`.

### Step 2: Connect Onesignal to WorldVisa

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

**1. Log in to the WorldVisa dashboard**

Open the WorldVisa Dashboard.

**2. Open Integration Store**

On the WorldVisa dashboard, navigate to the **Integration Store**.

**3. Connect a provider**

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

**4. Select Push tab**

Open the **Push** tab in the Integration Store.

**5. Select OneSignal**

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

**6. Paste credentials**

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

![Onesignal Integration in WorldVisa](https://mintcdn.com/wv-enterprise/l3bkwl1N_3mOn9aW/images/developers/channels-and-providers/push/onesignal/onesignal-integration.png?fit=max\&auto=format\&n=l3bkwl1N_3mOn9aW\&q=85\&s=570c596b3f091ea29350bcda32ebc34f)

**7. Create the integration**

Review your credentials, then click **Create Integration** to save.

## Using Onesignal with WorldVisa

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](https://documentation.onesignal.com/docs/onboarding-with-onesignal#step-1-setup-onesignal-sdk) in your application, your users are automatically assigned a unique OneSignal [`player_id`](https://documentation.onesignal.com/docs/users#player-id). This ID is used to target the user for push notifications.

To target a OneSignal user from WorldVisa, you must register their `player_id` as the `deviceToken` for their WorldVisa subscriber profile.

You can do this by making an API call to update the subscriber's credentials.

```bash theme={null}
curl -L -X PUT "${WV_API_URL}/v1/subscribers/<SUBSCRIBER_ID>/credentials" \
-H 'Content-Type: application/json' \
-H "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
  "providerId": "one-signal",
  "credentials": {
    "deviceTokens": [
      "token1",
      "token2",
      "token3"
    ]
  },
  "integrationIdentifier": "string"
}'
```

### Step 2: Send a notification

```bash theme={null}
curl --location "${WV_API_URL}/v1/events/trigger" \
--header 'Content-Type: application/json' \
--header "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": [
        "SUBSCRIBER_ID"
    ],
    "payload": {}
}'
```

## Using overrides to customize notifications

To customize a single notification, send OneSignal fields under `overrides.providers['one-signal']` when you trigger the workflow. WorldVisa deep-merges that object into the [Create notification](https://documentation.onesignal.com/reference/create-notification) request body it builds from the Push step's Subject and Body, so the fields you send win over the generated ones.

The override is an unvalidated passthrough, so copy field names from OneSignal's API reference. WorldVisa snake-cases the keys before sending, so `androidChannelId` also arrives as `android_channel_id`.

> [!NOTE]
>
> WorldVisa only reads provider fields under `overrides.providers`. Keys at the root of `overrides` are ignored. `channelId`, `categoryId`, `icon`, and `sound` are not OneSignal fields, so they do nothing under `providers` either — use `android_channel_id`, `ios_category`, `large_icon`, and `ios_sound` / `android_sound` instead, and send `subtitle` as a language map such as `{ "en": "Order #12345" }`.

```bash theme={null}
curl --location "${WV_API_URL}/v1/events/trigger" \
--header 'Content-Type: application/json' \
--header "Authorization: ApiKey ${WV_API_KEY}" \
-d '{
    "name": "workflowId",
    "to": [
        "subscriberId"
    ],
    "payload": {
        "abc": "def"
    },
    "overrides": {
        "providers": {
            "one-signal": {
                "subtitle": { "en": "Order #12345" },
                "mutable_content": true,
                "android_channel_id": "orders",
                "ios_category": "ORDER_UPDATE",
                "large_icon": "https://example.com/icon.png",
                "ios_sound": "default",
                "android_sound": "default"
            }
        }
    }
}'
```

You can also save the same object on the Push step in the workflow editor as a [provider content override](https://docs.worldvisagroup.com/developers/integrations/push#provider-content-overrides), which keeps it versioned with the workflow instead of repeating it on every trigger. Both land on the same OneSignal blob. Trigger overrides take precedence over the saved object: objects merge key by key, and arrays replace.

## Using external user ID

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

By default, WorldVisa 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 WorldVisa.

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

## Activity tracking

OneSignal supports [push activity tracking](https://docs.worldvisagroup.com/developers/integrations/push/push-activity-tracking.md). Enable the **Push Activity Tracking** toggle on the OneSignal integration. Your app reads the WorldVisa message id from the notification and forwards it as `eventId`.

WorldVisa sends the trigger payload as OneSignal `data` and adds `__nvMessageId`. The OneSignal SDK exposes that object as `additionalData`. A `data` override is merged into it. Leave `__nvMessageId` in place.

```javascript theme={null}
OneSignal.Notifications.addEventListener("click", async (event) => {
  await fetch("https://your-api.com/api/notifications/events", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      eventType: "clicked",
      eventId: event.notification.additionalData?.__nvMessageId,
    }),
  });
});
```

Forward `delivered`, `opened`, `dismissed`, or `failed` the same way when your app observes those events. Your backend then calls [WorldVisa's activity endpoint](https://docs.worldvisagroup.com/developers/integrations/push/push-activity-tracking.md#step-3-forward-events-to-WorldVisa-from-your-backend).


## Related topics

- [Push Webhook Push Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/push/push-webhook.md)
- [APNS Push Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/push/apns.md)
- [Pushpad Push Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/push/pushpad.md)
- [Expo Push Push Integration with WorldVisa](https://docs.worldvisagroup.com/developers/integrations/push/expo-push.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.