Embeddable Widget

Add a floating support button to your website so customers can submit tickets without leaving your site.

The embeddable widget adds a floating chat-style button to any website. When clicked, it opens a ticket submission form — customers can submit a support request without leaving your site. The button, header logo, and accent colors are pulled from your workspace's White-label settings so the widget feels like part of your product.

Three Ways to Embed

Go to Support → Settings → Widget to find all three snippets, ready to copy. Each one is workspace-branded automatically — no extra configuration needed.

A bottom-right floating button on any page. The compact popup includes inline knowledge-base deflection.

<script src="https://app.workestra.com/api/widget/support?workspace_id=YOUR_WORKSPACE_ID" async></script>

Paste this once into your website template before the closing </body> tag — it loads on every page.

2. Direct link

Share a public URL anywhere. Opens the full-page submit form on Workestra, branded with your workspace logo + primary color.

https://app.workestra.com/portal/YOUR-WORKSPACE-SLUG/submit

Good for email signatures, support pages, or in-app banners.

3. Iframe embed

Embed the submit form inside a page on your own site. The visitor never leaves your domain.

<iframe
  src="https://app.workestra.com/portal/YOUR-WORKSPACE-SLUG/submit"
  width="100%"
  height="780"
  style="border:0;max-width:640px;display:block;margin:auto"
  title="Support request form"
  loading="lazy"
></iframe>

A typical use is a /contact page on your marketing site that hosts the embedded form.

The Button

A circular floating button anchored bottom-right. Its background uses your workspace's white-label primary color (or Workestra blue if you haven't configured one). Hover state is a darker shade computed from the same color.

The popup header shows your workspace's logo (if configured) and a brand-named heading like "Acme Support". If no logo is set, only the brand name appears.

The Form

A compact panel with:

Field	Required	Description
Name	Yes	Customer's name
Email	Yes	Email address for replies and tracking
Subject	Yes	Brief summary of the issue
Description	No	Detailed information
Type	No	Support Request, Bug Report, or Feature Request

Focus rings and the Submit button match your brand color.

After Submission

The form shows a success message with the ticket reference number (e.g. TKT-0042). The customer receives a confirmation email with a tracking link.

Every popup shows a small "Powered by Workestra" attribution at the bottom — it's not removable on the standard plan.

Knowledge Base Deflection

As soon as the customer types in the Subject field, the widget searches your published knowledge base articles and shows up to 5 matching results inline — before the form submission button. If a customer's question is already answered in the KB, they can click through and resolve their own issue.

How it works:

The widget debounces input (300 ms) and searches once the subject is at least 3 characters
Results show the article title and a snippet centered on the matching keywords
Clicking a result opens the article in your customer-facing knowledge base in a new tab
Workestra logs each click to kb_widget_events so you can measure deflection rate
The customer can still submit a ticket if no result helps

Only published articles whose visibility is public or workspace-scoped are searchable. Drafts and internal-only articles never appear in the widget.

The more KB content you publish, the higher your deflection rate. Aim for one article per recurring ticket category — you'll spend a week writing them and save months of repeat replies.

How a Submission Flows Through the System

Customer fills out the form on your website
The widget searches your KB inline as they type the subject
If they still need to submit, the widget posts to Workestra's public ticket API
A ticket is created in your Support module with channel Portal
A CRM contact is created if the email doesn't already exist
Auto-assignment routes the ticket to an agent (if configured)
The customer receives a confirmation email with a tracking link

Branding

The widget reads its branding from Settings → Administration → White-label:

White-label field	Where it shows up in the widget
`primary_color`	Floating button, submit button, focus ring, KB result links, hover states
`logo_url`	Small chip in the popup header
`brand_name`	Popup heading (`"{brandName} Support"`)

The widget script is cached aggressively (1 h browser, 24 h CDN). When you change branding, expect the visual update to reach existing visitors within an hour; new visitors see it immediately on the next page load.

If no white-label config exists, the widget falls back to Workestra blue and a generic chat icon.

Where to Embed

Common places to add the widget:

Marketing website — Let visitors ask pre-sales questions
Documentation site — Help readers get support when docs aren't enough
Web application — Give logged-in users a quick way to report issues
Landing pages — Capture feedback during campaigns

Rate Limiting

All three embed options share the same backend limit: 10 submissions per hour per IP address. Customers who exceed this limit see a friendly error message.

Comparison

	Floating widget	Direct link	Iframe embed
Visitor stays on your site	Yes	No	Yes
Setup	One `<script>` line	Share a URL	One `<iframe>` line
Branding	Logo + primary color	Logo + primary color	Logo + primary color
KB deflection	Inline as they type	Inline as they type	Inline as they type
File attachments	Link to full form	Up to 3 × 10 MB	Up to 3 × 10 MB
Mobile	Adapts (bottom-fixed)	Full page	Re-flows in iframe
Best for	Always-available help	Email signatures	A dedicated /contact page

The direct-link and iframe paths both render the same /portal/<slug>/submit page, so any feature the page gains (file attachments, KB deflection, future custom fields) lights up in both immediately. The floating widget is a separate self-contained JavaScript bundle and adds capabilities on its own cadence.

When a widget visitor needs to attach files, the panel includes a small "📎 Need to attach files? Open the full form" link that opens the direct-link /submit page in a new tab — same workspace, same branding, same auto-create-ticket flow. The widget itself is intentionally upload-free to keep the embedded script small and the attack surface narrow.

For the best experience, use both — the widget for quick submissions from your product, and a direct link in customer emails so they can re-engage outside of a session.

Next Steps

Customer Portal — Full portal with tracking and replies
Tickets — Manage tickets from the widget
Auto-Assignment — Route widget tickets to agents