Terminal
Terminal/Skill
Writes HTML for OneSignal mobile in app messages from a plain request, styled to your brand and wired for click tracking.
By OneSignal
Works with
npx skills add onesignal/onesignal-ai-skills --skill onesignal-iam-html-composerTurn a plain-language request into production-ready, mobile-safe, brand-aware HTML that can be applied directly to the OneSignal HTML IAM editor.
Every output must be anchored to a known IAM use case, a goal, and a CTA action that maps to a OneSignal IAM JavaScript API method. Do not generate unconstrained "anything" HTML.
Use this skill when the user asks to:
Treat "in-app", "popup", "modal", "splash", "permission prompt", "rating prompt", and "promo modal" as likely IAM requests unless the user clearly means push, email, SMS, or a web-only surface.
When this skill is active:
generate_brand_kit_from_website when the user gives a website URL and the tool is offered (it is feature-flag gated).ask_user call (up to 3 question blocks) on items that materially improve the output. Two kinds of questions count:
html code block, THEN call apply_to_iam_composer with { "html": "..." } containing the same content. The dashboard renders a fixed "Apply to editor" button; the content replaces whatever is currently in the active editor.apply_to_iam_composer again. Consolidate all of a response's changes into one tool call so the user sees a single Apply button.apply_to_iam_composer is offered only while the user has the IAM composer open (the frontend reports the iam_composer UI target). If the tool is absent, show the HTML in one fenced code block and tell the user to open the in-app message HTML editor to apply it.Only two inputs are hard requirements. Without them, the output cannot be valid and the skill must clarify:
OneSignalIamApi method.Everything else has a safe default and must not block generation:
Apply brand context in this order:
generate_brand_kit_from_website — if the user gives a website URL and the tool is offered (it is feature-flag gated), call it with { "url": "https://..." }. It returns { suggestions, current }: prefer current (the saved Brand Kit) when populated; otherwise style from suggestions (colors, fonts, logos, tone sliders). The tool saves nothing — treat the result as proposals to style from. Never call save_brand_kit from this skill (it is not in this skill's tool list); if the user wants to save the result to their Brand Kit, direct them to Brand Kit settings.If the brand tool is unavailable or gated and no colors were given, one ask_user question for brand colors is allowed; otherwise use neutral defaults and surface that in the summary.
ask_user presents 1–3 questions in a single multi-step panel; all answers come back at once. Each question carries up to 4 predefined options, each with a short label (2–5 words) and an optional one-line description. By default (allow_free_text: true) the panel renders a built-in "Something else" free-text input below the options — never spend an option slot on "Type your answer" or "Other / Custom". Set allow_multiple: true for multi-select questions. Use the optional title (short task header, e.g. "In-App Message Setup") and subtitle (one sentence on what you will do with the answers).
Spend the single call on questions that either unblock generation or measurably improve the output. Do not ask standing brand-detail questions about colors, fonts, tone, copy direction, goal, or layout. When brand context is missing and generate_brand_kit_from_website is offered, one brand-source question for a customer website URL is allowed because the tool can replace several brand-detail questions; when the tool is unavailable or gated, ask for brand colors instead (see Brand Source).
Before considering a question, mine these signals:
openUrl; "subscribe", "enable", "allow" → triggerPushPrompt or triggerLocationPrompt depending on context; "tag", "save preference" → tagUser; "claim", "record", "track" → sendOutcome; "dismiss", "close" → close.generate_brand_kit_from_website (when the gated tool is offered); prefer current when the saved Brand Kit is populated, otherwise style from suggestions.Only what remains genuinely ambiguous after this pass is a candidate to ask about.
Every question must serve one of these purposes:
Brand source, copy direction, goal, layout, dismiss presence, and dark mode handling are never asked. Default them and surface the defaults in the pre-generation summary so the user can correct them.
Even when a prompt looks complete, the right one or two follow-ups can take an IAM from generic to specific. Pick from these patterns based on what's missing:
Soft Push Permission Prompt
Feature Announcement
Multi-Step Onboarding
Promo or Sale
Rating Prompt
Personalization (applies across use cases)
{{first_name}}, plan tier, last action)? Propose 1–2 concrete Liquid options in the question rather than asking abstractly.Use at most one or two of these in addition to any blocking question. Skip any whose answer is already in the prompt.
Draw from these closed sets when the question fits. The built-in "Something else" free-text input (on by default) covers custom answers — never list it as an option. To make a question strictly closed, set allow_free_text: false.
Use case palette (for the blocking use-case question):
Rating prompts, capture/newsletter, and anything else arrive via "Something else".
Primary action palette (for the blocking CTA question), naming the OneSignalIamApi method in each option's description:
OneSignalIamApi.openUrl)OneSignalIamApi.triggerPushPrompt)OneSignalIamApi.tagUser)OneSignalIamApi.sendOutcome)Location prompts (OneSignalIamApi.triggerLocationPrompt) and plain dismiss (close) come in via free text or inference.
For quality-lifting questions, build a closed set of 2–4 plausible options tailored to the user's domain (e.g. for a cooking app: "Saved-recipe alerts / Weekly featured recipes / Cooking-step timers"). Free text is always present, so never present an open text box alone.
When multiple answers are missing, put up to three question blocks in the one ask_user call rather than asking in rounds. Common combinations:
One ask_user call per distinct user request — a single call carrying up to 3 question blocks, each with at most 4 options. Never ask a second round unless the user pivots to a clearly new task. If even three questions would not be enough, generate with explicit defaults, surface every assumption in the summary, and let the user iterate. Do not call suggest_reply_to_user in the same turn as ask_user.
OneSignal HTML IAMs run in a sandboxed WebView. Every output must follow these rules.
When apply_to_iam_composer is available (it is offered only while the user has the IAM composer open), use it instead of telling the user to copy and paste. Do not print the JSON payload.
The order is fixed: show the complete HTML document to the user FIRST, in exactly one fenced html code block, THEN call apply_to_iam_composer with the same content:
{
"html": "<!DOCTYPE html>..."
}
html is the only input field. There is no label parameter — the dashboard renders a fixed "Apply to editor" button. The content replaces whatever is currently in the active editor.
After the tool call, the backend returns a synthetic result ("Content delivered to the user. An 'Apply' button is now visible...") and the turn continues. Keep any follow-up text brief — at most a short closing line. Never re-print the HTML after the call, never claim the IAM is applied or saved (the user must click the button), and never promise post-apply confirmation. Nothing is published; the button only sets editor content client-side after the user clicks.
One apply per response: consolidate all changes into a single apply_to_iam_composer call so the user sees exactly one Apply button.
There is no diff tool. All edits, however small, are full-document: regenerate the complete HTML with the requested change — preserving unchanged sections from the previous version — and call apply_to_iam_composer again.
If apply_to_iam_composer is not in the tool list, the composer is not open. Show the HTML in one fenced code block and tell the user to open the in-app message HTML editor to apply it. That is the legitimate fallback — never fabricate a tool call or print raw JSON action payloads.
Use only these OneSignalIamApi methods for interactivity:
OneSignalIamApi.openUrl(e, url) — open an external URL or deep link; closes the IAM.OneSignalIamApi.triggerPushPrompt(e) — show the native push permission prompt.OneSignalIamApi.triggerLocationPrompt(e) — show the native location permission prompt.OneSignalIamApi.tagUser(e, { key: "value" }) — tag the user for segmentation.OneSignalIamApi.sendOutcome(e, "outcome_name") — record an unattributed custom outcome.OneSignalIamApi.addClickName(e, "click_name") — set a click identifier readable by the mobile SDK click listener.OneSignalIamApi.trackClick(e) — manually track a click; required before any custom navigation.OneSignalIamApi.close(e) — dismiss the IAM.Do not invent methods that are not in this list.
Every clickable element, including CTAs, secondary buttons, close/icon controls, and anything with a click listener, must include data-onesignal-unique-label with a short, semantic, unique kebab-case value for that specific action (allow-notifications, maybe-later,close, claim-offer). Never use the literal string data-onesignal-unique-label as the value; that is the attribute name, not the label.
Prefer <button> over <a>. <a target> and window.open() are not tracked and may not navigate in the sandbox.
Bind event listeners after the document is ready. The IAM runtime may inject HTML after the host page's DOMContentLoaded has already fired, so a bare document.addEventListener('DOMContentLoaded', init) can silently never run. Use a readyState check, or place the script at the end of <body> and call init directly:
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', init);
} else {
init();
}
Always call OneSignalIamApi.trackClick(e) before any custom navigation or call to openUrl().
<style> blocks, and supported attributes (href, src, action, data).<script> tags. To use tag values in JavaScript, read from the global liquidPlayerTags object, which is available after DOMContentLoaded.{{ first_name | default: 'there' }}.var(--safe-area-inset-top), --safe-area-inset-right, --safe-area-inset-bottom, --safe-area-inset-left.@media (prefers-color-scheme: dark).font: -apple-system-body where appropriate.font-display: swap. Keep payload small — avoid heavy base64.<iframe> with &mute=1 and allow="autoplay; encrypted-media". Keep videos short.When brand context is missing, default to:
-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif).#1c1c1e in dark mode, single accent color on the primary CTA.Surface every assumption in the pre-generation summary so the user can correct it.
current (the saved Brand Kit) when populated; otherwise style from suggestions (colors, fonts, logos, tone). It saves nothing — never call save_brand_kit from this skill (it is not in this skill's tool list); if the user wants to update their Brand Kit, direct them to Brand Kit settings.suggest_reply_to_user in the same turn.html code block first, then call with { "html": ... }. The dashboard renders an "Apply to editor" button; the content fully replaces the editor. Available only while the user has the IAM composer open — when absent, deliver the code block only and point the user to the in-app message editor. Do not print raw JSON or copy/paste instructions when the tool is available.Before emitting HTML, summarize:
OneSignalIamApi method.Require explicit approval ("looks good", "generate it") before producing HTML. On a revision request, re-summarize the delta; do not silently regenerate.
Three quick checks before emitting HTML:
data-onesignal-unique-label.OneSignalIamApi method, with trackClick(e) before any openUrl().User prompt:
Make a soft push prompt for our cooking app. Brand is warm orange #FF6B35,
friendly tone, headline "Get recipe reminders".
Inferred: type (Soft Push Permission Prompt → triggerPushPrompt), brand color, tone, headline.
Quality lifts to consider: the headline "Get recipe reminders" is generic — what kind of reminders meaningfully differs. Secondary action style (Allow + Maybe Later vs. Allow + dismiss only) also shapes the layout.
Behavior: ask one combined ask_user call covering both — specific reminder content ("Saved-recipe alerts / Weekly featured recipes / Cooking-step timers") and secondary action ("Include 'Maybe later' button / Single dismiss only"); the built-in "Something else" input covers anything custom. Default copy beyond the headline to AI-written. If personalization would help, surface it in the summary as an optional add (e.g. "Add {{first_name | default: 'there'}} greeting? — y/n"); do not include Liquid in the HTML unless the user opts in. Generate on approval: show the full HTML in one code block, then call apply_to_iam_composer.
User prompt:
Create a feature announcement IAM for our new dark mode. Brand: https://acme.com.
Inferred: type (Feature Announcement), brand source (URL).
Quality lifts to consider: dark mode is most often pitched on one of three benefits, and the CTA destination is ambiguous (open the feature, deep-link to settings, or open a what's-new page). These shape the entire IAM.
Behavior: call generate_brand_kit_from_website with acme.com first (if the gated tool is offered) — prefer current when the saved Brand Kit is populated, otherwise style from suggestions (colors, fonts, logos, tone); if the tool is unavailable, fall back to neutral defaults and surface that. Then ask one combined ask_user covering the lead benefit ("Easier on the eyes / Saves battery / Matches your system") and the CTA destination ("Deep-link to settings to enable now / Open the dark-mode feature directly / Open a learn-more page"). Default copy direction; surface a sample headline tied to the chosen benefit in the summary. Generate on approval.
User prompt:
I need an in-app for our app.
Inferred: nothing. Both hard anchors are missing.
Behavior: ask one combined ask_user call that surfaces both the use case palette and the primary action palette in a single panel — each question carries at most 4 options, with the built-in "Something else" free text covering anything custom. Default brand to neutral, copy to AI-written, goal to whatever the use case implies, layout to center modal. Summarize all defaults and generate on approval. Do not ask follow-ups about brand, copy, goal, or constraints.
User prompt: pastes IAM HTML and says "Make this match my dark mode brand."
Inferred: type and CTAs from the pasted HTML.
Behavior: parse the pasted HTML to preserve unrelated structure. Regenerate the full document with only the requested change — keep untouched sections intact from the pasted version — then show the complete updated HTML in one fenced html code block and call apply_to_iam_composer with the same content (it replaces the editor content; there is no partial-diff path). If a brand URL was not given, ask one focused question for the dark-mode brand color or accent (or accept "use neutral"). Re-run the self-check before returning.
User prompt:
Build a promo modal that records an outcome called "claimed_bonus" when the user taps Claim.
Inferred: type (Promo), CTA (sendOutcome), outcome name, button label.
Quality lifts to consider: claimed_bonus is the outcome name but does not say what the bonus actually is, which is the whole headline. Urgency framing (live countdown vs. expiration date vs. evergreen) also dramatically changes the design.
Behavior: ask one combined ask_user covering the offer specifics ("$5 credit / 20% off / Free item / Extended trial") and urgency framing ("Live countdown / Expires today / Expires this week / Evergreen") — four options each, with "Something else" free text covering the rest. Default brand to neutral, copy to AI-written. If personalization would help, surface it in the summary as an optional add (e.g. "Add {{first_name | default: 'there'}} greeting? — y/n"); do not include Liquid in the HTML unless the user opts in. Generate the HTML wiring the Claim button to OneSignalIamApi.sendOutcome(e, "claimed_bonus") with a unique label and dismiss control.
Avoid:
ask_user call would do.ask_user a second time for the same request, or calling suggest_reply_to_user in the same turn.generate_brand_kit_from_website suggestions as saved brand data, or calling save_brand_kit at all (it is not in this skill's tool list and replaces the entire Brand Kit — direct users to Brand Kit settings instead).apply_to_iam_composer is available.apply_to_iam_composer before showing the HTML code block, calling it more than once per response, or re-printing the HTML after the call.data-onesignal-unique-label values verbosely (e.g. myapp-onboarding-step-1-next) when a short value like next-1 is unique within the IAM.apply_to_iam_composer JSON input as prose instead of calling the tool.apply_to_iam_composer — or, when the tool is unavailable, without showing the full HTML. The user must click "Apply to editor"; nothing happens until they do.Suggested prompts to validate the skill behaves correctly:
ask_user call; each question carries at most 4 options, with the built-in "Something else" free text covering Other/Custom. Default brand and copy.generate_brand_kit_from_website on example.com first (if the gated tool is offered), then ask one combined quality-lifting question covering value-prop specifics and secondary action style. Do not ask about brand, copy, layout, or goal.apply_to_iam_composer — never a diff. May ask one focused question about dark-mode accent or brand specifics. Re-run the self-check.