Quickstart guide

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through four stages to get you up and running with OneSignal. Complete them in order or jump to the section you need. If you haven’t already, create your account to get started.

1. Set up your account and messaging channels — create your app and configure at least one channel.
2. Add and organize your Users — model Users, Subscriptions, tags, and segments.
3. Send messages — compose campaigns, personalize content, and build automated Journeys.
4. Measure impact with analytics — track delivery, engagement, and conversions.

Prefer video? Watch the walkthrough below.

​

Which channel should I start with?

Pick the channel that matches your immediate goal — you can add more to the same OneSignal App at any time.

​

Set up your account and messaging channels

Your OneSignal App is where User and message data is stored. You can have multiple Apps in a single Organization for different projects, environments, or billing needs.

​

OneSignal account

​

Messaging channels

OneSignal supports push notifications, in-app messages, email, SMS/MMS/RCS, and Live Activities. Choose your first channel and follow its setup guide — you can add more channels to the same app at any time.

​

Add and organize your Users

As users interact with your app, OneSignal assigns each a OneSignal ID (the internal User ID) and Subscription IDs for each device, email address, or phone number. A single User can have multiple Subscriptions across channels. Users stay anonymous until you identify them with an External ID — a stable identifier from your system (typically your internal user ID) that lets OneSignal merge a User across devices, app reinstalls, and channels.

​

User properties

Store User data as tags (key-value pairs) and custom events (user actions). Tags power message personalization and segmentation. Common tag examples:

• Attributes: first_name, city, subscription_tier
• Behaviors: cart_abandoned, last_login_date, onboarding_complete
• Preferences: notification_frequency, theme_preference

​

Segments and integrations

Segments are dynamic groups of Users defined by tags, behavior data, or message interactions. They update automatically as User data changes — for example, “Last session greater than a week” or “Added item to cart.” Connect external platforms to enrich your segments with additional User data.

​

Send messages

Design and send single-message campaigns or automated multi-step Journeys from the OneSignal dashboard. Each channel has its own composer with preview, targeting, and scheduling options.

​

Personalize your messages

Use tags, custom events, and dynamic data to tailor message content for each recipient. OneSignal uses Liquid syntax to inject tag values, custom event properties, and Data Feed content into message bodies and email subject lines (e.g., Hi {{ first_name | default: 'there' }}). Create reusable templates to maintain consistency across campaigns.

​

Journeys

Journeys are automated, multi-step campaigns that respond to User behavior — such as onboarding sequences, abandoned cart reminders, and re-engagement flows.

​

Send via API

Send messages programmatically for transactional use cases like order confirmations, OTPs, and billing alerts.

​

Measure impact with analytics

Track message performance — including delivery, opens, clicks, and conversions — to understand what drives engagement and refine your strategy.

​

Next steps

Once you’ve sent your first message, deepen your setup with these guides.

​

FAQ

​

Do I need a developer to get started?

Not necessarily. Email and SMS channels can be configured without code. Push notifications and in-app messages require SDK integration, which may need a developer or AI assistant. You can invite team members with different roles at any time.

​

Can I add more messaging channels later?

Yes. Add any combination of channels to the same OneSignal App. Each channel has its own setup guide — return to the messaging channels section to add a new one.

​

What is the difference between a User and a Subscription?

A User represents one person, identified by an External ID. A Subscription is a specific channel endpoint — such as a device, email address, or phone number. One User can have multiple Subscriptions across different channels and devices.

​

How long does initial setup take?

Email setup typically takes under 30 minutes if you have access to your domain DNS settings. SMS requires carrier registration, which can take a few days. Push notification setup depends on your app’s platform and build process — plan for a few hours of developer time.

​

Where do I find my API key and App ID?

In the OneSignal dashboard, go to Settings → Keys & IDs. Each app has its own App ID and REST API Key — never expose the REST API Key in client-side code. See Keys and IDs for the full breakdown of which key to use where.

​

How do I test my setup before sending to real users?

Configure Test Users — devices, email addresses, or phone numbers flagged as internal — then use the Send to Test Users option in any composer. Test sends bypass segments and exclusions so you can preview rendering, deep links, and personalization on your own devices first.

​

Can I migrate from another messaging platform?

Yes. The fastest path is to (1) install the OneSignal SDK alongside your existing provider, (2) call the External ID and Tag setters with the user IDs and attributes from your current system so identities map cleanly, and (3) once Subscriptions are flowing in, sunset the old provider. For email and SMS lists, you can also import historical Subscriptions via CSV — see Users and Subscriptions for the import patterns.