Preset settings

With the preset settings you can customize:

• Which project preset and palette to use
• The remember user configuration
• The Riddle language
• When the Riddle automatically opens and closes
• The Riddle and block timer
• Navigation: pagination, auto-advance, back navigation
• What the visitor sees while answering: live score, right/wrong feedback, results and stats on blocks
• Vote limits: single vote per device, IP limits, email blocklist
• Button and message texts, the footer (logo + text) and Riddle-level ad slots

Default case

If no preset setting is specified and the Riddle is created in a project (!) the default preset and its selected palette will be used for the built Riddle.

Click here to learn how to set a default preset for your project.

Specifying preset settings

The preset settings properties are sent in the preset property of the build object. If we now for example want to use a preset and palette from our project the request would look like this:

{
    "blocks": [...],
    "preset": {
        "preset": 805,
        "palette": "Zymx"
    }
}

Retrieving preset and palette IDs

Retrieving your project's presets and associated palettes is possible through the Builder API presets endpoint. An example response looks like this:

{
    "success": true,
    "code": 200,
    "data": [
        {
            "id": 805,
            "name": "My project preset",
            "palettes": [
                {
                    "id": "Zymx",
                    "name": "my palette"
                }
            ]
        }
    ]
}

palette accepts either form: the palette's id ("Zymx") or its name ("my palette"). If neither matches, the error message lists the palettes available in the Riddle's preset.

All preset properties

Every property is optional. Which ones are accepted depends on the Riddle type, see the "Available for..." column below.

Note: In a plain POST create build, a property that does not exist for the type you are building is silently ignored by default - unless you turn on strictProperties, in which case it is rejected with a 400 naming the property and listing what is supported for that type instead. That strict behaviour is not optional when editing an existing Riddle (PUT) - there an inapplicable property (e.g. preset.revealResultsLater, Poll only, sent for a Quiz) is always rejected.

Note: Sending preset re-applies that project preset to the Riddle from scratch. Any other preset property you send in the same build config is applied on top of it, so {"preset": 805, "language": "de_formal"} gives you the project preset with German as its language.

Customizing individual palette values

paletteValues overrides individual design values (colors, fonts, layout options) of the palette the Riddle ends up on, without switching to a different palette. It is an object of path => value pairs, e.g.:

{
    "blocks": [...],
    "preset": {
        "paletteValues": {
            "bgColor": "#ffffff",
            "font.name": "Roboto"
        }
    }
}

If palette is sent in the same build config, the values are applied on top of that palette. A built-in palette is forked into a Riddle-owned copy first, since a built-in palette itself cannot be changed. An unknown path or a value that does not match the path (e.g. a non-color string for a color field) is rejected, naming the path and the reason.

Reading a Riddle back only reports the values that differ from the palette's own defaults, not the palette's full content.

Add remember user configuration

'Remember user' means writing the user's answers to the local storage, meaning that the user doesn't have to input their name or email again when revisiting the Riddle / website.

Properties

Example

{
    "blocks": [...],
    "preset": {
        "rememberUser": {
            "isEnabled": true,
            "isAutoSubmitEnabled": false,
            "isDsgvoAccepted": true,
            "isUserPermissionRequired": false
        }
    }
}

Changing Riddle language

The language of the Riddle can be changed by setting the language property in the preset settings. The default is en.

Most languages are their plain ISO code (en, it, es), some carry a region (en-GB, pt-br, zh-tw), and some exist only as a formal and a casual tone variant, written as <language>:formal / <language>:casual: de:formal, de:casual, fr:formal, fr:casual, cs:formal, pt:formal, zh-hans:formal, zh-hans:casual. The older underscore spelling (de_formal) is still accepted and normalized to the colon form.

Sending a variant language's bare code (de, fr) resolves to its formal variant where it has one. A variant language with no formal variant rejects the bare code and lists the variants you can send explicitly instead. An unknown language is rejected with the full list of available codes.

Example

{
    "blocks": [...],
    "preset": {
        "language": "de:formal"
    }
}

Opening the Riddle at a set time

Opening the Riddle at a set time can be done by setting the autoOpenDate property in the preset settings. The value must be a date in the format 'YYYY-mm-dd HH:ii:ss', e.g. '2023-10-01 00:00:00'. The date must be in the timezone Europe/Berlin (German local time).

Example

{
    "blocks": [...],
    "preset": {
        "autoOpenDate": "2099-10-01 00:00:00"
    }
}

Closing the Riddle at a set time

Closing the Riddle at a set time can be done by setting the autoClose property in the preset settings. The property is an object with the following properties:

Example

{
    "blocks": [...],
    "preset": {
        "autoClose": {
            "date": "2099-10-01 00:00:00",
            "resultId": 1
        }
    }
}

As with autoOpenDate, sending date switches the automatic closing on, and sending resultId switches on showing that result once the Riddle is closed.

Setting Riddle timer

The Riddle timer is a limit on how long the user has to complete the Riddle.

Note: The Riddle timer is available for polls, quizzes, personality tests, forms and minigames. For all other Riddle types, riddleTimer is silently ignored in a plain create build, but rejected as an unsupported property (see the note under All preset properties) when strict validation applies - editing an existing Riddle, or strictProperties: true.

Properties

Example

{
    "blocks": [...],
    "preset": {
        "riddleTimer": {
            "timeLimit": 60,
            "pauseOnNonQuestionBlocks": true,
            "warningAt": 10,
            "format": "s",
            "shape": "circleTimer"
        }
    }
}

Setting block timer

The block timer is a limit on how long the user has to complete a block. The time limit can be set either per block or globally for all blocks.

Note: The block timer is available for polls, quizzes, personality tests, forms and minigames. For all other Riddle types, blockTimer is silently ignored in a plain create build, but rejected as an unsupported property (see the note under All preset properties) when strict validation applies - editing an existing Riddle, or strictProperties: true.

Properties

Example

Setting a global block time limit:

{
    "blocks": [...],
    "preset": {
        "blockTimer": {
            "timeLimit": 60,
            "pauseOnNonQuestionBlocks": true,
            "warningAt": 10,
            "format": "s",
            "shape": "circleTimer"
        }
    }
}

Setting a block time limit for each block:

{
    "blocks": [
        {
            "title": "Solve this Riddle: What is the capital of France?",
            "type": "SingleChoice",
            "items": [
                { "title": "Paris", "isCorrect": true },
                { "title": "Berlin", "isCorrect": false }
            ]
        },
        {
            "title": "Solve this Riddle: What is the capital of Germany?",
            "type": "SingleChoice",
            "items": [
                { "title": "Berlin", "isCorrect": true },
                { "title": "Paris", "isCorrect": false }
            ]
        }
    ],
    "preset": {
        "blockTimer": {
            "individualBlockTimes": [60, 30]
        }
    }
}

Timer warm-up

Available for polls, quizzes, personality tests, forms and minigames: a short countdown before the timer actually starts running.

Pagination

Available for polls, quizzes, personality tests, forms and stories. Pagination is the pager and progress bar the visitor navigates the Riddle with; it is on by default.

Note: Pagination and custom logic are mutually exclusive - a logic tree already controls how the Riddle moves from block to block. This is not just about isEnabled: sending logic in the same build config together with any of pagination's toggles set to true - isEnabled, pagerIsEnabled, progressBarIsEnabled, isOnlyOnQuestionBlocksEnabled or isBackNavigationEnabled (paginationStyle is pure styling and is exempt) - is rejected, naming which toggle(s) conflict. Only sending logic with pagination.isEnabled: false and every other toggle left false or omitted is accepted - that combination is what lets a Riddle with custom logic be re-saved with its preset object at all.

Example:

{
    "blocks": [...],
    "preset": {
        "pagination": {
            "isEnabled": true,
            "paginationStyle": "Segmented",
            "isBackNavigationEnabled": true
        }
    }
}

Live score

Quiz only: a running score displayed while the visitor answers.

Right/wrong answer feedback

Quiz only: what the visitor sees right after answering a question.

The message texts themselves can be overridden with customStrings.correctAnswerText and customStrings.wrongAnswerText.

Results on blocks

Available for polls, quizzes, personality tests and forms: showing how everyone else answered, right on the block.

Stats before voting

Available for polls, quizzes, personality tests and forms: showing how popular the Riddle is before the visitor answers.

Reveal results later

Poll only: keep the results hidden until a set date, e.g. while a vote is still running.

Single vote

Available for polls, quizzes, personality tests, forms and predictors: limit each visitor's device to one submission.

Note: isVoteAgainEnabled has no single default. A newly created Quiz starts with true (retaking is allowed), a newly created Poll with false (retaking is blocked), and every other type with whatever its own default preset data carries. This only applies to a Riddle created without a parent preset - one built with a presetId inherits the setting from that preset instead. Send the key explicitly whenever the distinction matters to you rather than relying on the type default.

IP limit

Available for the same Riddle types as single vote: a coarser limit per IP address.

Clock

Minigame only: an always-visible clock counting up (as opposed to a countdown timer).

Open or close the Riddle right away

isRiddleOpen is the master switch for whether the Riddle accepts submissions at all - independent of autoOpenDate and autoClose, which schedule that state for a date.

{
    "blocks": [...],
    "preset": {
        "isRiddleOpen": false
    }
}

Scheduling an opening date closes the Riddle as a side effect, so this is also how you open one back up, or close one without inventing a date for it. Sending both in the same build config is fine: isRiddleOpen is applied after autoOpenDate and wins.

Personality result calculation

Personality tests only. Both properties pick between the same two scoring modes; they apply to the two independent ways such a test can be scored.

TotalPointsAchieved ranks results by the raw points a participant collected for each of them. MaxAchievablePoints ranks them by the share of the points that were achievable for that result, which keeps results with fewer scoring answers competitive.

{
    "blocks": [...],
    "preset": {
        "personalitySettings": {
            "calculationType": "MaxAchievablePoints"
        }
    }
}

Custom strings

customStrings overrides the Riddle's button and feedback texts. Sending at least one of them switches the custom-strings feature on.

Example:

{
    "blocks": [...],
    "preset": {
        "customStrings": {
            "startBtn": "Let's go!",
            "nextBtn": "Continue",
            "correctAnswerText": "Spot on!"
        }
    }
}

Footer

isRiddleFooterVisible (default true) controls whether the Riddle has a footer at all. Inside it you can place your own text and logo.

Footer text

Footer branding

Example:

{
    "blocks": [...],
    "preset": {
        "isRiddleFooterVisible": true,
        "footerText": {
            "text": "Sponsored by Example Inc.",
            "isOnAllBlocksEnabled": true
        },
        "footerBranding": {
            "type": "CustomLogo",
            "logo": "https://httpbin.io/image/jpeg",
            "logoPosition": "Left",
            "maxWidth": 120,
            "link": "https://www.your-website.com"
        }
    }
}

Riddle-level ads

Unlike the Ad block (which is a block of its own in the Riddle), ads places a fixed ad slot above and/or below the whole Riddle. Supplying either slot switches ads on.

Each slot is configured with either a project ad slot or a custom iframe - setting one clears the other:

Note: projectSlot requires the Riddle to belong to a team, since the slot IDs are the team's own.

Example:

{
    "blocks": [...],
    "preset": {
        "ads": {
            "adTop": {
                "projectSlot": {
                    "slotId": 123456,
                    "variables": {
                        "ad-variable-key1": "override-value1"
                    }
                }
            },
            "adBottom": {
                "iframe": {
                    "url": "https://ads.your-website.com/ad.html",
                    "height": 250
                }
            }
        }
    }
}

External content privacy banner

Available for polls, quizzes, personality tests, forms and stories: before an embedded YouTube/X/Vimeo item is loaded, the visitor is asked for consent.

Full example

A poll with a preset object built into it: German as its formal variant, a segmented pager the visitor can navigate back through, an opening date, and returning visitors remembered.

{
    "type": "Poll",
    "build": {
        "title": "Pasta poll",
        "blocks": [
            {
                "type": "SingleChoice",
                "title": "Spaghetti or Fusilli?",
                "items": [
                    { "title": "Spaghetti" },
                    { "title": "Fusilli" }
                ]
            }
        ],
        "result": {
            "title": "Thanks for voting!"
        },
        "preset": {
            "language": "de:formal",
            "autoOpenDate": "2026-09-01 00:00:00",
            "pagination": {
                "isEnabled": true,
                "paginationStyle": "Segmented",
                "isBackNavigationEnabled": true
            },
            "rememberUser": {
                "isEnabled": true,
                "isDsgvoAccepted": true
            }
        }
    }
}