Qaid
ARTICLE

Ask Follow-Up Questions: Link Thumbs Buttons to Quests

Replace the optional message box with a targeted quest — ask one set of questions after a thumbs-up, another after a thumbs-down, and another after a screen recording.

Qaid Team

The Qaid feedback embed (@qaiddev/thumbs-embed) ends every interaction with a small, optional message box: "Would you like to add a message?" It is friendly and low-friction, but a free-text box is a blunt instrument. When someone taps thumbs-down, you often want to know which part let them down. When they tap thumbs-up, you might want to ask what they would recommend you build next. Those are two different conversations — and a single text area can't have either one well.

This guide wires each button to a quest instead. A quest is a short, structured questionnaire powered by @qaiddev/quests-embed — the questionnaire sibling of the thumbs embed. You can point thumbs-up at one quest, thumbs-down at another, and the video button at a third. The thumbs embed stays a thin link: it doesn't grow any questionnaire logic, it just hands off to the quest.

The idea in one picture

thumbs-up   ──▶  "What did you love?" quest
thumbs-down ──▶  "What went wrong?" quest
video sent  ──▶  "Can we follow up?" quest

Each link is optional. Leave a button unset and it keeps the classic message box. Set base to nothing and the whole feature is off — the embed behaves exactly as before.

What you need first

  1. A Qaid project and its API key. The same key authorizes both feedback and quest responses, so you don't need a second one.
  2. A published quest for each button you want to link. Build them in the quest editor and publish. You only need each quest's ID — you'll find it in the quest's editor URL and its "Embed" panel.

Step 1 — Add the quests block

Add a quests object to your existing thumbs configuration. The only required field is base — the URL of the quest service. On Qaid that's https://qaid.dev/api/quests.

import { QaidFeedback } from '@qaiddev/thumbs-embed';

new QaidFeedback({
  endpoint: 'https://qaid.dev/api/feedback',
  apiKey: 'YOUR_API_KEY',
  captureVideo: true,
  quests: {
    base: 'https://qaid.dev/api/quests',
    up: 'QUEST_ID_FOR_THUMBS_UP',     // optional
    down: 'QUEST_ID_FOR_THUMBS_DOWN', // optional
    video: 'QUEST_ID_AFTER_VIDEO',    // optional
  },
});

Prefer the script tag? Every field maps to a data-quest-* attribute:

<script
  src="https://unpkg.com/@qaiddev/thumbs-embed/dist/embed.js"
  data-endpoint="https://qaid.dev/api/feedback"
  data-api-key="YOUR_API_KEY"
  data-capture-video="true"
  data-quest-base="https://qaid.dev/api/quests"
  data-quest-up="QUEST_ID_FOR_THUMBS_UP"
  data-quest-down="QUEST_ID_FOR_THUMBS_DOWN"
  data-quest-video="QUEST_ID_AFTER_VIDEO"
></script>

That's the whole setup. Now when a visitor taps thumbs-up, the embed records the feedback and — instead of the message box — opens the linked quest as a centered modal. The quest owns its own backdrop, focus trap, and close button; when the visitor finishes (or closes it), you're back to the page.

How the URLs are derived

You give the embed one base and a quest ID. From those it builds everything it needs, matching the routes Qaid already serves:

WhatURL
Quest definition (fetched by the embed){base}/{questId}/definition
Response endpoint (create / autosave / submit){base}/responses

So base: 'https://qaid.dev/api/quests' with up: 'abc123' loads the quest from https://qaid.dev/api/quests/abc123/definition and submits answers to https://qaid.dev/api/quests/responses. If you self-host, point base at your own quest service that follows the same shape.

A different conversation per button

The whole point is that each sentiment deserves its own questions. A common pattern:

new QaidFeedback({
  endpoint: 'https://qaid.dev/api/feedback',
  apiKey: 'YOUR_API_KEY',
  quests: {
    base: 'https://qaid.dev/api/quests',
    // Happy path: find out what to double down on.
    up: 'nps-and-what-to-build-next',
    // Unhappy path: triage the problem.
    down: 'what-broke-and-how-severe',
  },
});

You don't have to link every button. Here only thumbs-up and thumbs-down open quests; a video button (if enabled) would fall back to its normal review-and-send flow with the optional description box.

The video button fires after the recording is sent

The video button is special because a recording is precious — you never want to lose it behind a questionnaire. So the order is:

  1. The visitor records their screen and reviews it.
  2. They click Send — the recording uploads as usual.
  3. Then the video quest opens.

The recording is safely stored before any follow-up questions appear. If you don't set quests.video, the video flow is completely unchanged.

Answers are linked back to the feedback

When the embed launches a quest, it passes along the ID of the feedback record it just created. The quest response is stored with that feedbackId, so in your dashboard a single thumbs-down and the answers the visitor gave afterward are two halves of the same story — joinable, not two disconnected rows.

Feedback  { id: "clx…42", type: "down" }
              ▲
              │ feedbackId
QuestResponse { id: "clx…99", answers: { severity: "high", … } }

The link is validated on the server: a response is only tied to a feedback record that belongs to the same project, so a forged ID can't cross-link.

It fails gracefully, and stays zero-dependency

The quest embed isn't bundled into the thumbs embed — it's loaded from a CDN the first time a quest is actually triggered. That keeps the thumbs script tiny and dependency-free. Two things follow from this:

  • If the quest embed can't load (a network blip, a blocked CDN), the embed quietly falls back to the classic message box, so the visitor can still leave a note. You never lose the feedback.
  • The quests package must be reachable at runtime. The default is the public unpkg build. To self-host or pin a version, set moduleUrl:
quests: {
  base: 'https://qaid.dev/api/quests',
  up: 'abc123',
  moduleUrl: 'https://your-cdn.example.com/quests-embed/qaid-quests.js',
}

Theming carries over

Both embeds read the same --qaid-* CSS variables and colors namespace, so a theme you wrote for your feedback buttons already styles the quest that opens from them. There's nothing extra to configure — the quest inherits your brand out of the box. See brand color matching for the full palette.

Where the answers show up

Quest responses land in the same place as any other quest's responses — the quest's Responses and Analytics tabs in your dashboard — with the linked feedback available alongside them. Feedback keeps flowing into your feedback inbox exactly as before; the quest just adds structured context on top.

Summary

Linking buttons to quests turns a one-size-fits-all text box into a purpose-built follow-up:

  • Add a quests block with a base and a quest ID per button (up, down, video).
  • Each link is optional; unlinked buttons keep the message box.
  • The video quest opens only after the recording is safely sent.
  • Responses are joined back to the feedback record via feedbackId.
  • The quest embed loads on demand and falls back to the message box if it can't.

Next, learn how to design the quests themselves in Getting Started with Quests, add conditional follow-up questions, and match your brand with theming.

Back to all articles