> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/channels-integrations/text-channels/webchat/webchat-front-end.md).

# Configure the WebChat website front end

Configure the WebChat front end that connects customers to WebChat Dialogue Provider.

Configure the WebChat front end separately from WebChat Dialogue Provider backend settings.

{% hint style="warning" %}
Backend WebChat settings and front-end package steps are managed separately. Validate the current SharePoint or WordPress front-end package and target CMS instructions before production rollout.
{% endhint %}

## Before you begin

* WebChat Dialogue Provider 2 is configured. See [WebChat](/channels-integrations/text-channels/webchat.md).
* The website owner can edit the target page, theme, CMS component, or custom HTML/script area.
* The WebChat FrontEnd package or snippet supplied for the customer environment is available.
* Website privacy, storage, cookie, and accessibility requirements are known.

{% hint style="warning" %}
Do not use unconfirmed demo URLs, regional package URLs, or fixed CMS instructions unless support confirms them for the customer environment. Use the WebChat FrontEnd package or snippet supplied for the environment.
{% endhint %}

## Choose an integration option

| Option                 | Use                                                                                                                                                      |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTML integration       | Embeds the WebChat front end in a web page that can host the required script or markup.                                                                  |
| SharePoint integration | Embeds the WebChat front end in a SharePoint site after custom-script, embed, page, and permission requirements are validated with the SharePoint owner. |
| WordPress integration  | Embeds the WebChat front end in WordPress through a theme, widget, customizer, plugin, or custom HTML area that allows the supplied script.              |
| Other CMS integration  | Embeds the WebChat front end in another website platform that allows custom HTML or script loading.                                                      |

## Load the WebChat FrontEnd

1. Confirm which front-end integration option the customer uses.
2. Confirm the current WebChat front-end package or snippet for the environment.
3. Add the supplied bootstrap script or snippet to the target page or CMS component.
4. Configure the page to call `WebChat.load(config)` after the script is available, if the supplied integration model uses that configuration object.
5. Add the provider or endpoint values supplied for the WebChat channel.
6. Save or publish the page in a non-production location first.

When the configuration includes a Unified Contact Center (UCC) selection, `uccName` is resolved in this order: the website configuration object, `config.json`, and then the primary UCC connected to WebChat Dialogue Provider 2.

{% hint style="info" %}
If the FrontEnd script loads without a configuration object, the widget can remain hidden or incomplete depending on the supplied package. Use the configuration pattern supplied for the environment.
{% endhint %}

## Configure FrontEnd behavior

Configure only the behavior approved for the website:

| Area               | Use                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Presence behavior  | Controls which state customers see for the UCC presence values `Available`, `Busy`, `Away`, and `Offline`.                      |
| Parent element     | Uses the `parent` setting to render WebChat inside a specified page element instead of the default lower-right floating button. |
| Tease messages     | Uses `TeaseMessageSettings` to show a proactive message or teaser before the customer opens chat.                               |
| Persistence        | Uses `storageLocation` to control where browser conversation state is stored.                                                   |
| Language switching | Uses `WebChat.changeLanguage(language)` to change the FrontEnd language after WebChat has started.                              |

For presence behavior, configure each UCC presence with one supported front-end state. Presence and state are separate:

| UCC presence | Meaning                                                                             |
| ------------ | ----------------------------------------------------------------------------------- |
| `Available`  | Agents are available and chat can be enabled.                                       |
| `Busy`       | The UCC is available, but the expected wait can be longer than usual.               |
| `Away`       | Agents are away; use the configured away behavior.                                  |
| `Offline`    | The server is unavailable or agents are offline; chat input is limited or disabled. |

| Front-end state           | Behavior                                                              |
| ------------------------- | --------------------------------------------------------------------- |
| `Enabled`                 | Chat is fully open.                                                   |
| `WindowDisabled`          | Shows the start button, but prevents customers from opening a chat.   |
| `ChatInteractionDisabled` | Customers can open the chat window, but chat interaction is disabled. |
| `Hidden`                  | The WebChat entry point is hidden.                                    |

When the UCC presence is `Away`, new WebChat messages can finish pre-queue handling without forming a queued session until the UCC becomes available again. Existing sessions can continue. When the UCC presence is `Offline`, the server cannot receive customer input.

`TeaseMessageSettings` can include:

| Field                | Use                                                                              |
| -------------------- | -------------------------------------------------------------------------------- |
| `message`            | Defines the proactive message text.                                              |
| `showAsMessage`      | Displays the text as a chat message.                                             |
| `showAsTeaser`       | Displays the text as a teaser overlay.                                           |
| `onScrollPercentage` | Shows the tease message after the user scrolls a defined percentage of the page. |
| `onTimeout`          | Shows the tease message after a timeout in milliseconds.                         |

Only the first matching tease trigger fires. After the first tease message is displayed, subsequent triggers are ignored.

For persistence, `storageLocation` accepts any browser storage object that implements `getItem` and `setItem`. If no storage object is supplied, WebChat uses `sessionStorage`. Session state survives page navigation and tab refresh within the same browser session. State is cleared when the user clears browser storage or cache.

`WebChat.changeLanguage(language)` accepts a two-letter ISO language code. When no language is set, the FrontEnd auto-detects the browser language from `window.navigator.language` and falls back to English when the detected language is not supported. Call `WebChat.changeLanguage(language)` only after WebChat has started; it throws if called before start.

## Configure display and branding

Use display customization carefully:

| Area            | Use                                                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Templates       | Customize major UI areas such as the start button, notification, top bar, connected-agent display, agent placeholder, or tease message. |
| Theme           | Select a supplied light or dark theme, or apply approved theme color values.                                                            |
| Theme switching | Uses `WebChat.toggleStyle(themeName)` to change the active theme after the FrontEnd has loaded.                                         |

Template customization can target areas such as the floating button, top bar, agent placeholder, connected-agent display, notification, and tease message. Use only template elements and resources supported by the WebChat package supplied for the environment.

`WebChat.toggleStyle(themeName)` can switch between supplied light and dark themes or an approved custom theme name after the FrontEnd has loaded. When only the default light and dark themes are used, WebChat can follow the user's device theme behavior.

{% hint style="warning" %}
The default WebChat templates are designed to conform to WCAG 2.2. Theme, color, markup, and template changes can affect accessibility. Validate contrast, keyboard use, focus state, and screen-reader behavior before production rollout.
{% endhint %}

## Advanced website integration

Use these options only when the website owner or developer confirms they are needed:

* Load post-load customization after the FrontEnd has loaded. Use `WebChatLoaded` for post-load website customization; see [WebChat front-end events](/developer-docs/webchat-front-end-events.md).
* Pass customer context such as endpoint or display name into the FrontEnd with `WebChat.setUser('endpoint@domain.com', 'Username')` when supported by the supplied package.
* Render WebChat inside a specific DOM element controlled by the website.
* Add website-specific storage, cookie, or privacy handling around conversation persistence.

`WebChat.setUser('endpoint@domain.com', 'Username')` passes an endpoint and optional username into the FrontEnd. If the username is omitted, the FrontEnd shows an anonymous display. Call `WebChat.setUser` only after `WebChatLoaded` fires; it throws if called before WebChat has started.

{% hint style="warning" %}
Client-side values can be viewed or manipulated by website users. Do not trust user data passed from the browser as authoritative identity, authorization, or entitlement data.
{% endhint %}

## Front-end behavior reference

| Area                   | Use                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| Script loading         | Loads the environment-supplied package or snippet on the website.                                    |
| Configuration object   | Defines FrontEnd behavior when the supplied package uses `WebChat.load(config)`.                     |
| Parent setting         | Controls the parent page or element relationship for the WebChat front end.                          |
| Tease message settings | Controls proactive or teaser text shown before the customer opens chat.                              |
| Templates              | Controls front-end layout or message templates.                                                      |
| Theming                | Controls front-end visual styling.                                                                   |
| FrontEnd loaded event  | Signals that the front end has loaded. Keep developer event details in developer reference material. |
| Browser validation     | Confirms that the website's supported browsers can load and use the front end.                       |

## Validate the front end

1. Open the test page that hosts the WebChat front end.
2. Confirm that the front end loads without browser console errors.
3. Start a test conversation.
4. Confirm that the conversation reaches WebAgent through the configured WebChat provider.
5. Confirm that `Available`, `Away`, and `Offline` presence behavior matches the approved state configuration.
6. Trigger the approved tease message condition and confirm that only the first matching trigger displays the tease message.
7. Navigate and refresh within the same browser session to confirm persistence behavior, then clear browser storage or cache and confirm that stored chat state is cleared.
8. Confirm that theme switching, language switching, parent rendering, and optional `setUser` behavior match the approved website requirements.
9. Confirm that the widget remains usable with keyboard navigation and meets the website accessibility requirements.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://atlas.anywhere.now/channels-integrations/text-channels/webchat/webchat-front-end.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.