OneSignal query tutorial

Learn how to send notifications and manage devices in OneSignal using Retool queries.

After setting up a OneSignal integration with Retool, your OneSignal resource is available to use in the query editor. Retool generates the query editor directly from OneSignal's API specification, so you select an operation and Retool renders the relevant parameters and request body fields.

Create a query

Classic app

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

To create a OneSignal query in a Retool app:

1. In the Retool app IDE, open the Code tab, then click + in the page or global scope.
2. Select Resource query.
3. Choose your OneSignal resource.
4. Select an operation and configure its parameters or request body.

Workflow or agent

Workflows and agent custom tools use the same Resource query block to query OneSignal.

1. Add a Resource query block to your workflow or custom tool's function canvas.
2. Choose your OneSignal resource.
3. Select an operation and configure its parameters or request body.

Custom tools use the same block-based canvas as workflows, so the steps are identical in either context.

Query configuration fields

Retool surfaces OneSignal's API operations directly from its API specification. For the full list of available operations and their parameters, refer to the OneSignal API reference. The fields below are the Retool-specific controls you configure for any operation.

Operation

A searchable dropdown listing every available OneSignal API operation, such as Create notification, View notifications, Add a device, or Create Segments. Selecting an operation determines which parameter and request body fields Retool renders below it.

Examples

Create notification
View notification
Add a device
View devices

Parameters

Path and query parameters required by the selected operation. For example, View notifications requires an app_id query parameter, and accepts optional limit and offset parameters for pagination.

Example

app_id: {{ oneSignalAppId.value }}
limit: 50
offset: 0

Request body

For operations that create or update data (such as Create notification or Add a device), Retool renders a JSON request body editor with fields inferred from OneSignal's schema for that operation.

Example: Create notification request body

{
  "app_id": {{ oneSignalAppId.value }},
  "contents": { "en": {{ messageInput.value }} },
  "headings": { "en": {{ titleInput.value }} },
  "isIos": true,
  "isAndroid": true
}

Common use cases

The following examples demonstrate typical OneSignal operations in Retool apps. For a complete reference of available operations and parameters, refer to the OneSignal API reference.

send a push notification

First, create a query named sendNotificationQuery using the Create notification operation.

Field	Value
Operation	Create notification
Request body	See below

Example request body

{
  "app_id": {{ oneSignalAppId.value }},
  "contents": { "en": {{ messageInput.value }} },
  "headings": { "en": {{ titleInput.value }} },
  "isIos": true,
  "isAndroid": true
}

Next, add a Button component and add an event handler to its Click event that runs sendNotificationQuery.

view notification delivery history

First, create a query named getNotificationQuery using the View notification operation.

Field	Value
Operation	View notification
Parameters	See below

Example parameters

app_id: {{ oneSignalAppId.value }}
notification_id: {{ table1.selectedRow.data.id }}

Next, add a Table component and set its Data property to {{ getNotificationQuery.data }} to display delivery counts and status.

register a device

First, add a Form component with input fields for device information.

Next, create a query named addDeviceQuery using the Add a device operation.

Example request body

{
  "app_id": {{ oneSignalAppId.value }},
  "device_type": 1,
  "identifier": {{ form1.data.pushToken }},
  "external_user_id": {{ form1.data.userId }},
  "tags": { "plan": {{ form1.data.plan }} }
}

Then, add an event handler to the form's Submit event that runs addDeviceQuery and displays a success notification.

view and filter devices

First, create a query named getDevicesQuery using the View devices operation.

Example parameters

app_id: {{ oneSignalAppId.value }}
limit: 300
offset: 0

Next, add a Table component and set its Data property to {{ getDevicesQuery.data.players }} to display registered devices.

stop a scheduled notification

First, add a Button component in a table's action column.

Next, create a query named cancelNotificationQuery using the Stop a scheduled or currently outgoing notification operation.

Example parameters

app_id: {{ oneSignalAppId.value }}
notification_id: {{ table1.selectedRow.data.id }}

Then, add an event handler to the button's Click event:

1. Action: Show confirmation modal.
2. If confirmed, trigger cancelNotificationQuery.
3. Then refresh the notifications data query.

Best practices

Follow these best practices to keep OneSignal queries fast, efficient, and safe.

Performance

• Cache responses: For data that doesn't change frequently, such as app configuration, enable query caching to reduce API calls and improve response times.
• Use pagination: Use the limit and offset parameters on list operations like View notifications and View devices to reduce payload size.
• Minimize payload size: Request only the fields you need, and avoid running View devices without a limit on OneSignal apps with large user bases.
• Set appropriate timeouts: Configure query timeouts based on expected API response times to prevent hung requests.

Data integrity

• Validate user input: Sanitize and validate all user input before including it in notification content or device tags to prevent injection attacks.
• Handle errors gracefully: Configure error notifications and fallback behavior for failed queries to improve user experience.
• Verify responses: Check response status codes and validate response data structure before using it in your app.
• Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.
• Log query activity: Enable query logging to track notification sends and device changes for debugging and auditing.

Troubleshoot authentication errors

If a query returns a 403 or authentication error, verify which key the operation requires.

• REST API key missing or invalid: Most operations, including sending notifications and managing devices, require a valid REST API key configured on the resource.
• User Auth key missing or invalid: Operations under /apps/, such as creating or updating a OneSignal app, require the User Auth key instead of the REST API key.
• Wrong app_id: Confirm the app_id parameter matches the OneSignal app associated with your REST API key.