Quests

Quest templates

Template families, routing, and payload shapes.

The map from template name to what you render and what you submit. Dozens of template names are live. You do not write a branch per name, you write one per family.

What arrives on the wire

Three different vocabularies show up on a quest, and mixing them up is the most expensive mistake on this page.

template.name is a namespaced wire value, lowercase and dotted:

basic.auto-complete
basic.submit-wallet

The family names below are not wire values, and no SDK function returns them. text, visit, bind and the rest are a grouping you map names into yourself, with the router under Routing. Comparing template.name === 'visit' matches nothing, and because the comparison fails quietly, every quest falls through to your default branch and the page looks like it works.

Two SDK helpers look like they should do this and do not. getApiType returns the submit path, accept, complete or image, and getQuestType returns a number. Neither is a family. Switching on either one sends every quest to your default branch.

Requirement codes are a third namespace, upper snake case, and they are what you see when the machine holds a quest closed rather than what you switch on:

CodeMeans
VISIT_LINK_MISSIONAn outbound link the fan has not opened. See Visit-link quests.
EVENT_JOIN_NOT_ALLOWEDThe fan cannot join the event this quest belongs to.
SOCIAL_*A social account that is not linked. Needs authProfile.
WALLET_*A wallet that is not linked. Needs authProfile.
JOIN_*A community membership gate.

A quest also carries questType, a coarse grouping such as SOCIAL. It is not the template and it is not granular enough to route on.

The full list of names ships inside the package, in the Catalog section of node_modules/@xborglabs/fanbase-react/quest.md. The router below covers every typed name in it. Anything it does not recognise is empty-body, which is the safe default.

Families

Filter by how you submit. Typed families take a payload, empty-body families do not, and that distinction is the one your code actually branches on.

13 of 13

The same thing as a table

FamilySubmitYou render
textsubmit(payload)A text field
answersubmit(payload)A free-form answer field
predictionsubmit(payload)Outcome picker
quizsubmit(payload)Question with options
pollsubmit(payload)Options, single choice
emailsubmit(payload)Email field with validation
walletsubmit(payload)Wallet address field
imagesubmit(payload)File upload with preview
visitQuest.SubmitOutbound link, then the CTA
bindQuest.SubmitLink-account button, then the CTA
progressQuest.SubmitProgress readout, CTA when complete
autoQuest.SubmitStatus, no input
unknownQuest.SubmitFall through to the default branch

Typed families take a payload. Empty-body families do not. That distinction is the one your code branches on.

Routing

Map the template name to a family yourself. Only eight names take a payload, so the map is short, and everything you do not recognise falls through to an empty-body submit:

// Yours to own. Built from the template catalog in the package's quest.md.
const TYPED = {
  'basic.text-submission': 'text',
  'basic.answer-submission': 'answer',
  'basic.prediction': 'prediction',
  'basic.quiz': 'quiz',
  'basic.poll': 'poll',
  'basic.submit-email': 'email',
  'basic.submit-wallet': 'wallet',
  'manual.image-submission': 'image',
}

const VISIT = new Set([
  'basic.visit-link', 'basic.visit-facebook', 'basic.visit-instagram',
  'basic.view-instagram-post', 'basic.view-tiktok-post',
  'youtube.visit-channel', 'youtube.watch-video',
])

const BIND = new Set(['twitch.follow', 'twitch.subscribe', 'youtube.subscribe', 'youtube.like', 'steam.wishlist-game'])
const BIND_PREFIXES = ['twitter.', 'discord.', 'spotify.']

export function familyOf(name = '') {
  if (TYPED[name]) return TYPED[name]
  if (VISIT.has(name)) return 'visit'
  if (BIND.has(name) || BIND_PREFIXES.some((p) => name.startsWith(p))) return 'bind'
  if (name === 'basic.auto-complete') return 'auto'
  return 'other' // progress, gaming, wallet checks and anything new: empty body
}

Typed names come first because they are the ones where a wrong guess loses the fan's input. A new empty-body template needs no change here at all. A new typed one does, and the package's changelog is where you would see it.

Where does this template go?Try it
Your router, familyOf(name)
Familypoll
Submit withactions.submit(payload)
Payload{ text: option }
What getApiType(name) returns
Returns'complete'
A switch (getApiType(name)) with a case 'poll' never matches, so this quest drops to your default branch and is submitted with no payload. The fan's input is lost.
Suggestions are real names from the catalog in the package's quest.md.

Always have a default

default:
  return (
    <Quest.Submit asChild>
      <button disabled={!state.canSubmit}>{state.buttonLabel}</button>
    </Quest.Submit>
  )

An unrecognised name should render something usable rather than a blank panel. The machine still knows whether the fan can act.

Template args

template.args carries the settings a community team configured for that quest. Options for a poll, a URL for a visit, an accepted file type for an upload.

Read defensively. Args are per-template, optional keys are common, and a key being present in the admin panel does not mean it arrives populated:

const options = template.args?.options ?? []
const url = template.args?.url

Types vary across communities for some flags, so compare loosely rather than with a strict === true on a value that might arrive as a string.

Two things worth knowing before you rely on a key:

A documented key can still be null on live rows. Text-submission quests on beta have been observed with args.text null across every row on a tenant. Supply your own fallback label rather than rendering an empty prompt:

const prompt = template.args?.text ?? 'Your answer'

Some templates carry matching flags alongside the value. An answer-family quest arrives with the comparison rules next to it:

{ "answer": "1WH3NC1", "matchExactly": true, "caseSensitive": true }

You submit what the fan typed and let the platform compare. Do not do the comparison yourself, even though the pieces are sitting right there.

Payload shapes

Every typed template sends its value under text, whatever the family. Only the image upload is different.

FamilyPayloadNotes
text{ text: string }At least 3 characters
answer{ text: string }Not answer. The fan's earlier answer reads back from quest.metrics.answer.
prediction{ text: option.label }The option's label, not its index. Predictions.
quiz{ text: option }The option string itself. The platform marks it.
poll{ text: option }The option string itself
email{ text: email }
wallet{ text: address }A 0x address
imageFile[]The files, passed straight to actions.submit
empty-bodynone

Do not invent a payload shape. If a template needs something not listed here, ask rather than guessing, because the platform validates on submit and a wrong shape fails silently from the fan's point of view.

Display names

Templates carry a displayName for admin-facing surfaces. Fan-facing copy comes from the quest's own title and description, so you rarely need it in your app.

On this page