#Embedding the Chat Widget

Status: Available (current parameters and blocks 1 to 5). Planned: widget v2 parameters, block 6 "Inline block on a page", and block 7 "Your own 'Ask a question' button" in their target form. The status is marked on each parameter and block.

Purpose: add the AI seller chat window to your site with a single <script> line or through the module loader, and configure its look and behavior.

#Contents

1. When to use it
2. Access and requirements
3. Ways to connect
4. Parameters: current (Available)
5. v2 parameters (Planned)
6. Channel settings in the dashboard
7. Site domain and frame headers
8. What the widget looks like
9. Ready-made blocks
10. Errors and diagnostics
11. Known limitations
12. Notes
13. Open questions

#When to use it

• You need a chat on your site without building an interface.
• You want to change the color, greeting, and position from the dashboard without touching page code.
• For your own chat design, use the client Chat API; for a chat in your own messenger, use the server API.

#Access and requirements

The script and the frame are served by the cell where the channel was created. A channel ID from one cell does not work on another.

#Ways to connect

The order of sources for each parameter is: tag data attribute → window.SapportWidget key → default value.

#Parameters: current (Available)

#Tag attributes and window.SapportWidget keys

Keys without a data attribute:

window.SapportWidget must be set before the widget.js tag. If you change consent later, change the property of the same object rather than replacing the whole object.

#What is passed to the frame

When the window is first opened, the widget creates an iframe with the address https://<cell>/widget/<channel_id> and parameters.

widget.js does not put a language in the frame address: the frame language comes from the channel setting locale, and if it is absent, from the visitor's browser language (ru, en, ms, and id are supported; the default is en).

#What the widget does

• Loads the channel settings with a POST /api/widget/init request (this is the only route open to requests from other sites).
• Draws a round 60×60 px button. The window (iframe) is created only on the first click of the button: until then, the page address is not sent to the platform.
• The window is 380×560 px above the button; on screens up to 440 px wide it takes almost the whole screen (width 100vw − 24 px, height 100dvh − 100 px).
• The container's z-index is 2147483647. It cannot be changed with parameters.
• Unread counter on the button: while the window is closed, each new message increases the number (9+ above nine).
• The internal sapport-* CSS classes are not a contract and may change.

#v2 parameters (Planned)

Status: Planned. The parameters below do not work in the current version of widget.js: unknown attributes are ignored. Do not use them in production markup until they are announced in the changelog.

The design does not fix the defaults marked "presumably"; the final values will be in the reference when this ships.

#Channel settings in the dashboard

Part of the look can be changed without editing page code: the settings are stored in the channel and loaded by the init request.

Position, theme, bubble text, and delay reach the widget only as attributes of the code copied from the dashboard. If you connect the widget through the loader (Bitrix/WordPress), these four values are not applied: the loader passes only the channel ID, the address, and the consent flags.

Channel keys that the server reads but that have no fields in the dashboard: locale (frame language), pre_chat_form (the pre-chat form), and ai_daily_limit (the daily limit on AI replies). They are set by editing the channel record; there is no interface for them today.

The embed code in the dashboard is assembled by string substitution: quotes in the bubble text are not escaped. Do not use the " character in the bubble text.

#Site domain and frame headers

The chat window is a page on the cell's domain, embedded in your site. The browser will show it only if your site is allowed by the Content-Security-Policy: frame-ancestors header.

The following are allowed:

• the cell itself;
• the tenant's domains (the tenant's domains list);
• the domains of sites bound to the tenant through the connector (with https:// and https://www.);
• on EN, additionally a static partner list.

Conditions: the channel is active; the tenant is active and has the "Promotion" module available. The response is cached for 60 seconds. If the database is unavailable, the header is built from 'self' only.

The init request does not check the domain: the button may appear even where the window will be blocked.

#What the widget looks like

The mockups are schematic; exact spacing and colors are determined by the theme.

#Button

 Closed:                          Unread messages:                Open:

        Need help?                                                    ┌────┐
       ┌─────────────┐                                                │ ✕  │
       └─────────▽───┘                          ┌─┐                   └────┘
            ╭────────╮                        ╭─┤3├────╮
            │  ◯◯    │  60×60 px              │ └─┘ ◯◯  │            a cross instead of the icon
            ╰────────╯                        ╰────────╯
   the label above the button —       red counter in the corner,
   data-bubble-text                   "9+" above nine

#Window on desktop, 380×560

                                   ┌────────────────────────────────┐
                                   │ ◯  Channel name             ✕  │  header: avatar,
                                   │    ● we reply instantly        │  name, close
                                   ├────────────────────────────────┤
                                   │ ┌───────────────────────┐      │
                                   │ │ Hello! How can we     │      │  greeting
                                   │ │ help?                 │      │  (from channel settings)
                                   │ └───────────────────────┘      │
                                   │                  ┌───────────┐ │
                                   │                  │ How much  │ │  visitor's message
                                   │                  │ is it?    │ │
                                   │                  └───────────┘ │
                                   │ ◌ ● ● ●                        │  typing indicator
                                   ├────────────────────────────────┤
                                   │ [ Type a message…       ] [+] > │  input, attachment
                                   ├────────────────────────────────┤
                                   │        Powered by Formula AI   │  label in the frame
                                   └────────────────────────────────┘
                                        ╭────────╮
                                        │   ✕    │  60×60 button in the corner, 20 px margin
                                        ╰────────╯

#Window on a phone, width ≤ 440 px

 ┌─────────────────────────────┐
 │ ◯ Channel name           ✕  │   width: 100vw − 24 px
 │   ● we reply instantly      │   height: 100dvh − 100 px
 ├─────────────────────────────┤   84 px from the bottom edge,
 │ ┌─────────────────┐         │   12 px at the sides
 │ │ Hello!          │         │
 │ └─────────────────┘         │
 │              ┌────────────┐ │
 │              │ Hi         │ │
 │              └────────────┘ │
 ├─────────────────────────────┤
 │ [ Type a message… ]    [+]> │
 ├─────────────────────────────┤
 │    Powered by Formula AI    │
 └─────────────────────────────┘
          ╭────────╮
          │   ✕    │
          ╰────────╯

#Pre-chat form

Shown if the channel has pre_chat_form enabled and the visitor has no session yet. Fields: name, email, phone; required sets which are required.

 ┌────────────────────────────────┐
 │ ◯  Channel name             ✕  │
 ├────────────────────────────────┤
 │             (◯◯)               │
 │        Start a conversation    │
 │ Fill in the details below to   │
 │ begin.                         │
 │                                │
 │ Name *                         │
 │ [____________________________] │
 │ Email *                        │
 │ [____________________________] │
 │ Phone                          │
 │ [____________________________] │
 │                                │
 │ [         Start chat         ] │
 └────────────────────────────────┘

The server uses only the name (sender_name) from the form. The email and phone are sent but not read; see the known limitation.

#Consent bar

Shown above the input field if the tenant set consent_text. Until the checkbox is ticked, the message is not sent.

 ├────────────────────────────────┤
 │ ☐ I agree to the terms of      │
 │   the offer. Open the offer    │   link from consent_url
 │   Tick the consent to          │   (if set)
 │   write.                       │
 ├────────────────────────────────┤
 │ [ Type a message…       ] [+] > │

#Typing indicator

 │ ◌ ● ● ●                        │   while the AI prepares a reply (a bubble with three dots)
 │ ◯ ● ● ●  Anna is typing…       │   an operator is typing: avatar and name

#Operator with an avatar

After an operator joins, the header shows their name, and below the header there is a bar "You are talking with …".

 ┌────────────────────────────────┐
 │ ◯  Anna                     ✕  │   the operator's name instead of the channel name
 │    ● online                    │
 ├────────────────────────────────┤
 │ (◯) You are talking with Anna  │   bar with a 24 px avatar
 ├────────────────────────────────┤
 │  Anna                          │   label above the operator's message
 │ (◯) ┌──────────────────────┐   │   26 px avatar next to the bubble
 │     │ Of course, I'll tell │   │
 │     └──────────────────────┘   │

#Ready-made blocks

In all blocks, replace 00000000-0000-4000-8000-000000000000 with your channel ID, and formula-cream.pro with your cell's domain (wfacademy.org for EN, wfacademy.id for ID). Files to copy are in examples/.

#Block 1. Floating button

Status: Available. File: examples/floating-button.html.

The standard connection: a round button in the bottom-right corner.

<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  async></script>

For the mockup, see the button and the window.

If the tag loads synchronously (without async), the widget starts after DOMContentLoaded; with async, right after the script loads.

#Block 2. Button on the left with a label

Status: Available.

<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  data-position="bottom-left"
  data-theme="dark"
  data-bubble-text="Need help?"
  async></script>

 ┌───────────────────────────────────────────┐
 │  page                                     │
 │                                           │
 │                                           │
 │  Need help?                               │
 │ ┌──────────────┐                          │
 │ └──▽───────────┘                          │
 │ ╭────────╮                                │
 │ │  ◯◯    │                                │
 │ ╰────────╯                                │
 └───────────────────────────────────────────┘

The equivalent through the global object:

<script>
  window.SapportWidget = {
    channelId: '00000000-0000-4000-8000-000000000000',
    position: 'bottom-left',
    theme: 'dark',
    bubbleText: 'Need help?'
  };
</script>
<script src="https://formula-cream.pro/widget.js" async></script>

#Block 3. Delayed start

Status: Available.

The button appears after the given number of seconds. Until then, the script draws nothing and does not contact the platform.

<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  data-bubble-text="Questions about the course?"
  data-delay="15"
  async></script>

Fifteen seconds after the script loads, the widget requests the channel settings and draws the button. The window does not open by itself: automatic opening will arrive in v2 (data-open="after:N", Planned).

#Block 4. Product or course page context

Status: Available. File: examples/product-page-context.html.

The widget passes the page address and title by itself. Set the entity type and ID (course, product, article) with the window.sapportPage object before the chat is first opened. To be sure the value is ready, set it before the widget tag.

<script>
  window.sapportPage = { type: 'course', id: 'hydrolat-basics' };
</script>
<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  async></script>

What the model receives (in the prompt, as browser data, not as instructions):

Visitor's current page: https://shop.example.com/courses/hydrolat-basics · "[course #hydrolat-basics] Hydrolat Basics"

The context is read once, when the window is first opened. Navigating to another page without a reload (an SPA) does not update the context; Sapport.setPage() from the JS API (Planned) is intended for that. More: Page, source, and UTM.

The Bitrix and WordPress modules output window.sapportPage themselves.

#Block 5. Cookie consent through the loader

Status: Available. File: examples/consent-banner.html.

Suited to a site bound to Sapport: the loader attaches the chat, the counter, and behavior collection, and itself waits for the visitor's consent. The chat channel is set by the site settings (chat, chat_channel_id), so the tag has no data-channel.

<!-- 1. Consent queue stub: BEFORE the loader -->
<script>
  window.sapport = window.sapport || {
    q: [],
    consent: function (v) { this.q.push(['consent', !!v]); }
  };
</script>

<!-- 2. The cell loader. k is the site's public key (not a secret) -->
<script async src="https://formula-cream.pro/api/v1/connector/loader.js?k=0123456789abcdef0123456789abcdef"></script>

<!-- 3. Your cookie banner calls consent -->
<script>
  document.getElementById('cookie-accept').addEventListener('click', function () {
    window.sapport.consent(true);
  });
  document.getElementById('cookie-decline').addEventListener('click', function () {
    window.sapport.consent(false);
  });
</script>

 ┌─────────────────────────────────────────────────────┐
 │ We use cookies to understand where visitors come    │
 │ from and to offer suggestions in the chat.          │
 │                                                     │
 │            [ Accept ]    [ Decline ]                │
 └─────────────────────────────────────────────────────┘

As an event: window.dispatchEvent(new CustomEvent('sapport:consent', { detail: true })); the form { granted: true } is also accepted. consent(false) returns to the minimal-context mode.

Consent in the chat is separate: it is not a cookie banner but consent to the tenant's terms (the consent bar).

A manual installation without the loader but with the same behavior:

<script>
  window.SapportWidget = {
    channelId: '00000000-0000-4000-8000-000000000000',
    consent: false,
    firstTouch: false
  };
  // after the visitor consents, on the same object:
  function onCookieAccepted() {
    window.SapportWidget.consent = true;
    window.SapportWidget.firstTouch = true;
  }
</script>
<script src="https://formula-cream.pro/widget.js" async></script>

The Bitrix/WordPress module installs this loader itself; you do not need to add the tag manually.

#Block 6. Inline block on a page

Status: Planned (data-mode="inline", data-container). There is no supported interim option; below is a workaround that works according to the code but is not a contract.

The target v2 markup (does not work today):

<div id="sapport-chat" style="height:560px"></div>
<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  data-mode="inline"
  data-container="#sapport-chat"
  async></script>

 ┌───────────────────────────────────────────────────────────┐
 │ Questions about the course?                               │
 │ ┌───────────────────────────────────────────────────────┐ │
 │ │ ◯ Channel name                                     ✕  │ │
 │ │ ┌───────────────────────┐                             │ │
 │ │ │ Hello!                │   the chat window inside    │ │
 │ │ └───────────────────────┘   the page text             │ │
 │ │ [ Type a message…                           ] [+] >   │ │
 │ └───────────────────────────────────────────────────────┘ │
 └───────────────────────────────────────────────────────────┘

Workaround today. The chat page opens as a regular iframe:

<iframe
  title="Chat"
  src="https://formula-cream.pro/widget/00000000-0000-4000-8000-000000000000?theme=light"
  style="width:100%;max-width:380px;height:560px;border:0"
  allow="clipboard-write"></iframe>

Limitations of the workaround:

• your site's domain must be allowed by the frame-ancestors header (above);
• the frame does not receive the page address, title, sapportPage, or first touch: only widget.js collects them. If you need the context, add it to the address manually: &page=<address>&title=<title> (values in encodeURIComponent); pt, pid, and ref work the same way;
• inside the frame, the "Close" (✕) button remains. It sends the parent a sapport:close message that nobody handles without widget.js;
• the frame does not stretch wider than 380 px or taller than 560 px by itself, and is centered;
• the workaround is not described as a public contract, and its behavior may change.

#Block 7. Your own "Ask a question" button

Status: Planned (data-launcher="none" and Sapport.open()). There is no supported way to open the window from your own code today.

The target v2 markup (does not work today):

<button id="ask">Ask a question</button>
<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  data-launcher="none"
  async></script>
<script>
  document.getElementById('ask').addEventListener('click', function () {
    window.Sapport.open();
  });
</script>

 ┌───────────────────────────────────────────────┐
 │ Course "Hydrolat Basics"                      │
 │ [ Enroll ]   [ Ask a question ]               │   your button
 │                        │                      │
 │                        ▼                      │
 │              ┌────────────────────┐           │
 │              │ chat window 380×560│           │
 │              └────────────────────┘           │
 └───────────────────────────────────────────────┘

What you can do today.

1. Use the standard floating button (blocks 1 to 3) and label it with data-bubble-text="Ask a question".
2. For an "Ask a question" link, open the chat page in your own window or in a pop-up iframe (the workaround from block 6).
3. Click the standard button programmatically (document.querySelector('.sapport-bubble').click()). This is not recommended: the internal sapport-* class names are not a contract and may change without notice.

#Errors and diagnostics

In the browser's Network tab, look for the requests widget.js, /api/widget/init, and, after opening, /widget/<channel_id>.

#Known limitations

These items reflect gaps between expectation and behavior; the wording is neutral, and the source is the code as of 11 Oct 2026.

The numbering matches the design's list of discrepancies.

#Notes

• Sizes: the button is 60×60 px; the window is 380×560 px; at widths ≤ 440 px, the window takes almost the whole screen.
• Referrer policy. The frame's messages (sapport:new-message, sapport:close) go to the page origin. The frame determines the origin from ancestorOrigins (Chrome, Safari) or from document.referrer (Firefox). If your site sends Referrer-Policy: no-referrer, the unread counter on the button will not work, but the chat itself keeps working.
• Hiding on pages. Load the tag only on the pages you need (for example, not on the checkout page): there is no "do not show here" parameter.
• Cache. The widget.js script and the init response are not versioned by address; updates are picked up under the browser's ordinary caching rules.
• Label in the window. The bottom of the window shows the label "Powered by Formula AI"; there is no parameter in the code to turn it off.
• Changelog: 90-changelog.

#Open questions

• Where in the dashboard the tenant manages the domains list that determines the domains allowed to frame the chat: this could not be confirmed in the interface. For bound sites, the domain is added automatically.
• Where in the interface the site's public key k comes from for a manual loader installation (it is issued at binding and is not shown in the dashboard).
• The defaults of data-open and data-locale in v2, and whether the listed parameters are needed in the first version, are not fixed.
• Whether a parameter is needed to turn off the "Powered by Formula AI" label (not described in the design).