Surveys

Surveys are created and configured in the dashboard. The SDK is the runtime that displays them in your app, respects frequency rules, and reports responses back.

Open a survey

Chirp.survey.open(publicId: string, opts?: SurveyOpenOpts): void

Field	Type	Notes
`publicId`	`string`	From the dashboard share menu — looks like `nps_q2_check`.
`opts.force`	`boolean`	Default `false`. Bypass frequency / cooldown rules.
`opts.variables`	`Record<string, unknown>`	Pass data into survey logic and branching. Available in questions as `{userId}`, etc.
`opts.theme`	`Theme`	Override colors, font, or radius for this open.

Minimum usage

Chirp.survey.open("nps_q2_check");

With variables and theming

Chirp.survey.open("post_checkout_csat", {
  variables: {
    productName: "Pro plan",
    invoiceAmount: 299,
  },
  theme: {
    primaryColor: "#1F4BFF",
    radius: 12,
    colorScheme: "dark",
  },
});

Force a survey to show

By default, surveys respect frequency rules and per-user dismissals. To bypass for testing or special triggers:

Chirp.survey.open("debug_form", { force: true });

force: true overrides display caps but not consent. A survey will not show to a user who has denied consent.

Close a survey

Chirp.survey.close(): void

Programmatically dismiss the currently-open survey. Emits survey:dismissed with reason: 'programmatic'. No-op if no survey is open.

Chirp.survey.close();

Common patterns

Trigger after a key user action

async function onCheckoutComplete(order) {
  await trackOrder(order);
  Chirp.survey.open("post_checkout_csat", {
    variables: { orderId: order.id, total: order.total },
  });
}

Trigger from your own UI

If you have a "Give feedback" button in your app, wire it to survey.open:

<button onClick={() => Chirp.survey.open("nps_q2_check", { force: true })}>
  Give feedback
</button>

Listen for completion

Chirp.on("survey:completed", ({ surveyId, response }) => {
  // forward to your own analytics
  analytics.track("survey_done", { surveyId, response });
});

Gotchas

If publicId doesn't exist, the SDK fetches it lazily and shows a skeleton while loading. Watch the network tab if you see a delay.
Opening a survey while another is open closes the previous one first.
Frequency rules are evaluated per-user-per-survey. Use Chirp.reset() to clear them in dev.

Next steps

Events — survey:shown, survey:completed, survey:dismissed
Surveys (product guide) — building surveys in the dashboard

On this page