Developer

Complete widget documentation

The widget automatically loads its configuration from the AISA APIs. The data-* attributes almost always work as targeted overrides: use them only when you want to force a behavior at the page level.

Config precedence

Actual resolution order

Inline override

Every data-* attribute present in the script has top priority and forces only that single option.

Remote configuration

If an override isn't present, the widget uses the settings fetched from the AISA APIs via API URL and agent ID.

Internal defaults

Only if the remote value is missing too does the widget apply its own local fallback documented in the README.

What's actually required

For a real bootstrap, all you need is data-api-url and data-agent-id. Add data-identity and data-context only if you want to pass user data or runtime context to the backend.

data-api-url

Endpoint of your assistant instance. Without it, the widget can't fetch the remote config.

data-agent-id

Identifier of the agent used to load settings and route the conversation to the correct assistant.

data-identity

Optional. String or JSON with data such as name, email and phone, sent to the backend via a dedicated identity event.

data-context

Optional. Extra string to give the session context, useful for page, funnel, campaign or use case.

Minimal snippet

Recommended installation

Production

This is the setup we recommend in most cases: the script identifies environment and agent, then fetches the rest from the backend. Identity and context are optional.

<script
  src="https://cdn.jsdelivr.net/gh/Autocust/ai-chat-widget@latest/dist/chat-widget.min.js"
  data-api-url="https://assistant.aisalesassistant.it"
  data-agent-id="AGENT_ID"
  data-identity='{"email":"[email protected]"}'
  data-context="Landing pricing enterprise"
></script>

Snippet with overrides

When to force local options

Exceptions

This example shows a few inline customizations. They are all optional and override the corresponding remote value.

<script
  src="https://cdn.jsdelivr.net/gh/Autocust/ai-chat-widget@latest/dist/chat-widget.min.js"
  data-api-url="https://assistant.aisalesassistant.it"
  data-agent-id="AGENT_ID"
  data-theme="dark"
  data-position="bottom-right"
  data-predefined-questions='["Prezzi","Onboarding","Integrazioni"]'
  data-button-overlay-text="Serve una mano?"
  data-start-open="false"
  data-width="360px"
></script>

Reference

Supported attributes

Every attribute below is available in the widget. If you don't set it inline, the widget uses the agent's remote configuration first and then, only if needed, its own internal default.

Bootstrap, identity and context

Parameters that connect the widget to the backend or change its operating mode.

data-api-urlRequired

URL of the API that powers the widget. In demo mode it's ignored.

data-agent-idRequired

Agent ID used for backend identification and API calls. In demo mode it's ignored.

data-identityDefault: null

String or JSON payload with data such as name, email and phone, sent to the backend with a dedicated event.

data-contextDefault: null

Additional context for the assistant, useful to personalize the runtime conversation.

data-cmsDefault: ''

CMS type (for example prestashop or woocommerce). It can enable feature variants such as add to cart in product carousels.

data-is-demoDefault: false

Starts a demo conversation with predefined content, disabling the real connection and message sending.

When true, API URL, agent ID and persistent sessions are not used.

Copy, onboarding and chat content

Text, initial suggestions and micro-copy shown to the user.

data-title

Widget title. If absent, the default localized title or the remote one is used.

data-initial-message

Initial message shown on opening. In demo mode it's also the first message of the conversation.

data-predefined-questions

JSON array of clickable questions. It shows only until the user sends the first message.

data-cta-text

Base text of the CTA button below messages. It can be overridden by the bot or by the demo content.

data-footer-text

Custom text in the footer below the input field. If absent, it uses the default localized message.

data-show-powered-byDefault: true

Set to false to hide the "Powered by Autocust" line in the widget footer.

Trigger, session and user behavior

Controls for chat start, persistence and initial interactions.

data-button-iconDefault: 💬

Icon of the floating button. It accepts text, emoji, image URL or SVG markup.

data-button-overlay-text

Text of the bubble next to the button on page load, designed to grab attention before it fades away.

data-button-overlay-delayDefault: 5000

Duration in milliseconds of the overlay bubble before the fade-out.

data-start-openDefault: false

If true, the widget starts already open when the page loads.

data-persistent-sessionDefault: false

If true, it keeps the history across sessions and subsequent visits.

Ignored in demo mode.

data-session-expirationDefault: 24

Duration in hours of the persistent session. Once the TTL is exceeded, the history is cleared.

Ignored in demo mode.

data-closableDefault: true

If false, it hides the close button in the header and prevents closing the widget once open.

Navigation, layout and viewport

Link handling, positioning and container dimensions.

data-open-in-new-tabDefault: true

Determines whether links generated by the widget are opened in a new tab.

data-enable-utmDefault: true

If true, it adds UTM parameters to product links. Set false to disable them.

data-positionDefault: bottom-right

Widget position among top-left, top-right, bottom-left and bottom-right.

Ignored if data-full-screen is true.

data-full-screenDefault: false

If true, the widget takes up the whole viewport and ignores the position.

data-widthDefault: 340px

Width of the chat container in non-fullscreen mode.

data-heightDefault: 485px

Height of the chat container in non-fullscreen mode.

data-z-indexDefault: 1000

Stacking order of the non-fullscreen widget relative to the other layers of the page.

Theme and palette

Visual overrides for the theme and individual widget elements.

data-themeDefault: light

Global widget theme: light or dark.

data-user-message-bg-colorDefault: #e0e0e0

Background color of user messages.

data-user-message-text-colorDefault: #000000

Text color in user messages.

data-assistant-message-bg-colorDefault: #f8f8f8

Background color of assistant messages.

data-assistant-message-text-colorDefault: #000000

Text color in assistant messages.

data-chat-button-bg-colorDefault: #000000

Background color of the floating open button.

data-chat-button-text-colorDefault: #ffffff

Color of the text or icon in the floating button.

data-cta-button-bg-colorDefault: #f8f8f8

Background of the CTA buttons inside the conversation.

data-cta-button-text-colorDefault: #000000

Text color of the CTA buttons inside the conversation.

data-cta-button-hover-bg-color

Hover background of the CTA buttons, taking precedence over the theme.

data-cta-button-hover-text-color

Hover text color of the CTA buttons, taking precedence over the theme.

data-header-bg-color

Background color of the widget header, overrides the theme.

data-header-text-color

Text color of the title and buttons in the widget header.

Advanced override

The last level of customization when the standard options aren't enough.

data-custom-cssDefault: null

Raw CSS string injected into the widget's Shadow DOM. Useful only for advanced, controlled styling.

Internal classes, ids and markup aren't stable: this override can break with every release and must be tested.

Placement

Supported positions

data-position accepts only these values. If the value is not valid, the widget falls back to bottom-right. In fullscreen the position is ignored.

top-left

Anchors the widget in the top-left corner.

top-right

Anchors the widget in the top-right corner.

bottom-left

Anchors the widget in the bottom-left corner.

bottom-right

Anchors the widget in the bottom-right corner. It's the default fallback.

JavaScript API

Programmatic control

The widget exposes window.autocustChatWidget and listens for the autocust:ask.

Open the widget

Opens the chat programmatically, useful for external CTAs or custom flows.

window.autocustChatWidget.open()

Close the widget

Closes the chat. If data-closable="false" the call becomes a no-op.

window.autocustChatWidget.close()

Prefill the question

Inserts the text into the composer and, optionally, sends it right away.

window.autocustChatWidget.ask('Spedite all'estero?')
window.autocustChatWidget.ask('Spedite all'estero?', { sendImmediately: true })

window.dispatchEvent(
  new CustomEvent('autocust:ask', {
    detail: {
      question: 'Qual è la vostra policy resi?',
      sendImmediately: true,
    },
  })
)

Analytics

Events emitted by the widget

All events are CustomEvent emitted on window, with the data in event.detail.

autocust:chatOpened

Fires when the widget is opened by a user click, the JS API or an automatic opening.

Payload

No required payload: it mainly serves to measure engagement and trigger efficacy.

autocust:productClicked

Fires when a user interacts with a product in the carousel, both for view and for add to cart.

Payload

event.detail.product.id
event.detail.product.name
event.detail.product.price
event.detail.product.url
event.detail.action = 'view' or 'add_to_cart'

autocust:ctaClicked

Fires when a user clicks a CTA button below a message.

Payload

event.detail.url
event.detail.ctaText

Tag Manager

GTM / dataLayer example

You can intercept the widget's events and relay them to your analytics stack without touching the component's internal code.

window.addEventListener('autocust:chatOpened', () => {
  window.dataLayer = window.dataLayer || []
  window.dataLayer.push({ event: 'autocust_chat_opened' })
})

window.addEventListener('autocust:productClicked', (event) => {
  window.dataLayer = window.dataLayer || []
  window.dataLayer.push({
    event: 'autocust_product_clicked',
    product_id: event.detail.product.id,
    product_name: event.detail.product.name,
    interaction_type: event.detail.action,
  })
})

window.addEventListener('autocust:ctaClicked', (event) => {
  window.dataLayer = window.dataLayer || []
  window.dataLayer.push({
    event: 'autocust_cta_clicked',
    cta_text: event.detail.ctaText,
    destination_url: event.detail.url,
  })
})

Security

Content Security Policy

If your site uses CSP, allow at least the domains needed to download the script and contact your environment's API.

script-src: https://cdn.jsdelivr.net
connect-src: the host passed in data-api-url

Advanced styling

Using data-custom-css

The data-custom-css attribute injects CSS into the widget's Shadow DOM. It's powerful, but should be treated as an escape hatch.

Internal DOM, classes and ids are not a stable API and can change in every release.
Anyone using custom CSS must retest the widget after every update.
In production it's best to pin a tested version of the script instead of always using @latest.

Inline override

Remote configuration

Internal defaults

What's actually required

Recommended installation

When to force local options

Supported attributes

Bootstrap, identity and context

Copy, onboarding and chat content

Trigger, session and user behavior

Navigation, layout and viewport

Theme and palette

Advanced override

Supported positions

Programmatic control

Events emitted by the widget

GTM / dataLayer example

Content Security Policy

Using data-custom-css

Want to see it on your site?