> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/onesignal.md).

# OneSignal

OneSignal customer engagement platform. Send push, email, and SMS messages, manage users, subscriptions, and tags, and view delivery outcomes.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector           | Authentication |
| ------------------- | -------------- |
| OneSignal (API Key) | REST API Key   |

#### OneSignal (API Key)

Connect to OneSignal with an app-level REST API Key and App ID to send push, email, and SMS messages and manage users and subscriptions.

**Set up in OneSignal**

1. Prepare the OneSignal account or service that the workflow will access. Grant access to the required resources and operations.
2. **REST API Key:** App-scoped REST API Key from OneSignal Settings > Keys & IDs. Do not use an Organization API Key.
3. **App ID:** Your OneSignal App ID (UUID) from Settings > Keys & IDs.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **OneSignal (API Key)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                               |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| REST API Key  | Yes      | App-scoped REST API Key from OneSignal Settings > Keys & IDs. Do not use an Organization API Key. [Provider instructions](https://dashboard.onesignal.com). |
| App ID        | Yes      | Your OneSignal App ID (UUID) from Settings > Keys & IDs.                                                                                                    |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **OneSignal** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Message

Send a push, email, or SMS message to segments, users, or direct recipients.

**Inputs**

| Field             | Type                      | Required | Description                                                                         |
| ----------------- | ------------------------- | -------- | ----------------------------------------------------------------------------------- |
| Channel           | select (string)           | Yes      | Delivery channel: push, email, or SMS. Available values: Push, Email, SMS.          |
| Included Segments | multiple\_select (string) | No       | Segment names to send to. Options load from the selected connection.                |
| Excluded Segments | multiple\_select (string) | No       | Segment names to exclude. Options load from the selected connection.                |
| External IDs      | array                     | No       | Target specific users by external ID.                                               |
| Subscription IDs  | array                     | No       | Target specific subscription IDs.                                                   |
| Email Recipients  | array                     | No       | Email addresses to send to directly.                                                |
| Phone Numbers     | array                     | No       | E.164 phone numbers to send to directly.                                            |
| Title             | string                    | No       | Push notification title.                                                            |
| Message           | string                    | No       | Message body (push/SMS).                                                            |
| Subtitle          | string                    | No       | Push subtitle (iOS).                                                                |
| Launch URL        | string                    | No       | URL to open when the push is tapped.                                                |
| Big Picture URL   | string                    | No       | Large image URL for the push.                                                       |
| Custom Data       | object                    | No       | Custom key/value data delivered with the push.                                      |
| Email Subject     | string                    | No       | Email subject line.                                                                 |
| Email Body (HTML) | textarea                  | No       | HTML body of the email.                                                             |
| From Name         | string                    | No       | Sender display name.                                                                |
| From Address      | string                    | No       | Sender email address.                                                               |
| Reply-To Address  | string                    | No       | Reply-to email address.                                                             |
| Preheader         | string                    | No       | Preheader/preview text.                                                             |
| SMS From          | string                    | No       | Sender number or Messaging Service ID.                                              |
| MMS Media URLs    | array                     | No       | Media URLs to attach (MMS).                                                         |
| Template          | select (string)           | No       | Template to use for the message content. Options load from the selected connection. |
| Internal Name     | string                    | No       | Internal message name (not shown to recipients).                                    |
| Send After        | datetime                  | No       | Schedule delivery for this time.                                                    |

**Outputs**

| Field       | Type   | Description                                         |
| ----------- | ------ | --------------------------------------------------- |
| Message ID  | string | The created message ID.                             |
| Recipients  | number | Number of recipients targeted.                      |
| External ID | string | Idempotency external\_id, if one was assigned.      |
| Message URL | string | Dashboard link to the message.                      |
| Raw Result  | dict   | Full create-message response, including any errors. |

#### List Messages

List sent messages with delivery stats, paginated up to a cap.

**Inputs**

| Field       | Type            | Required | Description                                                                         |
| ----------- | --------------- | -------- | ----------------------------------------------------------------------------------- |
| Created Via | select (string) | No       | Filter by how the message was created. Available values: Dashboard, API, Automated. |
| Limit       | integer         | No       | Maximum messages to return (up to 200). Minimum: 1. Maximum: 200. Default: 50.      |

**Outputs**

| Field       | Type        | Description                                          |
| ----------- | ----------- | ---------------------------------------------------- |
| Messages    | dict\_array | Messages on this page.                               |
| Total Count | number      | Total messages available for the app.                |
| Has More    | boolean     | Whether more messages exist beyond the returned set. |

#### Get Message

Get a message's delivery stats and (optionally) outcomes.

**Inputs**

| Field         | Type            | Required | Description                                                      |
| ------------- | --------------- | -------- | ---------------------------------------------------------------- |
| Message       | select (string) | Yes      | The message to fetch. Options load from the selected connection. |
| Outcome Names | array           | No       | Outcomes to include in the response.                             |

**Outputs**

| Field       | Type   | Description                                           |
| ----------- | ------ | ----------------------------------------------------- |
| Message ID  | string | The message ID.                                       |
| Message     | dict   | Full message object with delivery stats and outcomes. |
| Message URL | string | Dashboard link to the message.                        |
| Successful  | number | Number delivered successfully.                        |
| Failed      | number | Number that failed.                                   |
| Converted   | number | Number of clicks/conversions.                         |

#### Cancel Message

Cancel a scheduled message before it is delivered.

**Inputs**

| Field   | Type            | Required | Description                                                                 |
| ------- | --------------- | -------- | --------------------------------------------------------------------------- |
| Message | select (string) | Yes      | The scheduled message to cancel. Options load from the selected connection. |

**Outputs**

| Field      | Type    | Description                        |
| ---------- | ------- | ---------------------------------- |
| Success    | boolean | Whether the message was cancelled. |
| Message ID | string  | The cancelled message ID.          |

#### Create or Update User

Create or update a user, adding email/SMS subscriptions and tags.

**Inputs**

| Field        | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| External ID  | string | Yes      | Your unique identifier for the user. |
| Email        | string | No       | Email address to subscribe.          |
| Phone Number | string | No       | E.164 phone number to subscribe.     |
| Tags         | object | No       | Custom key/value tags for the user.  |
| Language     | string | No       | ISO 639-1 language code.             |
| Country      | string | No       | ISO 3166-1 alpha-2 country code.     |
| Timezone     | string | No       | tz database timezone identifier.     |

**Outputs**

| Field         | Type        | Description                   |
| ------------- | ----------- | ----------------------------- |
| OneSignal ID  | string      | OneSignal's internal user ID. |
| External ID   | string      | The user's external ID.       |
| Subscriptions | dict\_array | The user's subscriptions.     |
| User          | dict        | Full user object.             |

#### Get User

Fetch a user by external ID (or another alias).

**Inputs**

| Field       | Type            | Required | Description                                                                                                 |
| ----------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| Alias Type  | select (string) | No       | Which identifier the value refers to. Available values: external\_id, onesignal\_id. Default: external\_id. |
| Alias Value | string          | Yes      | The identifier value for the user.                                                                          |

**Outputs**

| Field        | Type   | Description                   |
| ------------ | ------ | ----------------------------- |
| OneSignal ID | string | OneSignal's internal user ID. |
| External ID  | string | The user's external ID.       |
| User         | dict   | Full user object.             |

#### Edit User Tags

Set or remove tags on a user identified by external ID.

**Inputs**

| Field       | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| External ID | string | Yes      | External ID of the user whose tags to edit.             |
| Tags        | object | Yes      | Tags to set. Use an empty string value to remove a tag. |

**Outputs**

| Field       | Type    | Description                       |
| ----------- | ------- | --------------------------------- |
| Success     | boolean | Whether the tags were updated.    |
| External ID | string  | The user's external ID.           |
| Tags        | dict    | The user's tags after the update. |
| User        | dict    | Full updated user object.         |

#### Update Subscription

Update a subscription's token, enabled state, or status.

**Inputs**

| Field              | Type            | Required | Description                                                                                                                                                                                                |
| ------------------ | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Subscription ID    | string          | Yes      | The subscription to update.                                                                                                                                                                                |
| Type               | select (string) | Yes      | Subscription channel type. Available values: iOSPush, AndroidPush, HuaweiPush, FireOSPush, WindowsPush, macOSPush, ChromePush, ChromeExtensionPush, FirefoxPush, SafariPush, SafariLegacyPush, Email, SMS. |
| Token              | string          | Yes      | Push token, email address, or E.164 phone number.                                                                                                                                                          |
| Enabled            | boolean         | No       | Enable (true) or unsubscribe (false).                                                                                                                                                                      |
| Notification Types | integer         | No       | Subscription status code (1 = subscribed).                                                                                                                                                                 |

**Outputs**

| Field           | Type    | Description                      |
| --------------- | ------- | -------------------------------- |
| Success         | boolean | Whether the update was accepted. |
| Subscription ID | string  | The updated subscription ID.     |

#### View Outcomes

Fetch outcome metrics (clicks, conversions, custom outcomes) for the app.

**Inputs**

| Field         | Type            | Required | Description                                                                                       |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------- |
| Outcome Names | array           | Yes      | Outcome names to fetch.                                                                           |
| Time Range    | select (string) | No       | Aggregation window (defaults to 1h). Available values: 1h, 1d, 1mo.                               |
| Attribution   | select (string) | No       | Attribution model (defaults to total). Available values: direct, influenced, unattributed, total. |

**Outputs**

| Field    | Type        | Description                |
| -------- | ----------- | -------------------------- |
| Outcomes | dict\_array | Requested outcome metrics. |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/onesignal.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
