Widget Configuration Guide

The Platform Widget embeds a WIIL chat and voice assistant into any website. You add it with a single element plus a script tag, and configure everything through HTML data-* attributes on the widget element — no JavaScript required.

Quick Start

Add the widget element where you want it to appear, then load the widget script once (typically just before the closing </body> tag):

<div
  id="wiil-widget"
  data-config-id="your-config-id"
  data-route-service="north-america"
></div>
<script src="https://cdn.wiil.io/public/wiil-widget.js"></script>

Replace your-config-id with the configuration ID from your WIIL console. Every other attribute is optional — omit it to use its default.

Required — do not modify these attributes

data-config-id and data-route-service are provisioned by WIIL and connect the widget to your deployment. Keep them exactly as provided in your console, and never edit or remove them:

• data-config-id — binds the widget to your agent/deployment configuration.
• data-route-service — the service routing region for your deployment (e.g. north-america).

All other attributes documented below are safe to customize.

How It Works

All options are set as data-* attributes directly on the widget <div>. The widget reads them on load, so there is no separate configuration file or initialization code to write. To change an option, edit its attribute value; to revert to the default, remove the attribute.

Connection

These attributes identify your deployment. The first two are managed values — see the warning above.

Attribute	Required	Description
data-config-id	Yes	Configuration ID that binds the widget to your WIIL deployment. Managed — do not modify.
data-route-service	Yes	Service routing region for your deployment (e.g. north-america). Managed — do not modify.
data-organization	No	Your organization name shown in the widget header.

Appearance

Control the widget's look and layout.

Property	Data Attribute	Default	Description
primaryColor	data-primary-color	#0d9488	Primary theme color (teal-600)
chatButtonColor	data-chat-button-color	null	Chat button color (defaults to primaryColor)
callButtonColor	data-call-button-color	null	Call button color (defaults to primaryColor)
widgetTitle	data-widget-title	AI Assistant	Widget header title
agentAvatar	data-agent-avatar	null	Agent avatar image URL
position	data-position	bottom-right	Widget position on screen
size	data-size	compact	Widget size: compact or full
theme	data-theme	light	Theme mode: light or dark
embedMode	data-embed-mode	null	Embed mode: null or iframe
panelWidth	data-panel-width	400px	Widget panel width (e.g. 400px, 420px)
panelHeight	data-panel-height	650px	Widget panel max-height (e.g. 650px, 700px)
chatButtonText	data-contact-chat-button-text	Start Chat	Chat button text in contact form
callButtonText	data-contact-call-button-text	Start Call	Call button text in contact form

Features

Choose which interaction modes the widget offers.

Property	Data Attribute	Default	Description
features	data-features	chat	Comma-separated list: chat, voice

Enabling voice

Use data-features="chat,voice" to offer both text chat and voice calling. Leave it as chat for a text-only assistant.

Behavior

Control how the widget engages visitors.

Property	Data Attribute	Default	Description
modeSelectorHeader	data-mode-selector-header	How can we help?	Mode selector header text
callButtonText	data-call-button-text	Tap to speak	Voice call button label
autoOpen	data-auto-open	false	Auto-open widget on load
autoOpenDelay	data-auto-open-delay	3000	Auto-open delay in milliseconds
promptMessage	data-prompt-message	👋 Need help? We're here to assist!	Welcome prompt message
removeHeaderTextTrimming	data-remove-header-text-trimming	false	Disable text trimming on organization header

note

callButtonText appears in two places with different attributes: data-call-button-text (the voice call button label, above) and data-contact-call-button-text (the button in the contact form, under Appearance). Set whichever matches the label you want to change.

Contact Form

Text shown on the pre-conversation form that collects a visitor's email or phone number.

Property	Data Attribute	Default	Description
headerText	data-contact-header-text	Please provide your email or phone number to continue	Form header text
emailLabel	data-contact-email-label	Email Address	Email field label
emailPlaceholder	data-contact-email-placeholder	you@example.com	Email field placeholder
phoneLabel	data-contact-phone-label	Phone Number	Phone field label
phonePlaceholder	data-contact-phone-placeholder	+1 (555) 000-0000	Phone field placeholder
orText	data-contact-or-text	OR	Separator text between email and phone
emailError	data-contact-email-error	Please enter a valid email address	Email validation error message
phoneError	data-contact-phone-error	Please enter a valid phone number	Phone validation error message

Collecting visitor information responsibly

This form gathers personal contact details. Ask only for what you need, and keep your API key server-side — see Handling Customer Data.

Full Example

A widget with a custom color, title, both chat and voice enabled, and a tailored greeting:

<div
  id="wiil-widget"
  data-config-id="your-config-id"
  data-primary-color="#3b82f6"
  data-widget-title="Support Assistant"
  data-position="bottom-right"
  data-size="compact"
  data-theme="light"
  data-features="chat,voice"
  data-organization="Your Company"
  data-route-service="north-america"
  data-auto-open="false"
  data-mode-selector-header="How can we assist you today?"
  data-call-button-text="Start Voice Call"
></div>
<script src="https://cdn.wiil.io/public/wiil-widget.js"></script>

warning

Notice data-config-id and data-route-service remain untouched. Customize the appearance and behavior attributes freely, but always leave those two exactly as issued for your deployment.