OneSignal Custom Events Skill

Purpose

Help the agent design, send, and use OneSignal Custom Events — named records of user behavior that drive automation, personalize messages, and feed segmentation.

This is a reasoning guide, not a script.

When to Use

Trigger phrases: "track [user action]", "send a custom event", "design an event taxonomy", "trigger a Journey on [event]", "use event properties in a template", "import events from [Segment / Amplitude / Mixpanel / Snowflake / BigQuery / Kafka]", "import from Google Sheets", "tag vs custom event", "why isn't my event firing", "verify my events are reaching OneSignal", "what's the event payload limit".

Lookalike intents that should NOT trigger this skill:

• A long-term user attribute (membership tier, language preference) — that's a Tag, not a Custom Event.
• Designing a Journey that uses an existing event — use onesignal-journeys.
• Designing a Segment that filters on an event — use onesignal-segments.

Key Concepts

A Custom Event is a record of something that happened at a specific point in time. Unlike Tags, events do NOT permanently update a user's profile — they record behavior.

When to use Custom Events:

• Messaging should respond to real-time user behavior.
• The data represents an action (not a state).
• You need event properties for personalization or Journey logic.

When to use Tags instead:

• Long-term user attributes (plan tier, language, lifetime value, opt-in flags).
• State that should persist regardless of recent behavior.

A Custom Event has these fields:

• name (required, string, max 128 chars).
• properties (optional object) — pairs that describe the event (item, price, plan, etc.). Used for personalization and Journey property filters.
• external_id OR onesignal_id — identifies the user. Required when sending via the Create Custom Events API.
• timestamp (optional, ISO 8601) — when the event occurred (defaults to ingest time).
• idempotency_key (optional UUID) — prevents duplicate processing on retry.

Hard limits:

• Max event payload: 2024 bytes.
• Max request size (multiple events batched): 1 MB.

Sources: SDK (mobile + web), Create Custom Events API, integrations (Segment, Amplitude, Mixpanel, Snowflake, BigQuery, Kafka, Google Sheets, and 25+ others). All sources are billed equivalently.

For the full ingestion API, integration list, retention behavior, and Journey property storage rules (the "100 properties per Journey instance" rule), read REFERENCE.md.

Decisions That Shape an Event

Each dimension has a priority tag:

1. Source (Critical) — SDK (client-side), Create Custom Events API (server-side), or integration (Segment / data warehouse / Sheets). Source affects code path, latency, and dedup story.
2. Event name (Critical) — snake_case, past-tense (signup_completed, purchase_completed, cart_updated, payment_failed). Stable and meaningful. Don't rename events that live Journeys depend on.
3. Properties (Often defaultable to "minimal") — what to include. Keep small; only what you'll actually use for personalization, Journey branching, or segmentation.
4. Identification (Critical) — external_id is the standard. Confirm the user has been logged into the SDK first or that backend events include external_id.
5. Idempotency (Often defaultable) — idempotency_key recommended for retried backend events. Required when the same event might fire twice (SDK + backend webhook duplicates).
6. Use case (Critical for design) — Journey trigger, Journey progression (Wait Until), Journey exit, message personalization, segmentation (Early Access). Drives which properties are needed.
7. Timestamp handling (Almost always defaultable) — default to ingest time; explicit timestamp only for backfill or out-of-order events.

Before Asking — Ground in Tools

• Call list_custom_events to see what events already exist. Don't propose a new event if a similar one is already flowing.
• Inspect a candidate event's recent payloads (via the Custom Events page) to see actual property shapes — confirm naming, types, and consistency across sources.
• For "trigger a Journey on this event" requests, also call list_journeys to see if it's already wired in.
• Check Source Breakdown in the dashboard's Custom Events detail view — if the same event name comes from BOTH SDK and an integration, that's the #1 cause of "users get every Journey message twice" (no dedup). Surface this as a warning.

How to Reason About Questions

1. Is the user designing a new event, sending one, debugging one, or asking how to use one downstream? Different questions for each.
2. For design: walk Decisions; mark each Specified / Defaultable / Open. Default to "minimal properties" + idempotency_key for backend sources.
3. For sending / debugging: ground in tools — check the Event List page, Source Breakdown, and recent Activity. Most "event isn't working" issues are visible there.
4. Skip AskUserQuestion entirely when the user pasted code or a payload. Diagnose / extend directly.
5. Otherwise bundle 1–4 most decisive open dimensions into ONE AskUserQuestion call.

Ambiguity to Watch For

• "track [user action]" — could be Custom Event, Tag, or both. Clarify: action over time = event; long-lived state = tag. (For purchase: purchase_completed event AND lifetime_value tag both make sense.)
• "trigger a journey on [event]" — confirm the event exists in OneSignal first. If it doesn't, the design is blocked on a prerequisite (instrument the event before building the Journey).
• "event-driven personalization" — confirm the event has the property they want to interpolate. Liquid that references a missing property renders empty.
• "abandoned cart event" — almost always wants cart_updated (with cart contents in properties) AND a purchase_completed exit. Surface the "same event for entry + exit = restart timer with fresh data" pattern.
• "track everything" — anti-pattern. Recommend an event taxonomy designed around what you'll actually message on, not exhaustive activity logging.
• "why are we sending duplicates" — almost always: same event from SDK + backend without idempotency_key. Diagnose source breakdown.
• "can I store [attribute] as an event" — usually no, that's a Tag. Custom Events are for actions.
• "backfill historical events" — confirm they want to use the timestamp field. Surface that segmentation time-filters reference event RECEIVED time, not original event time — for historical imports where original time matters, store it as a Tag.

Defaults & Best Practices

Apply silently and surface as assumptions:

• Naming: snake_case, past-tense verb. (purchase_completed, not Purchase or purchaseEvent.)
• Properties: minimal. 3–8 keys is normal; 20+ is a smell. Each property eats into the 2024-byte payload limit.
• Property values: strings, numbers, booleans. Avoid deeply nested objects; flatten to top-level keys.
• External ID: required for SDK-tracked events to be tied back to the user; require login first in your SDK init.
• Idempotency: include idempotency_key (UUID) for any event sent from a server with retries.

Best practices:

• For purchases: purchase_completed event with {order_id, total, currency, item_count} + a lifetime_value Tag updated on the same hook.
• For onboarding: discrete events for each milestone (signup_completed, profile_completed, first_action_completed) — easier to branch on than a single onboarding_state event.
• For abandoned cart: cart_updated with full cart contents in properties; purchase_completed as the exit signal.
• For data warehouse imports: use timestamp to preserve original event time. Use idempotency_key derived from (user, event, timestamp) to prevent reimport duplicates.

For full integration setup paths (Segment, Amplitude, Mixpanel, Snowflake, BigQuery, Kafka, Google Sheets), Liquid syntax for event properties, segmentation Early Access limits, and SDK code samples per platform, read REFERENCE.md. For full reasoning traces, read EXAMPLES.md.

Summary and Approval

Every summary must include:

• Event name + source.
• Property schema (keys, types, examples).
• Identification path (external_id from SDK login, or backend value).
• Idempotency strategy.
• How the event will be used (Journey trigger / Wait Until / personalization / segmentation).
• Assumptions — every default applied so the user can correct them.
• Must-mention warnings for this domain:
• Event payload max 2024 bytes; batched request max 1 MB.
• Custom Events appear on the Custom Events page instantly, but can take up to 5 minutes to appear in a user's profile timeline.
• Custom Event segmentation is Early Access — request access via support.
• Don't fire the same event from BOTH SDK and a backend without idempotency_key-based dedup; that's the #1 cause of duplicate Journey messages.
• Use snake_case past-tense names; renaming an event silently breaks every Journey + Segment that depends on it.
• Numbers must be sent as numbers (not strings) for numeric Journey filters and Liquid math to work.
• Don't put PII in event properties (use anonymized internal IDs).
• Tags vs Custom Events: long-lived state → Tag; point-in-time action → Custom Event.

Require explicit user approval before sending events to a production app.

Anti-Patterns

Avoid:

• Storing user state (membership tier, lifetime value) as a Custom Event — use a Tag.
• Storing point-in-time actions (purchase, login) as a Tag instead of an Event.
• Naming events with mixed case, camelCase, or present tense (purchaseEvent, Purchase, purchases). Stick to snake_case past-tense.
• Renaming events without auditing dependent Journeys and Segments.
• Sending the same event from both SDK and backend with no dedup.
• Including PII (emails, phone numbers, names) in event properties.
• Sending numbers as strings (breaks numeric filters and Liquid math).
• Designing 50+ properties per event "just in case" — only include what you'll use.
• Reproducing this skill's example wording verbatim — derive your own from the user's prompt.

Supporting Files

• REFERENCE.md — Create Custom Events API shape, integration list with setup paths, Liquid syntax for event properties, Journey property storage rules (100-per-instance limit), Custom Event segmentation Early Access details, Tags vs Custom Events comparison.
• EXAMPLES.md — worked traces (purchase event design, abandoned cart, signup flow, debugging duplicates, SDK vs backend, "is this an event or a tag", historical backfill).