5. Design the widget

The widget is the chat UI your users see. It belongs to one agent and holds its own token, allowed origins, and appearance. Everything except the token and the origins is presentation, which means you restyle the widget or rewrite its welcome message from the console with nothing to redeploy.

Create it

Open the agent and select the Widget tab, then Create widget. A new widget starts enabled, with an empty origin list, which is deliberate: until you allow an origin, it rejects every browser request.

The designer has five tabs and a live preview beside it. Changes stay local until you select Save, and the preview reflects your draft rather than what is deployed.

Theme

Colors, typography, and shape. The fields that matter most:

Field	What it controls
`primaryColor`	Launcher button, send button, and accents
`userBubbleColor`, `assistantBubbleColor`	The two message bubbles
`backgroundColor`, `surfaceColor`, `textColor`	Panel background and text
`fontFamily`	Defaults to the system stack
`radius`, `shadow`	Corner rounding and panel elevation
`dark`	`false`, `true`, or `system` to follow the visitor’s setting

Match your product rather than Urai’s defaults. Set the primary color to your brand color and the font to the one your app already loads, and the widget stops looking bolted on.

Layout

Mode is floating or inline. Floating mounts a launcher button in a corner of the page. Inline renders the panel into an element you provide, which suits a dedicated help page or a sidebar.

Position puts the floating launcher at bottom-right or bottom-left.

Width and height size the panel, defaulting to 380 by 560 pixels.

Button label, brand name, and brand logo URL are the visible copy and mark. The brand name defaults to Assistant; use your product’s name for it.

Show header toggles the title bar.

Behavior

Welcome message is the first thing in an empty conversation. Say what the agent can do, in one line: Ask me about invoices, timers, or approvals.

Suggested questions appear as buttons before the visitor types. Three good ones raise engagement more than any styling change, and they teach people what the agent is for. Use real questions your support team receives.

Placeholder, send label, and new conversation label are copy.

Footer text and disclaimer hold the small print, such as a note that replies are generated and a link to your privacy policy.

Reset on close clears the conversation whenever the panel closes. Leave it off unless the widget handles sensitive data on a shared machine.

Persist across sessions keeps the thread across reloads, which is on by default and is what most people expect.

Security

Three things live here, and the first one is the one people get wrong.

Allowed origins is one origin per line, scheme included:

https://app.acme.com
https://www.acme.com
http://localhost:5173

Every widget request is checked against this list, including the streaming response. An origin that is not listed gets a 403 and the widget shows an error instead of a conversation. Add each environment you embed in, and remember that https://app.acme.com and https://www.acme.com are different origins.

* disables the origin check. It is there for local development. Do not ship it.

Token identifies the widget in the embed snippet. It travels in your page’s HTML, so treat it as a public identifier rather than a secret; the origin list is what actually protects the widget. Rotate token issues a new one and breaks the old one immediately, so plan to deploy the new snippet in the same window.

Enabled turns the widget off without deleting it. A disabled widget stops serving, and deleting it revokes the token and leaves existing threads read only.

Install

This tab shows the snippet you paste into your site, prefilled with your token. It also warns you when your draft has unsaved changes, because the snippet reflects the saved configuration rather than what you are looking at.

Step 6 covers the snippet and the framework packages in detail.

Check before moving on

Save the widget. The preview beside the designer talks to the same agent, so send it a message and confirm you get a real answer with your styling applied. If the preview works but your own page does not, the origin list is the first thing to check.

Next: embed the widget.