adbtaawrmh4h.widgets.cadenya.com.
Your backend has one job in the live conversation path: authenticate the visitor and mint a Widget Session. The browser receives the session’s short-lived token and the Widget host. It then sends conversation requests and receives event streams from that host. Your Cadenya API key stays on your server, where it belongs.
How Widgets work
Each Widget binds one Agent to one host and one origin allowlist. A conversation created through the Widget becomes an Objective for that Agent. Cadenya derives the workspace, Agent, tenant, subject, secrets, and pinned parameters from the Widget Session instead of trusting values sent by the browser.
Widget overview
1. Mint a Widget Session
The frontend asks your backend for a Widget Session. Your backend authenticates the visitor, calls the Cadenya API with its private API key, and returns only the browser-safe token and host.2. Start conversations
The React UI usesinfo.host as its API base URL and sends the Widget Session token as a bearer token. Conversation requests and SSE events travel between the browser and the Widget host without passing through your backend.
The Widget host uses its DNS label to find the Widget, checks the request’s Origin against the allowlist, and routes the request to the Cadenya environment that owns it. Always use info.host from the Widget Session response. Do not build the hostname from a Widget ID or DNS label.
Configure a Widget
A Widget has three settings that shape new sessions:- Agent: The published Agent that handles conversations.
- Agent Variation: An optional pin to one variation. Without a pin, the Agent’s Variation Selection Mode chooses a variation for each conversation.
- Origin allowlist: The exact web origins that may call the Widget host, including the scheme and optional port. Add
https://app.example.com, not a path or wildcard.
Mint a Widget Session
Call Create a widget session from your backend with an API key that has thewidget_sessions:manage scope.
Never make this request from the browser because it requires your private Cadenya API key.
CADENYA_API_KEY and CADENYA_WORKSPACE_ID from the environment. Set CADENYA_WIDGET_ID to the Widget you want to embed.
Add the React Widget UI
Install the React UI kit and its Radix Themes peer dependency:CadenyaWidgetProvider creates the browser client and points it at the host returned by the Widget Session API. ConversationsPanel supplies the conversation list, message thread, composer, tool approvals, and live event stream.
hostsets the@cadenya/widgetsclient base URL tohttps://{info.host}.tokensupplies the Widget Session bearer token for browser requests.getTokencalls your backend after a request returns401. The provider uses the new token and retries the request once.
getToken must call your backend, which authenticates the visitor again and creates another Widget Session. This keeps the Cadenya API key out of the browser and gives your application control over every token issuance.
If you want to build your own interface, use the lower-level @cadenya/widgets SDK instead. It exposes the Widget config, conversations, events, tool approvals, browser-supplied Bare tool results, and feedback APIs.
cadenya/widgets-sdk
Loading repository data...
Pass trusted context into conversations
A Widget Session carries values that the browser must not choose. Cadenya applies them to every Objective created through the session:- Tenant and subject assertions group conversations under identities from your application. Subjects require a tenant.
- Secrets let the Agent act with a visitor-specific credential. Cadenya encrypts the value and never returns it from an API.
- Pinned parameters force values onto matching tool arguments after the model makes a Tool Call. Use them for IDs such as an account or workspace that the visitor must not change.
- Labels add searchable metadata to every conversation created by the session.