Publish settings

Publishing the built Riddle after creation

The request body parameter publish can be sent with the API to publish the Riddle right after creation, making it easier to embed the generated content on the web page.

Example:

{
    "type": "Poll",
    "publish": true,
    "build": {
        "blocks": [...]
    }
}

Advanced settings

With these publish settings you can define any settings found in the Riddle Creator Publish screen.

Properties

You can specify the following optional properties:

Note: DOI, email OTP and SMS OTP are three alternative ways of verifying a lead and only one of them can be active. Enabling one automatically switches the other two off, exactly as the Riddle Creator does.

Example

The publish settings properties are sent in the publish property of the build object, here's how it looks:

{
    "blocks": [...],
    "publish": {
        "isDoiEnabled": true,
        ...
    }
}

Integrations

You can add existing Googlesheets & webhook integrations to your Riddle. To do this, you can specify integrations in your publish object.

Example:

{
    "blocks": [...],
    "publish": {
        "integrations": {
            "googlesheets": "test@riddle.com",
            "webhook": "your-website.com/webhook"
        }
    }
}

In this example we already connected the Googlesheets integration with the email test@riddle.com and the webhook integration with the URL your-website.com/webhook. The name of the integration you send here must match with the name displayed on the integrations page in the Riddle Creator.

If the integration cannot be found, the Riddle build will fail and you will get a RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_INVALID error from the API.

DOI

To enable DOI, first set isDoiEnabled to true:

{
    "isDoiEnabled": true
}

Enabling it will set the first email field in the Riddle as the DOI field.

If you want to customize the DOI email or confirmation page, you can send the following properties in doiConfig:

Note: If you send a confirmationPageUrl property, the other confirmation page properties are redundant as the user gets redirected to the URL immediately after confirming the DOI (user does not see extra confirmation page headline/text).

Note: Sending any of confirmationPageHeadline, confirmationPageBody or confirmationPageUrl automatically switches the custom confirmation page on - you do not need a separate flag for it.

Note: confirmationPageUrl accepts an empty string as well: "" is what an unset redirect stores, so sending "" removes a stored one and the user sees the confirmation page again instead of being redirected.

Note: emailFieldIdentifier must be the identifier of an Email field that actually exists in the built Riddle (e.g. email1); anything else is rejected and the error lists the identifiers you can use. You only need it if your Riddle has more than one email field, e.g. an "invite a friend" form.

Note: emailText and confirmationPageBody are HTML rich text, exactly like the email automation body below - write one <p>...</p> per paragraph, or separate your paragraphs by blank lines and they are converted for you. emailSubject, emailConfirmationButtonLabel and confirmationPageHeadline are one-liners.

Tip: Use dynamic variables for any of the DOI properties to personalize this flow to user input. Only variables that this particular Riddle can actually resolve are accepted - e.g. %name needs a Name form field. If you use one that does not exist, the error message lists every variable that is usable in your Riddle.

Example:

{
    "isDoiEnabled": true,
    "doiConfig": {
        "emailSubject": "Please confirm your email %name",
        "emailText": "<p>Hi %name,</p><p>Please confirm your email by clicking the button below.</p>",
        "emailConfirmationButtonLabel": "Confirm email",
        "confirmationPageHeadline": "Thank you for confirming your email",
        "confirmationPageBody": "You can now access the content",
        "confirmationPageUrl": "https://www.your-website.com"
    }
}

Email OTP

Instead of a confirmation link (DOI), you can have the visitor type back a one-time code that is emailed to them. Set isOtpEnabled to true; the first email field of the Riddle is picked automatically, and DOI/SMS OTP are switched off.

otpConfig accepts:

Example:

{
    "isOtpEnabled": true,
    "otpConfig": {
        "isSaveUnconfirmedEnabled": true
    }
}

SMS OTP

The same one-time-code flow, but over SMS. Set isOtpSMSEnabled to true - this requires a Phone form field in the Riddle (the first one is picked automatically) and switches DOI/email OTP off.

otpSMSConfig accepts:

Note: vendorApiKey is write-only. It is never returned when you read a Riddle back as a build configuration, so a credential is not handed out to anyone who can read the Riddle's structure.

Example:

{
    "isOtpSMSEnabled": true,
    "otpSMSConfig": {
        "vendor": "LinkMobility",
        "vendorApiKey": "my-api-key"
    }
}

Showcase page and QR code

isShowcaseEnabled controls whether the Riddle is reachable through its direct link (riddle.com/view/XXX) at all - it is enabled by default. showcaseConfig fine-tunes that page and the QR code generated for it:

Note: customQrCodeDestination is the one URL property here that also accepts an empty string: "" is what an unset custom destination stores, so sending "" removes a stored one and the QR code points at the showcase page again.

Example:

{
    "isShowcaseEnabled": true,
    "showcaseConfig": {
        "isFullScreenEnabled": true,
        "isCustomQrCodeDestinationEnabled": true,
        "customQrCodeDestination": "https://www.your-website.com/campaign"
    }
}

Email automation

To enable email automation, first set isEmailAutomationEnabled to true:

{
    "isEmailAutomationEnabled": true
}

Enabling it will set the first email field in the Riddle as the email automation field.

Enabling it also prefills a default subject and text for you (e.g. "Thanks for taking our quiz!", including the score and result for quizzes) - you only need emailAutomationConfig if you want something else.

The prefilled text greets the respondent (by their name if the Riddle has a Name field), names the Riddle, and ends with a link back to it. On a validation-only request the link is left out, because the Riddle it would point at is the temporary copy the validation discards.

If you want to customize the email that is sent, you can send the following properties in emailAutomationConfig:

Note: Exactly one email is ever sent per submission - the conditional emails and the one above never stack. See Conditional emails below for the full rule.

Note: subject is sent as an email header, so it must not contain a line break, may not be longer than 400 bytes (one header line - a longer subject is folded or cut off by the receiving mail server, so the detail belongs in text) and may not contain a bidirectional formatting character (U+202A-U+202E, U+2066-U+2069), which would make the subject an inbox displays differ from the one stored here. The plain direction marks U+200E/U+200F are allowed. text is the email body: it may contain line breaks and has no length cap. The same holds for each conditional email's subject.

Note: The email body is HTML rich text - the same markup the Riddle Creator's editor writes, rendered as HTML in the recipient's mail client. Write one <p>...</p> per paragraph:

{
    "text": "<p>Hi %name,</p><p>Thanks for taking part - your result is %result.title.</p><p>See you next time!</p>"
}

<p>, <br>, <strong>, <em>, <a href>, <ul>/<li> and <h2>-<h6> all work; scripts, iframes, forms and event attributes are rejected. Plain text is accepted too and converted for you: a blank line between two paragraphs becomes a paragraph, a single newline a line break. What cannot be converted is a body written as one long run of sentences with no line break in it at all - there is nothing to split on, and the email arrives as one unbroken wall of text. So either send the markup, or at least separate your paragraphs by blank lines. This applies to the normal email's text, every conditional email's text and the DOI emailText/confirmationPageBody; subjects and headlines are one-liners and are never turned into paragraphs.

Note: recipient is a form field identifier (e.g. email1) and must name an Email field in the built Riddle. Send "" to drop your choice again - the first Email field of the Riddle is used, exactly as when you enabled the automation. recipientCC, recipientBCC and replyTo are the opposite: plain, literal email addresses, each of which must be a valid address.

Tip: Use dynamic variables for any of the email automation properties to personalize this flow to user input.

Example:

{
    "isEmailAutomationEnabled": true,
    "emailAutomationConfig": {
        "subject": "Thank you for participating %name!",
        "text": "<p>Thank you for participating in our quiz %name.</p><p>Here are your results: ...</p>"
    }
}

Conditional emails

Next to the one email everybody gets, you can send conditional emails: each one has a condition and is only sent to the respondents that match it. Add them as emails inside emailAutomationConfig (max 50):

{
    "isEmailAutomationEnabled": true,
    "emailAutomationConfig": {
        "emails": [
            {
                "condition": { "field": "1", "operator": "equals", "value": "Yes" },
                "subject": "Great to hear, %name!",
                "text": "You said yes - here is what happens next ..."
            },
            {
                "condition": { "field": "2.1", "operator": "contains", "value": "@riddle.com" },
                "subject": "Hi colleague!",
                "text": "Nice to see you here."
            }
        ]
    }
}

Each entry accepts:

Note The two raffle events wait for a raffle draw, and a raffle is not part of a Riddle's build configuration - it is set up in the Riddle Creator under Publish > Raffle. The events are accepted either way (the raffle may well be created after the email is written), but publishing a Riddle whose email waits for a draw that nobody configured returns the warning RAFFLE_EVENT_WITHOUT_RAFFLE: that email can never be sent. Either set the raffle up, or give the email the riddle_finished event.

The condition object is the same one condition branching uses:

• field is the ID of the block whose answer is compared ("1"), or "<blockId>.<fieldId>" for a form field nested inside a FormBuilder block ("2.1").
• operator must be one allowed for that kind of field (equals, notEquals, contains, isAnswered, isChecked, ...) - see the operator table on the logic settings page.
• value is what the field is compared against, and is left out for standalone checks like isAnswered. For a fixed-choice field (an answer, a dropdown, a country) it must name one of that field's actual choices, by title or ID.

value also has to fit the operator beside it, and a mismatch is refused rather than stored:

The same rules apply to a condition branching condition - both use one and the same condition object.

subject and text accept the same dynamic variables as the normal automation email. text is HTML rich text there as well - see the note under Email automation.

They are also read back as those variables: reading the Riddle returns Well done, %name and not the internal markup it is stored as, so the copy you read can be edited and sent straight back.

Note: every conditional email needs a subject, and an empty or blank one is refused - both when creating the email and on an edit that would blank it. Because the first matching email wins, an email without a subject would still match, still suppress the normal email, and then send nothing: one incomplete entry would silently take away the email every other respondent was getting. text may be left empty; a subject-only email is fine.

Read the Riddle back for the block IDs you address: they are assigned across the whole Riddle, not by the position of the block in blocks. On a Personality test, for instance, the personalities are created first, so the first block usually has ID 3. A field that resolves to nothing answers with the list of everything that Riddle can address.

One email per result

A conditional email can also condition on the result the respondent got - which is what "one email per personality" or "one email per score band" needs. Put a magic variable in field instead of a block ID:

• Quiz: magic.result.title, magic.score.number, magic.score.max, magic.score.percentage
• Personality: magic.<personality|attribute>[.<2-5>].<title|desc|label|score|percentage> - without a rank this is the winning personality/attribute (magic.personality.title), with a rank of 2 to 5 the runner-ups (magic.personality.2.title)

{
    "isEmailAutomationEnabled": true,
    "emailAutomationConfig": {
        "isCatchAllEnabled": false,
        "emails": [
            {
                "condition": { "field": "magic.personality.title", "operator": "equals", "value": "The Cat" },
                "subject": "You are a cat, %name!"
            },
            {
                "condition": { "field": "magic.personality.percentage", "operator": "greaterThan", "value": 80 },
                "subject": "A very clear result"
            }
        ]
    }
}

Text result fields take equals, notEquals, contains, notContains, startsWith, notStartsWith, endsWith, notEndsWith; number fields the comparisons (greaterThan, lessThanOrEquals, ...); a percentage additionally between / notBetween, whose value is a two-element array ([80, 100]).

Riddle types without a result (Poll, Form, Predictor, ...) reject these fields. Result fields work in automation emails only - condition branching cannot use them, because the logic tree is what produces the result in the first place.

Only one email is ever sent

Conditional emails are not sent on top of the normal one. Per submission, exactly one email goes out:

1. the first conditional email whose condition matches this submission - and nothing else, even if a later condition would match too ($emailsOrder therefore decides precedence);
2. if no conditional email matches, the normal email above is sent as the fallback;
3. if no conditional email matches and the normal email is switched off (isCatchAllEnabled: false) or was never given a subject and text, nothing is sent at all.

Everything here also needs isEmailAutomationEnabled: true; with false nothing is sent no matter what is configured. Sending isEmailAutomationEnabled: false on an edit switches a running automation back off and keeps its subject, text and conditional emails stored for when you switch it on again.

To send only the conditional emails, switch the normal one off - respondents matching no condition then get no email:

{
    "isEmailAutomationEnabled": true,
    "emailAutomationConfig": {
        "isCatchAllEnabled": false,
        "emails": [ ... ]
    }
}

Editing conditional emails

When editing an existing Riddle, emails is merged by id rather than replaced - so you can change one email without resending the others. Read the Riddle back to get the IDs, then:

{
    "emailAutomationConfig": {
        "emails": [
            { "id": 1, "subject": "A better subject" },
            { "id": 2, "$delete": true },
            { "$create": true, "condition": { "field": "1", "operator": "equals", "value": "No" }, "subject": "Maybe next time" }
        ],
        "$emailsOrder": [3, 1]
    }
}

• An entry with an id updates only the keys it contains - everything else about that email, its condition included, stays as it is.
• {"$create": true, ...} adds a new email (which needs a condition), {"id": X, "$delete": true} removes one, and $emailsOrder re-orders them by ID.
• An email you do not mention is left untouched. Sending "emails": [] removes all of them.
• IDs are never reused while the collection has entries: a new email always gets a fresh one. Clearing every mail with "emails": [] resets the numbering, so the first mail added afterwards is id 1 again - do not hold on to an id across a clear.
• A block (or a FormBuilder field) a conditional email conditions on cannot be deleted while that email still references it: the delete is refused and names the email, rather than leaving behind an email whose condition silently never matches again. Fix both sides in the same request - delete the block and give the email a new condition, $delete the email, or send "emails": [].
• A form field an automation text references as a dynamic variable is protected the same way: while any automation subject or text - the normal email's or a conditional one's - still contains %name, that Name field cannot be deleted. The refusal names every text that references it, and is cleared by sending new copy for those texts (or deleting the email) in the same request.
• Keep in mind that switching the automation on writes a default text that itself greets the respondent with %name whenever the Riddle has a Name field - so that field can be protected by copy you never wrote yourself. Rewrite the normal email's text and the delete goes through.
• Publishing a Riddle whose automation is switched on but can never send anything - no conditional email has a subject, and the normal email is switched off ("isCatchAllEnabled": false) or has no subject either - succeeds, with a non-blocking EMAIL_AUTOMATION_UNSENDABLE warning in validationWarnings. It does not block the publish: writing the conditional emails while the normal one is already off is a legitimate intermediate state.
• This protection covers the email automation only. The same variables in result pages, double opt-in texts and Text blocks still let the delete through, and only warn about the dangling reference afterwards.

Data Layer

The Riddle Data Layer can be setup with the dataLayerItems property which is a key-value array: The key is the key of the data layer variable (this is used to push to it, e.g. riddle.com/view/XXX?key=value or dataLayer.push({ key: value })) and the value is the title of the variable which will be used in the export as the data layer column name.

Example: Adding three data layer variables:

{
    "dataLayerItems": {
        "utm_source": "Source",
        "utm_medium": "Medium",
        "utm_campaign": "Campaign"
    }
}

Two further data layer switches are available next to the variables themselves:

Tracking

With the tracking property you can define which tracking should be enabled for your Riddle. By default no tracking is enabled.

The following tracking options are available (case-sensitive):

• adobe
• facebookPixel
• googleAnalytics
• googleAnalytics4
• googleTagManager
• matomoTag

Example: Activating Google Tag Manager and Matomo Tag:

{
    "tracking": ["googleTagManager", "matomoTag"]
}

Note: tracking is a switch and nothing more - it enables the networks you list and disables every one you leave out. It cannot configure customTracking; use trackingNetworks below for that.

Advanced tracking configuration

trackingNetworks is the richer form of the same setting: an object keyed by network name, where each network can be configured in detail. It is applied after tracking, so you can use the simple list to switch networks on and this to fill in the details - or use trackingNetworks alone.

Next to the six networks listed above, trackingNetworks also accepts customTracking.

Note: Supplying a trackingId automatically enables that network's configuration - a credential you sent would otherwise never be used.

eventConfig accepts these keys, all booleans:

An unknown network name, an unknown event key or a non-boolean event value is rejected, and the error message lists the keys you can use.

Example: switching on Google Tag Manager with its container ID, forwarding only the core metrics, plus a custom tracking function:

{
    "trackingNetworks": {
        "googleTagManager": {
            "isEnabled": true,
            "trackingId": "GTM-XXXXXX",
            "eventConfig": {
                "isEnabled": true,
                "Block_View": false,
                "Block_Next": false,
                "isIncludeFormDataEnabled": true
            }
        },
        "customTracking": {
            "isEnabled": true,
            "eventFunction": "(riddleEvent) => { console.log(riddleEvent); }"
        }
    }
}

Embed settings

embedSettings defines how the published Riddle behaves once it is embedded on your own page - the same options the Embed screen of the Riddle Creator offers. They are applied to the embed code you retrieve for the Riddle.

Note: Unlike everything else on this page, embed settings have no draft/live distinction - they take effect immediately, without publishing the Riddle again.

Example:

{
    "embedSettings": {
        "iframeMaxWidth": "800px",
        "isLazyLoadRiddleActive": true,
        "isAutoScrollOffsetEnabled": true,
        "autoScrollOffset": 120
    }
}

Full example

{
    "type": "Poll",
    "publish": true,
    "build": {
        "blocks": [...],
        "publish": {
            "isDoiEnabled": true,
            "doiConfig": {
                "emailSubject": "Please confirm your email %name",
                "emailText": "<p>Hi %name,</p><p>Please confirm your email by clicking the button below.</p>",
                "emailConfirmationButtonLabel": "Confirm email",
                "confirmationPageHeadline": "Thank you for confirming your email",
                "confirmationPageBody": "You can now access the content",
                "confirmationPageUrl": "https://www.your-website.com"
            },
            "isEmailAutomationEnabled": true,
            "emailAutomationConfig": {
                "subject": "Thank you for participating %name!",
                "text": "<p>Thank you for participating in our quiz %name.</p><p>Here are your results: ...</p>"
            },
            "dataLayerItems": {
                "utm_source": "Source",
                "utm_medium": "Medium",
                "utm_campaign": "Campaign"
            },
            "isDataLayerSubmitEnabled": true,
            "tracking": ["googleTagManager", "matomoTag"],
            "trackingNetworks": {
                "googleTagManager": {
                    "trackingId": "GTM-XXXXXX"
                }
            },
            "embedSettings": {
                "iframeMaxWidth": "800px",
                "isLazyLoadRiddleActive": true
            },
            "integrations": {
                "googlesheets": "test@riddle.com",
                "webhook": "https://www.your-website.com/webhook"
            }
        }
    }
}