Widget Branding

Customize colors, logo, greeting, and position to match your brand.

How Branding Works

When the widget loads, it makes a request to /widget/config using your site key. The API returns a branding configuration object that controls the widget's appearance and behavior. This means you manage all branding from the dashboard — changes take effect immediately for all visitors without redeploying your website or updating the embed snippet.

Request

GET /widget/config
Header: X-Site-Key: zt_pub_abc123...

Response payload

{
  "primaryColor": "#6366f1",
  "logoUrl": "https://cdn.example.com/logo.png",
  "greeting": "Hi there! How can we help?",
  "position": "bottom-right",
  "offlineMessage": "We're offline right now. Leave a message and we'll get back to you."
}

Branding Fields

`primaryColor`

A hex color value used as the widget's accent color. It controls the chat bubble background, send button, header background, and link highlights. Choose a color with good contrast against white text — the widget renders white text and icons on top of this color.

Type	`string` (hex color)
Default	`#6366f1` (Indigo 500)
Example	`#0ea5e9`, `#10b981`, `#f59e0b`

💡The widget automatically generates a slightly darker shade for hover states and a lighter tint for backgrounds. You only need to set one color.

`logoUrl`

URL of your company logo displayed in the widget header. It appears as a 32×32px circle image next to your workspace name. Use a square image with transparent background for best results. SVG, PNG, and JPEG formats are supported.

Type	`string` (URL)
Default	ZapTicket placeholder icon
Max size	200 KB recommended

⚠️The logo URL must be served over HTTPS. Mixed-content requests will be blocked by browsers. Ensure the image host has appropriate CORS headers if served from a different domain.

`greeting`

The welcome message shown in the widget when a visitor opens it for the first time (before any conversation exists). Use this to set expectations — let visitors know what kind of help they can expect and typical response times.

Type	`string`
Default	"Hi there! How can we help?"
Max length	200 characters

`position`

Controls where the chat bubble appears on the page. The widget supports two positions:

Value	Description
bottom-right	Fixed to the bottom-right corner (default, most common)
bottom-left	Fixed to the bottom-left corner

The bubble is inset 20px from the edge of the viewport. When expanded, the chat panel grows upward from the bubble position.

`offlineMessage`

Shown to visitors when no agents are currently online. When all agents in the workspace are offline (based on presence tracking), the widget replaces the live chat interface with a ticket submission form. This message appears above that form to explain the situation.

Type	`string`
Default	"We're offline right now. Leave a message and we'll get back to you."
Max length	300 characters

Updating Branding

All branding fields are configured from the dashboard at Settings → Branding. Changes are saved to the database and served immediately on the next /widget/config request. Because the widget fetches its config on each page load, visitors see updated branding without any code changes or redeployment on your side.

Go to Settings → Branding in the dashboard.
Update any field (color picker, logo upload, text fields, position toggle).
Click Save.
Refresh your website — the widget reflects the new branding.

💡Branding is cached by the widget for the duration of a page session. If a visitor already has the widget open, they'll see updated branding on their next page load or browser refresh.

Branding via API

You can also update branding programmatically through the API. This is useful for white-label setups where you manage multiple workspaces.

Update branding via API

curl -X PATCH https://api.zapticket.app/api/workspaces/current/branding \
  -H "Authorization: Bearer zt_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#0ea5e9",
    "greeting": "Welcome! Ask us anything.",
    "position": "bottom-left"
  }'

Design Tips

Pick a primary color that contrasts well with white — the widget uses white text on colored backgrounds.
Keep your greeting short and friendly. Visitors scan, they don't read paragraphs.
Use bottom-right unless you have a conflicting element there (cookie banners, other chat tools).
Test your offline message — temporarily set your status to offline in the dashboard to preview the experience.