OneSignal API Essential Guide

What type of API does OneSignal provide?

OneSignal provides a RESTful API based on the REST architecture.

API Type

OneSignal uses a REST API.

Key Features

• Uses HTTPS connections with TLS 1.2 or higher on port 443
• Requires an App ID and REST API Key for authentication
• Supports operations like creating/updating apps, sending notifications, managing devices, etc.

Authentication

• Uses Basic authentication scheme
• Requires an App ID and REST API Key
• The App ID can be found in the Dashboard URL or Settings page
• The REST API Key is located in Dashboard > Settings > Keys & IDs

Request Format

• Requests are made using standard HTTP methods (GET, POST, PUT, DELETE)
• Request and response bodies use JSON format

Best Practices

• Use HTTPS for all API calls
• Include proper authentication headers
• Handle rate limiting and errors appropriately
• Cache responses when possible to reduce API calls

Does the OneSignal API have webhooks?

Yes, the official OneSignal API does have webhooks. Here are the key points about OneSignal's webhook capabilities:

Event Webhooks

OneSignal offers Event Webhooks that allow you to stream data out of OneSignal to your chosen destination in real-time. This feature enables you to:

• Connect OneSignal to other products within your marketing ecosystem
• Trigger corresponding messaging
• Maintain records
• And more

Types of Events

You can subscribe to various types of events through OneSignal's webhooks. While the search results don't provide an exhaustive list, they mention that you can select multiple events to trigger a webhook. These events can be related to different channels (e.g., push notifications, email, SMS) and can be sent through the same webhook or configured separately for more granular control.

Configuration

To set up a webhook in OneSignal:

1. Go to Settings → Webhook in your OneSignal application.
2. Select "Trigger when any of the following events occur".
3. Click "Select Events" and choose the events you want to trigger the webhook.
4. Configure the HTTP method, URL, and headers for the webhook.

Personalization

OneSignal allows you to personalize all fields in your webhook using information about the user and the message that triggered it. This provides flexibility for various use cases.

Retries and Disabling

OneSignal has a retry mechanism for failed webhook requests and will disable webhooks if there's a high failure rate (300 failures in 5 minutes).

Journey Webhooks

For more advanced use cases, OneSignal offers Journey Webhooks (available for annual plans) that allow you to add custom webhook steps to your customer journeys. These webhooks offer more configuration options and can be personalized based on user information.

Best Practices

1. Test your webhooks using tools like webhook.site before pointing them to your actual endpoints.
2. Monitor webhook performance and troubleshoot any issues promptly.
3. Use personalization to make your webhooks more dynamic and useful.

In summary, OneSignal's webhook support provides a powerful way to integrate your messaging workflows with other systems and automate actions based on various events in your customer engagement process.

Rate Limits and other limitations

Here are the key points about the API Rate Limits for the OneSignal API:

API Rate Limits

1. Create notification endpoint:

   • Free Plans: 150 requests per second per app
   • Paid Plans: 6,000 requests per second per app

2. Updating Users/Subscriptions and Delete Users endpoints:

   • 1000 requests per second per app
   • 1 request per second per user or subscription
   • Up to 100 modifications per request

3. View notifications, templates, users, and individual notifications:

   • 1 request per second per app
   • 10 requests per second look back

4. Notification History:

   • Keep number of parallel requests under 100 GB/file

Application Rate Limits

• In 15 minutes, you may not send more messages than 10x your total subscribed user count.
• This limit is designed to protect customers from accidentally messaging all users in a loop.
• Exceeding this limit may result in your app being disabled temporarily.

Handling Rate Limit Errors

• If you exceed an API rate limit, you'll receive an HTTP 429 response with an error message.
• The response will include a 'RetryAfter' header indicating how many seconds to wait before retrying.

Best Practices

• When possible, batch multiple pushes/updates in a single request to reduce the total number of requests sent.
• For apps with exactly 1000 subscribed users, you can send up to 9,999 notifications within a 15-minute period.

Additional Notes

• The 15-minute window for application rate limits is static and does not roll over from minute to minute.
• Apps are not disabled if API limits are reached; they will be allowed to send again after some time passes.

It's important to note that these rate limits are designed as safety measures and should not affect normal usage of the OneSignal platform.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the OneSignal API:

Latest SDK Versions

• Android (Google) SDK: 5.1.6
• iOS SDK: 5.1.3
• Unity SDK: 5.1.1
• Flutter SDK: 5.1.2
• Android (Huawei) SDK: 4.8.8
• Cordova/Ionic SDK: 5.1.0
• React Native/Expo SDK: 5.1.0
• .NET MAUI SDK: 5.1.1

Key Points

• The search results do not provide a specific version number for the OneSignal API itself. Instead, they focus on the SDK versions for different platforms.

• The most recent updates appear to be for the Android and iOS SDKs, with Android at 5.1.6 and iOS at 5.1.3.

• These recent updates include bug fixes, performance improvements, and new features across various platforms.

• Some of the recent changes include:

  • New methods for getting user IDs and subscription information
  • Improvements to in-app messaging
  • Bug fixes for crashes and null pointer exceptions
  • Updates to dependencies like Firebase messaging

• There have been some API changes, such as the Push Subscription observer now passing nullable properties.

Best Practices

• It is recommended to update to the latest SDK versions listed or higher if available.

• When implementing the OneSignal SDK, be sure to check the specific documentation for your platform, as there may be platform-specific changes or features.

• Keep an eye on deprecated methods and update your code accordingly to use the new recommended methods.

• When using the Push Subscription API, account for the possibility of null values for token and ID properties.

How to get a OneSignal developer account and API Keys?

To get a developer account for OneSignal and create an API integration, follow these steps:

1. Sign up for a OneSignal account

Visit the OneSignal website (https://onesignal.com) and sign up for an account using your email address.

2. Create a OneSignal App

After signing up, you'll be able to create a OneSignal App. This App will house relevant messaging data for your mobile and web applications, such as user data, message data, and custom application configurations.

3. Generate API keys

Once you've created an App, you'll need to generate API keys to use for authentication when making API requests. Here's how to do it:

• Go to the OneSignal dashboard
• Select your App from the All Apps page
• Navigate to Settings
• Look for the "Keys & IDs" section

You'll find two important keys here:

• REST API Key: Used for server-side API requests
• App ID: Identifies your OneSignal App

4. Set up your development environment

Depending on your preferred programming language, you may want to use one of OneSignal's client SDKs. They offer SDKs for various languages including Go, Java, .NET, Node, PHP, Python, Ruby, and Rust.

5. Make API requests

With your API keys and development environment set up, you can now start making API requests. Here's a basic example using Node.js:

const https = require('https');

const options = {
  hostname: 'onesignal.com',
  path: '/api/v1/notifications',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic YOUR_REST_API_KEY'
  }
};

const data = JSON.stringify({
  app_id: 'YOUR_APP_ID',
  contents: {'en': 'Your notification message'},
  included_segments: ['All']
});

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (e) => {
  console.error(e);
});

req.write(data);
req.end();

Remember to replace 'YOUR_REST_API_KEY' and 'YOUR_APP_ID' with your actual REST API Key and App ID.

What can you do with the OneSignal API?

Based on the search results provided, here is a list of data models that can be interacted with using the OneSignal API, along with what is possible for each:

Users

• Create, update, and retrieve user data
• Properties that can be managed include:
  • OneSignal ID (UUID assigned by OneSignal)
  • External ID (for identified users)
  • Data Tags (custom event or user data)
  • Language
  • Timezone ID
  • Location
  • Country
  • First Session
  • Amount Spent
  • Purchases

Subscriptions

• Manage user subscriptions across different channels (push, email, SMS)

Aliases

• Create and manage aliases for users

Tags

• Set, update, and retrieve data tags for users
• Import user attributes or data tags in bulk
• Use time operators with tags
• Track user events and attributes

Messages

• Create and send push notifications, emails, SMS, and in-app messages
• Retrieve message reports and analytics

Analytics

• Access delivery reports for different message types (push, email, SMS, in-app)
• Retrieve notification click-through rates (CTR)
• Access outcome data
• Integrate with third-party analytics tools (e.g., Google Analytics, Adobe Analytics)

A/B Testing

• Create and manage A/B tests for push notifications and emails

Integrations

• Set up and manage integrations with third-party platforms and services

Webhooks

• Configure and manage event webhooks

Apps and Organizations

• Manage apps and organizations within OneSignal

Account Management

• Manage team members, billing, and account security settings

Data Export

• Export user data, message data, and outcomes data

This list covers the main data models that can be interacted with using the OneSignal API. Each model offers various possibilities for creating, updating, retrieving, and managing data related to user engagement and messaging across multiple channels.