Skip to main content
OneSignal offers two ways to get started quickly with in-app messages: quickstart designs built into the dashboard, and copy/paste HTML templates for the HTML editor.
All templates and quickstarts run inside an in-app message webview. To close messages, open URLs, tag users, and capture clicks, use the In-App Message JS API.

Prerequisites

Before you start, we recommend you review:
Do not put secrets (API keys, tokens) in template code. Treat all in-app message input as untrusted and validate it in your app or backend.

Quickstart designs

OneSignal now includes a library of ready-to-use quickstart designs directly in the dashboard. These cover common use cases like push permission prompts, onboarding flows, and feature announcements — available in both the Block Editor and HTML Editor. To access the quickstart library:
  1. In OneSignal, go to Messages > In-App > New In-App.
  2. Under Start from a pre-built design, select the OneSignal quickstart designs tab.
  3. Choose a design, then customize it to match your brand.

Tested devices

These quickstart designs have been tested on:
  • iPhone 13+ (iOS)
  • Pixel 8+ (Android)
Quickstart designs are not optimized for landscape mode and may not render correctly when a device is rotated. We recommend restricting your app to portrait-only orientation to ensure a consistent experience.

HTML editor templates

Our HTML Editor lets you fully control your in-app message layout and behavior using HTML, CSS, and JavaScript. Use the copy/paste templates below to get started faster.

How to use the templates

  1. In OneSignal, go to Messages > In-App > New In-App.
  2. Select the HTML editor.
  3. Find a template below.
  4. Copy the full HTML from the code block and paste it into the editor.
  5. Update the placeholders (URLs, endpoints, dates, and copy).
  6. Test on a real device, then publish.

Available templates

email-form

Collect Email Form

Ask for the user’s email and send it to your app via click name.
sms-form

Collect Phone Numbers Form

Ask for and get consent to send SMS. Includes phone number in E.164 format and send it to your app via click name.
checklist-survey

Checklist Survey

Multi-select survey you can send to your backend or convert to tags.
count_down

Countdown

Countdown timer for time-sensitive promotions.
promo-wheel

Promo Wheel

Spin-to-win promo experience (customize promo handling).
quiz_modal

Quiz Modal

Quiz experience that can tag users with their score.
ranking-survey

Ranking Survey

1–5 rating survey (send to your endpoint or tag user).
ui-ui

Audio/Video Player

Simple audio preview UI for a direct MP3 file.
vertical-swiping

Vertical Swiping

Multi-slide vertical swipe onboarding or feature tour.

Email form

Gather Email Subscriptions through an in-app message. How this form works:
  1. The user enters an email address and checks a consent box.
  2. On submit, OneSignal’s Create User API is called to create the email Subscription in your app.
  3. Also, the template calls OneSignalIamApi.addClickName(e, email) which passes the email address to our SDK’s In-app Message Click Listener.
  4. Within your app, you can add the In-App Message Click Listener to read the click name and pass the email into our SDK’s addEmail method.
You may notice that steps 2 and 4 both involve creating the email Subscription.
  • Step 2 doesn’t require adding code directly into the app while but also, doesn’t add the email Subscription to the user if you called the login method.
  • Step 4 requires additional code (the In-App Message Click Listener) but also adds the email Subscription to the user if you called the login method.
**Replace YOUR_APP_ID with your OneSignal App ID found in Settings > Keys & IDs.
Required for step 4:
  1. Keep the addClickName call in your HTML submit handler.
  2. Read the input with our SDK’s In-app Message Click Listener
  3. When the click name looks like an email, call the addEmail method within the in-app message click listener.
Example using the in-app message click listener and addEmail method:

SMS form

Gather SMS Subscriptions through an in-app message. How this form works:
  1. The user selects their country code, enters a 10-digit number, and checks a consent box.
  2. On submit, OneSignal’s Create User API is called to create the SMS Subscription in your app.
  3. Also, the template calls OneSignalIamApi.addClickName(e, e164Phone) which passes the phone number to our SDK’s In-app Message Click Listener.
  4. Within your app, you can add the In-App Message Click Listener to read the click name and pass the phone number into our SDK’s addSms method.
You may notice that steps 2 and 4 both involve creating the SMS Subscription.
  • Step 2 doesn’t require adding code directly into the app but also, doesn’t add the SMS Subscription to the user if you called the login method.
  • Step 4 requires additional code (the In-App Message Click Listener) but also adds the SMS Subscription to the user if you called the login method.
**Replace YOUR_APP_ID with your OneSignal App ID found in Settings > Keys & IDs.
Required for step 4:
  1. Keep the addClickName call in your HTML submit handler.
  2. Read the input with our SDK’s In-app Message Click Listener
  3. When the click name is an E.164 number, call the addSms method within the in-app message click listener.
Example using the in-app message click listener and addSms method:

Checklist survey

Multi-select survey that posts results to your backend.
  • Set your endpoint in handleSurveyAnswer().
  • Update checkbox name values and labels to match your question.
If you leave var url = "", the request will fail. Set a real endpoint or replace fetch() with tagging (example below).
Optional: tag users instead of calling your backend Replace the handleSurveyAnswer(answers) call in the submit handler with:

Countdown

Create urgency with a countdown timer for limited-time offers and promotions. Customize the end date and redirect URL to match your campaign.
  • Update endtime to a future date/time.
  • Update openUrl destination URL.
The sample endtime in this template is in the past (Mar 25, 2025). If you don’t update it, users will immediately hit the “ended” logic.

Promo wheel

Spin-to-win promotion with a random outcome.
  • Replace hardcoded promo codes with server-generated or validated codes.
  • Add your “Shop Now” URL or action.
Client-side randomness and hardcoded codes are easy to abuse. If a promo has value, generate/validate it server-side.

Quiz modal

Interactive quiz that tracks score.
  • Update the questions array with real content.
  • Decide when to tag users:
    • current behavior tags on close
    • you can tag immediately when the quiz ends

Ranking survey

1–5 rating survey.
  • Set your url in handleSurveyAnswer().
  • Update question text and labels.

Audio/video player

Audio preview UI. For video details, see the HTML Design guide for embedding videos.
  • Replace the <audio> src with a direct MP3 URL.
  • Update the CTA openUrl destination URL.
Do not use a streaming page URL in <audio>. The <audio> element requires a direct audio file URL (like .mp3).

Vertical swiping

Multi-slide vertical onboarding or feature tour. Why this template works well on mobile:
  • Uses a hidden OneSignal-labeled close button for reliable dismissal.
  • Places the visible close button in the safe area and uses a large tap target.
  • Disables swipe when interacting with buttons/inputs.