Skip to main content

Multi-Platform Raffle

A multi-platform raffle pools entries from several channels into a single draw. The platform produces a verifiable list of winners, plus a PDF "acta" and a CSV audit export for legal reporting.

When to use it​

  • A brand campaign whose entry mechanic spans your owned channels (web/WhatsApp) and social platforms (Instagram/TikTok hashtag).
  • Any sweepstake where you need a reproducible, auditable draw — the platform stores the input pool hash, the random seed, and the output hash.
  • A CSV-only raffle where the entry list comes from an external source (e.g. a partner promotion).

How it works​

You create a CampaignRaffleDraw for a campaign at any point — typically at the end. The draw has:

  • Winners requested — how many winners to pick.
  • Seed — any string up to 128 characters. The same pool + the same seed produces the same winners, so the draw is reproducible if you ever need to re-prove it.
  • Source filter (optional) — restrict the pool to specific channels.

When you run the draw, the platform:

  1. Builds the eligible pool from every approved entry across the selected sources.
  2. Computes a SHA-256 hash of the pool (for audit).
  3. Shuffles the pool with a Fisher–Yates pass derived from the seed.
  4. Picks the first N entries as winners.
  5. Computes a SHA-256 hash of the winners list and records execution duration.

The draw is immutable once run — if you need a different outcome, create a new draw.

Supported sources​

SourceWhere entries come from
FormLanding-page form, WhatsApp conversation flow, or any flow action that calls register_participant.
CSVAdmin uploads a list of participants (email-deduplicated).
InstagramComments under a configured Instagram post, ingested via the connected Instagram source.
TikTokComments under a configured TikTok post, ingested via the connected TikTok source.

You can pool any combination of these into one draw using the Source filter field.

Step-by-step​

1. Capture entries during the campaign​

Make sure each channel you plan to use is feeding the platform:

  • Form / WhatsApp: the conversation flow or landing form needs the register_participant action wired to your campaign. The platform tags those entries with source = Form.
  • CSV: prepare a file with at least Email and FullName columns. The platform will dedupe within the file and against any existing participants.
  • Instagram / TikTok: connect the source under Integrations → Social sources and point it at the post URL whose comments should count as entries.

2. Import a CSV (optional)​

  1. Open the campaign and go to Raffle → Import participants.
  2. Upload the CSV. The file is validated row by row (max 50 000 rows per upload, batched 500 at a time).
  3. The platform shows a summary of inserted vs deduplicated rows. Bad rows are listed but the rest of the file still imports.

3. Create the draw​

  1. Open the campaign and go to Raffle → Draw.
  2. Click New draw.
  3. Fill in:
    • Winners requested
    • Seed (free text — type something memorable like the campaign name + date)
    • Sources (any combination)
  4. Click Run draw.

The result page shows the winners list, plus the pool hash, the output hash, and the execution duration.

4. Export evidence​

From the draw detail page:

  • PDF acta — a legal-style summary of the draw (one PDF per winner, labelled with their source like Source: Form or Source: Instagram (@username)).
  • CSV audit export — the full pool plus the winners flag, downloadable from GET /api/.../raffle/{drawId}/audit.csv.

Limits and gotchas​

  • CSV cap: 50 000 rows per upload. Larger lists must be split.
  • Dedup is by email. Two entries with the same email count as one, both within the upload and against existing participants.
  • Smaller pool than requested winners. If you ask for 50 winners but only 30 entries qualify, the draw runs anyway and stamps ReasonIfPartial = "pool_smaller_than_requested" so you have an audit trail.
  • Social sources need OAuth. The Instagram/TikTok side of the pool only fills if the integration is connected and the platform has fetched the comments — schedule the ingestion before running the draw.
  • WhatsApp is not its own source. WhatsApp-submitted entries arrive via the flow's register_participant action, which tags them as Form. If you need to slice "WhatsApp only" stats, do it at the funnel level rather than the source filter.
  • Permission: Pages.Gamification.Campaigns (plus Pages.Gamification.Campaigns.Winners.View and .Winners.Export for visibility into the winners list and audit export).