Website widget
The Website widget page configures an embeddable chat button for your website that connects visitors to your own WhatsApp Business number. It opens on /account/widget. Admin-only.
What it is
Zellbox Widget for WhatsApp — a single-line embeddable chat widget for websites that use WhatsApp Business as their main customer channel. Visitors click a floating button, fill a short pre-chat form (name + WhatsApp number + optional reason), and the server sends an approved WhatsApp template from your own WABA to open the conversation. The lead lands in your Zellbox inbox even if the visitor never replies.
Unlike a plain wa.me link (which drops visitors into an empty chat) or a vendor-branded chat widget (which routes everything through a shared number), the Zellbox widget sends the first message from your approved WABA template, on brand, and captures the lead on form submission — before WhatsApp even opens.
Prerequisites
Two conditions must hold before the widget can send its first message:
- A WABA is connected to your workspace. See Account — WhatsApp for the Embedded Signup flow.
- The
widget_welcometemplate is approved on that WABA. Zellbox submits the template automatically for every tenant; Meta approval usually takes minutes to a few hours. The/account/widgetpage shows a red callout and disables Save until both prereqs are green.
Without both, the widget still loads on your site but every /widget/lead submission is refused.
Install
Open Account → Website widget from the sidebar.
Copy the install snippet shown on the page. It looks like:
html<script src="https://zellbox.com/widget/v1.js" data-tenant="YOUR_TENANT_ID" data-locale="auto" async></script>Paste it before the closing
</body>tag on every page where you want the button to appear.
The data-tenant attribute is required. The tenant id is unique to your workspace and visible on the /account/widget page. The data-locale attribute is optional; omit it (or set data-locale="auto") to use the automatic locale detection described below, or set it to one of the supported locale codes (e.g. data-locale="it") to force a specific language.
The script is served from Zellbox's CDN with a 5-minute must-revalidate cache header, so bundle updates reach visitors within minutes. A new tab is not required — the widget mounts asynchronously and a repeated mount is a no-op.
Allowed origins
The widget will only send a template on behalf of your WABA when the form is submitted from a domain you explicitly listed. This prevents a third party from scraping your tenant id and spamming your WABA's quota from their own site.
Add every public origin that will host the widget on /account/widget → Allowed origins. Each origin is the scheme + host of your website (e.g. https://example.com, https://www.example.com — subdomains are separate entries).
What happens when the widget is embedded on a non-allowed origin:
- The script still loads and the button still renders.
- Any
/widget/leadrequest is answered with HTTP 403origin_not_allowedby the API. - The visitor sees the "This site is not authorised to use this widget" error toast localised to their language.
Telemetry beacons (impression / expand / submit) continue to be accepted and are visible in the per-tenant event stream — so you can still see if the widget is being loaded from the wrong domain.
Pre-chat form fields
Each submission contains:
firstName— string, required. The visitor's first name. Used as the1parameter of thewidget_welcometemplate and as the display name in the resulting Zellbox lead row.phone— string, required. E.164 format (+<country><national>). The country-code chip in the widget form uses a searchable 65-country picker that auto-selects from the visitor'snavigator.languageor timezone; the visitor can change it before submitting.reason— string, optional. Free text from the pre-chat textarea. Appended to the lead's internal note so an operator can see the context before they reply.consent— boolean, required. The visitor must tick the "I agree to be contacted on WhatsApp" box before the Open WhatsApp button enables.marketingConsent— boolean, optional. Not currently surfaced in the UI; logged for future use.
Where the lead appears in Zellbox:
- The Leads card on the main
/dashboardlists every widget submission whose phone is not yet linked to a customer row. Internally, these rows live in theBWS_ZELLBOX_WA_UNBOUND_INBOXtable withSOURCE = 'widget'so the regular unbound-inbox flows (dismiss, create customer, merge) work identically. - When the visitor replies on WhatsApp, the inbound-message pipeline auto-links the row to a customer; from that point on the conversation surfaces on the customer's chat history.
Localization
The widget UI ships with 13 built-in locales:
| Code | Language |
|---|---|
en | English |
es | Español |
ca | Català |
pt-BR | Português (Brasil) |
de | Deutsch |
fr | Français |
it | Italiano |
id | Bahasa Indonesia |
tl | Filipino / Tagalog |
tr | Türkçe |
hi | हिन्दी |
ar | العربية |
zh-HK | 繁體中文 (香港) |
Auto-detection order (default when data-locale="auto" or the attribute is omitted):
navigator.languages— if any of the visitor's browser languages maps to a supported locale, use it (falls back to the primary tag, e.g.pt-BR→pt-BR, otherwiseptis not a defined fallback so it drops to step 3).Intl.DateTimeFormat().resolvedOptions().timeZone— if the visitor's timezone maps to a region (e.g.Europe/Rome→IT→it), use that locale.en(final default).
To force a locale regardless of the visitor's browser, set data-locale to the exact code from the table above. An unknown code silently falls back to en.
The outgoing widget_welcome template is also localised: each of the 13 locales has its own approved Meta template, so the first message the visitor sees on WhatsApp is in their language.
Analytics
The widget posts four event types to /widget/event as best-effort navigator.sendBeacon requests (no fetch retries, no blocking):
| Event | When it fires |
|---|---|
impression | Once per page load, right after the button mounts. |
expand | Every time the pre-chat form opens. |
submit | Form submitted. Payload includes hasReason. |
redirect | The visitor was handed the wa.me link and the chat is about to open. |
Rows land in BWS_ZELLBOX_WIDGET_EVENTS, keyed by COMPANY_ID + a timestamped sort key, with a TTL of 90 days set at write time. There is no dedicated admin UI for the stream yet — until one ships, pull aggregates straight from DynamoDB with a Query on the company's events partition, or ask support for a one-off CSV.
The telemetry endpoint always returns HTTP 204; a DDB write failure is swallowed so the widget's UX never depends on the beacons landing.
Rate limits
Two layers apply:
- Per-visitor rate limit. The
/widget/leadendpoint checksWA_UNBOUND_INBOUND_INBOXfor the submitting phone within the last 60 minutes; a repeat submission from the same number returns HTTP 429rate_limitedwithretry_after_sec: 3600. The widget shows the "We already received your request" error in the visitor's language. - WhatsApp 24-hour customer-care window. Meta's own rules apply to the conversation that follows: once the template has opened the thread, your operator can reply free-form for 24 hours; after that a new approved template is needed. See WhatsApp templates for the templating rules.
Troubleshooting
Button doesn't appear on the website
Check, in order:
- The
<script>tag has a non-emptydata-tenantattribute whose value matches the tenant id on/account/widget. - The script URL is loading (open DevTools → Network → filter
widget/v1.js; expect 200 with content-typeapplication/javascript; charset=utf-8). - No Content-Security-Policy on your site is blocking the bundle (
script-srcmust allowhttps://zellbox.comor the CDN). - The allowed-origins list on
/account/widgetincludes the exact scheme + host your site serves from. The button renders even without it, but if origins are empty the widget is effectively dormant.
Template not sending
If visitors fill the form but no WhatsApp message arrives:
- Confirm both prereqs on
/account/widgetare green: WABA connected +widget_welcomeapproved for the visitor's locale. - Open the Leads card on the dashboard — if the lead is listed, the form submission succeeded and the failure is on the Meta send. Zellbox retries template sends with exponential backoff for ~15 minutes.
- Still missing? File a support ticket with the submission timestamp and the visitor's phone (last 4 digits are enough).
Mobile users see the old form
The widget bundle is served with Cache-Control: max-age=300,must-revalidate, so returning visitors may hold a 5-minute-old copy. Hard-refresh clears it. Any update Zellbox ships propagates to every embedded site within ~5 minutes of CloudFront finishing its deploy — no action needed on your side.
FAQ
Can I customise the colour, teaser text, or button icon? Not yet. The widget ships with the WhatsApp brand green (#25d366) and a fixed bottom-right position. Theming is on the roadmap.
Can I A/B test the teaser bubble? Not yet. The teaser text comes from the locale file and is the same for every visitor.
Does it work with single-page apps (React / Vue / SvelteKit / …)? Yes. The widget mounts once per page load; repeated script loads are idempotent. If your app navigates without a full page reload the widget stays mounted.
Does it play nicely with cookie banners? Yes. The bundle loads asynchronously and renders into a closed Shadow DOM, so your consent-management overlay stays on top and the widget's styles cannot bleed into — or receive — the banner's CSS.
Does Zellbox see the message body visitors type? No. The widget sends only the structured fields (firstName, phone, optional reason, consent). The outbound widget_welcome template is server-to-server from your own WABA to Meta; the visitor's subsequent WhatsApp replies go to your operators via the standard inbound path, not through a Zellbox inbox we read as a service.
For other configuration surfaces see Account — General and Account — WhatsApp.