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 brand color and logo in the Branding section

Branding lives on the agent, not on each widget — set it once and it applies everywhere that agent appears: the chat widget, the voice orb, the playground, and the agent's card in your dashboard. Pick your Brand color (it themes the launcher, header, message bubbles, and send button — type a hex code or use the color picker) and Upload your logo file (PNG, JPG, SVG, or WebP up to 2 MB). No more pasting logo URLs.

Tip:

set the brand color to your site's main 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.

Set the theme and copy

Choose Light, Dark, or Auto theme (Auto follows the visitor's device setting), which corner of the page the widget sits in, and the Border Radius (0–32px). Then 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 setup, Qalyb can look at your website and pre-fill the agent's branding — your site name, logo, and brand 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: the brand color, corner radius, theme, position, logo, header copy, welcome message, and the launcher. The brand color and logo are agent-level — one place to change them, and every widget for that agent follows.

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

Branding (brand color + logo) is stored on the agent. Upload the logo first, then save the returned URL with the color on the agent's branding object — every widget for that agent picks it up on the next load (requires agents:write):

# 1. Upload the logo file (PNG, JPG, SVG, WebP, GIF, or ICO — max 2 MB)
curl -X POST https://api.qalyb.ai/branding/logo \
  -H "Authorization: Bearer sk-live-..." \
  -H "X-Organization-Id: org_abc123" \
  -F "file=@logo.png"
# → { "logoUrl": "https://api.qalyb.ai/branding/logo/org_abc123/.../logo.png" }

# 2. Save the branding on the agent — every widget follows it
curl -X PATCH https://api.qalyb.ai/agents/agent_abc123 \
  -H "Authorization: Bearer sk-live-..." \
  -H "X-Organization-Id: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "branding": {
      "primaryColor": "#5C5CF6",
      "logoUrl": "https://api.qalyb.ai/branding/logo/org_abc123/.../logo.png"
    }
  }'

Widget-level settings (theme, copy, launcher) are stored as a single customization object on the widget token:

{
  "theme": "light",
  "position": "bottom-right",
  "borderRadius": 16,
  "title": "Acme Support",
  "subtitle": "Online now",
  "welcomeMessage": "Marhaba! How can we help?",
  "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. Any primaryColor, accentColor, or logo keys you send here are ignored — those live on the agent's branding now:

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": {
      "borderRadius": 16,
      "title": "Acme Support"
    }
  }'

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"
}