Widgets

Widgets are embeddable views of community features. Each widget has its own id, so several widgets can sit on one page.

They are not the messaging HTTP API and not the leaderboard CRUD API. Those stay in Messaging and Gamification.

WARNING

Authenticated widgets need a widget API key on your backend. That is not a community /v1 key and must never ship in frontend bundles.

Domain allowlist

No domains listed → the widget can be embedded on any origin.

Domains listed → only those origins.

Mode	Who sees it	Child guide
Public	All visitors, read-only, optional CTA	Public widgets
Authenticated	Signed-in members, interactive	Authenticated Widgets

Public iframe host: https://prod-widgets.returning.ai/{{widget_type}}/{{widget_ID}}.

Authenticated flow uses a backend that holds WIDGET_API_KEY, then postMessage into the iframe. Check event.origin against that widget host.

Sizing, theme color, and CTA live in community widget settings. Changing settings updates embeds that point at the same widget id.