# OneSignal

OneSignal is a customer engagement platform for push notifications, email, SMS, and in-app messaging. The Sling OneSignal connector extracts data from the OneSignal REST API, supporting apps, segments, templates, messages/notifications, and devices.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `app_api_key` **(required)** -> Your OneSignal App API Key
* `org_api_key` **(required for `apps` endpoint)** -> Your OneSignal Organization API Key

**Inputs:**

* `app_id` **(required)** -> Your OneSignal App ID
* `anchor_date` (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DDTHH:MM:SSZ`

### Getting Your API Keys

1. Log in to your OneSignal dashboard at [dashboard.onesignal.com](https://dashboard.onesignal.com)
2. **App API Key**: Go to **Settings** > **Keys & IDs** to find your App API Key and App ID
3. **Organization API Key**: Go to **Organization** > **API Keys** and create a new key

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set ONESIGNAL type=api spec=onesignal \
  secrets='{ app_api_key: your_app_api_key, org_api_key: your_org_api_key }' \
  inputs='{ app_id: your_app_id }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export ONESIGNAL='{ type: api, spec: onesignal, secrets: { app_api_key: "your_app_api_key", org_api_key: "your_org_api_key" }, inputs: { app_id: "your_app_id" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  ONESIGNAL:
    type: api
    spec: onesignal
    secrets:
      app_api_key: "your_app_api_key"
      org_api_key: "your_org_api_key"
    inputs:
      app_id: "your_app_id"
```

**With anchor date for historical data:**

```yaml
connections:
  ONESIGNAL:
    type: api
    spec: onesignal
    secrets:
      app_api_key: "your_app_api_key"
      org_api_key: "your_org_api_key"
    inputs:
      app_id: "your_app_id"
      anchor_date: "2024-01-01T00:00:00Z"
```

## Replication

Here's an example replication configuration to sync OneSignal data to a PostgreSQL database:

```yaml
source: ONESIGNAL
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: onesignal.{stream_name}

streams:
  # Organization data
  apps:

  # App-level reference data
  segments:
  templates:

  # Incremental event data
  messages:
    mode: incremental

  # Device/player data (deprecated API)
  devices:
```

**Sync all endpoints:**

```yaml
source: ONESIGNAL
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: onesignal.{stream_name}

streams:
  '*':
```

## Endpoints

| Endpoint    | Description                                           | Incremental |
| ----------- | ----------------------------------------------------- | ----------- |
| `apps`      | All apps in the organization (requires `org_api_key`) | No          |
| `segments`  | All segments for the app                              | No          |
| `templates` | All message templates for the app                     | No          |
| `messages`  | Sent messages/notifications, filtered by time offset  | Yes         |
| `devices`   | Player/device records (deprecated API)                | No          |

To discover available endpoints:

```bash
sling conns discover ONESIGNAL
```

## Rate Limiting

The OneSignal API has a rate limit of 1 request per second for view endpoints. The connector automatically:

* Uses conservative rate limiting (1 request/second)
* Limits concurrency to 1 parallel request
* Retries with exponential backoff on 429 (rate limit) responses
* Retries on 5xx server errors

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).