Announcements

Announcements are product updates, feature launches, and important notices created in the dashboard. The SDK can show one announcement at a time or open a collection feed.

Show one announcement

Chirp.announcement.open(publicId: string, opts?: AnnouncementOpenOpts): void

Field	Type	Notes
`publicId`	`string`	From the dashboard. Required.
`opts.layout`	`'modal' \| 'drawer' \| 'banner' \| 'toast' \| 'inline'`	Overrides the layout set in the dashboard.
`opts.position`	`'top' \| 'bottom' \| 'top-right' \| ...`	Overrides position.
`opts.layoutSettings`	`{ styles?: ... }`	Per-open theme override — `background`, `text`, `textMuted`, `primary`, `border`, `fontFamily`. See Theming below.

Chirp.announcement.open("release_v2");

Override layout

Chirp.announcement.open("maintenance_window", {
  layout: "banner",
  position: "top",
});

Theme it to match your host page

Pass layoutSettings.styles to override the dashboard-configured theme for this open only. Useful for syncing the surface to a dark or branded host page:

Chirp.announcement.open("release_v2", {
  layout: "drawer",
  layoutSettings: {
    styles: {
      background: "#0a0f2e",
      text: "#ffffff",
      textMuted: "rgba(255,255,255,0.55)",
      primary: "#6366f1",
      border: "rgba(255,255,255,0.1)",
    },
  },
});

The same layoutSettings.styles works on openCollection and changelog.open.

Show a collection feed

A collection groups related announcements (e.g. "Mobile updates", "AI features"). Use openCollection to show users a feed scoped to one collection:

Chirp.announcement.openCollection(collectionPublicId: string, opts?: AnnouncementOpenOpts): void

Chirp.announcement.openCollection("mobile_updates");

The user sees a modal or drawer listing every announcement in that collection. Filter pills are hidden — use changelog.open() instead if you want cross-collection filtering.

Close the current announcement

Chirp.announcement.close(): void

Chirp.announcement.close();

No-op if no announcement is open. Emits announcement:dismissed.

Reset dismissals

By default, a user who dismisses an announcement won't see it again — even on a new session, if the announcement was configured "keep hidden after dismiss".

To clear announcement-specific dismissals (e.g. for testing):

Chirp.announcement.reset();

This only clears announcement state. It does not affect identity, consent, or frequency caps for other surfaces.

Need a full clean slate? Use Chirp.reset() instead — it clears announcements, surveys, and identity together.

Common patterns

Show a release note on first visit after a deploy

useEffect(() => {
  if (lastSeenVersion < currentVersion) {
    Chirp.announcement.open("release_2_4_0");
    setLastSeenVersion(currentVersion);
  }
}, []);

Bind a "What's new" button to a collection

<button onClick={() => Chirp.announcement.openCollection("product_updates")}>
  What's new
</button>

Next steps

Changelog — show the global cross-collection feed
Events — announcement:shown, clicked, dismissed
Announcements (product guide)

On this page