Make it match your brand

Open the widget editor

In the dashboard, go to Deploy, open Widgets, and click your widget. You get a split view: settings on the left with Appearance, Content, and Embed tabs, and a live preview of your real widget on the right. Every change shows in the preview immediately — nothing goes live until you click Save Changes.

app.qalyb.ai/channels/widgets/wt_abc123

Set your colors on the Appearance tab

Pick your Primary Color (used for the launcher, send button, and agent accents) and Accent Color (gradients, the voice orb glow, active states) — type a hex code or use the color picker. Then choose Light, Dark, or Auto theme (Auto follows the visitor's device setting), which corner of the page the widget sits in (bottom right or bottom left), and the Border Radius (0–32px — 0 for sharp square corners, higher for rounder).

Tip:

set the primary color to your brand color and the border radius to match your site's buttons. Those two changes alone make the widget read as native rather than bolted-on.

Add your logo and copy on the Content tab

Paste your Logo URL (a hosted PNG or SVG), set the header Title (defaults to the agent's name) and Subtitle (e.g. "Online now"), and write the Welcome Message — the agent's opening line. You can also style the launcher: a compact icon button or a labeled pill (e.g. "Ask Noura — AI guide"), a launcher icon (Chat, Bot, Sparkles, or Voice), and whether the widget opens by itself when the page loads or waits for a click.

app.qalyb.ai/channels/widgets/wt_abc123

Check the preview and save

The preview on the right renders your real widget with the unsaved settings — use the refresh or external-link button to open it full-page in a new tab. Happy with it? Click Save Changes.

You're done:

sites that already have your widget update automatically — there's no need to re-paste the embed code just to change colors or copy.

Let Qalyb find your colors for you

You don't have to hunt down hex codes. During agent and widget setup, Qalyb can look at your website and pre-fill a starting brand profile — your site name, logo, primary color, and accent color. It's a best-effort starting point: if nothing useful is found, you simply get Qalyb's defaults and adjust in the editor. It never blocks your setup.

What can — and can't — be changed

You can fully theme everything a visitor reads and touches: colors, corner radius, theme, position, logo, header copy, welcome message, and the launcher.

Two honest caveats: the launcher, dictation, and file-upload settings only apply to chat widgets — the voice widget shows the full-screen voice orb, which still honors your colors and logo but ignores the chat-bubble launcher settings. And the soundEnabled field exists in the customization schema but has no control in the editor yet.

For developers

Everything in the Appearance and Content tabs is stored as a single customization object on the widget token:

{
  "theme": "light",
  "position": "bottom-right",
  "primaryColor": "#5C5CF6",
  "accentColor": "#06B6D4",
  "borderRadius": 16,
  "title": "Acme Support",
  "subtitle": "Online now",
  "welcomeMessage": "Marhaba! How can we help?",
  "logo": "https://acme.com/logo.svg",
  "autoOpen": false,
  "launcherVariant": "pill",
  "launcherLabel": "Ask Noura",
  "launcherSubtitle": "AI guide",
  "launcherIcon": "sparkles"
}

Persist it with a PATCH to the widget token — send a partial update and only the keys you include change. Requires the channels:write permission (admin-only). The live embed reads the saved object back, so an API update is reflected on your site without re-pasting the embed snippet:

curl -X PATCH https://api.qalyb.ai/widget-tokens/wt_abc123 \
  -H "Authorization: Bearer sk-live-..." \
  -H "X-Organization-Id: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "customization": {
      "primaryColor": "#5C5CF6",
      "accentColor": "#06B6D4",
      "borderRadius": 16,
      "title": "Acme Support",
      "logo": "https://acme.com/logo.svg"
    }
  }'

The auto-branding helper is GET /branding?url=. It requires the agents:write permission and is intentionally fail-safe: if the URL can't be reached or nothing useful comes back, it returns Qalyb's brand defaults (primaryColor #5C5CF6, accentColor #06B6D4, with siteName/logoUrl as null) rather than erroring. Private, internal, or otherwise non-public URLs are rejected with URL is not allowed.

curl "https://api.qalyb.ai/branding?url=https://acme.com" \
  -H "Authorization: Bearer sk-live-..." \
  -H "X-Organization-Id: org_abc123"

# Response — best-effort; falls back to Qalyb brand defaults on any failure
{
  "siteName": "Acme",
  "logoUrl": "https://acme.com/logo.svg",
  "primaryColor": "#5C5CF6",
  "accentColor": "#06B6D4"
}