Control the chat from your page

After the install snippets run window.amioWebchat.init({...}), your page controls the chat through the same window.amioWebchat object. Call these functions only after init.

Functions

Function	What it does
`open()`	Opens the chat window.
`close()`	Closes the chat window.
`sendText(text)`	Sends `text` as the visitor’s message, for example from a “Ask about this product” button. Returns a promise. It rejects if `text` is empty, if `init` was not called, or if the message is not sent within 30 seconds.
`restart()`	Opens the chat and starts a new conversation. The current conversation is cleared and any `externalContactId` from `init` is dropped for the new session.
`triggerEvent(eventId)`	Fires a custom event in the bot. The admin’s Copy code button on an event gives you this call with the right ID.
`setMetadata({...})`	Attaches your own data (for example a customer tier) to the visitor’s messages. Takes a plain object.
`setBrowserUrl(url)`	Shortcut for `setMetadata({ browserUrl: url })`. The widget also updates the page URL on its own when a single-page site changes route, so you rarely need to call this.
`getAmioContactId()`	Returns a promise with the Amio contact ID of the current visitor. Use it to match the chat with your own records.
`onUserEvent(callback)`	Registers one function that receives visitor events (below). A second call replaces the first.
`onCallbackButtonPressed(callback)`	Registers a function called with the payload when the visitor clicks a bot button of type callback.
`setCart(cart)`	Tells the chat what is in the shopper’s cart, see Shopping cart.
`onAddToCart(handler)`	Registers the function that adds a product to your real cart, see Shopping cart.
`destroy()`	Removes the chat from the page. Call `init` again to bring it back.

window.amioWebchat.sendText('Which shoes fit trail running?')
  .catch((err) => console.warn('Chat message not sent', err))

window.amioWebchat.setMetadata({ customerTier: 'gold' })

Shopping cart

Two functions connect the chat to your shop’s cart: setCart shows the cart in the chat and lets the bot’s AI prompts read it as ${context.cart}, and onAddToCart lets shoppers add recommended products from the chat.

To set it up:

Check your product feed: every variant on its own row, with item_group_id, g:size and g:color. See Add to cart from the chat.
Call setCart on every page and after every cart change.
Register an onAddToCart handler that adds the variant to your real cart.
Put ${context.cart} in the AI prompts that should know about the cart, and optionally make the bot react to cart changes with the Cart Updated event.

`setCart(cart)`

Call after init and every time the cart changes. Calls before the chat is ready are held, and only the latest cart is delivered.

window.amioWebchat.setCart({
  currency: 'CZK',                 // ISO 4217
  items: [
    {
      variantId: '123456',         // the variant's ID from the product feed (g:id in a Google feed)
      name: 'Nike Air Max 90',
      options: { size: '42', color: 'black' },   // optional, free-form
      quantity: 1,
      unitPrice: 2990,             // numbers in major units (2990 = 2 990 Kč, 19.99 = 19.99 EUR)
      total: 2990
    }
  ],
  subtotal: 2990,                  // items only
  shipping: 99,                    // null = not known yet
  customs: 0,                      // duties (GB/UA/NO); null = n/a or not known
  total: 3089,                     // what the shopper pays
  freeShippingThreshold: 1500,     // optional; null/absent = no free shipping
  cartUrl: 'https://shop.example/cart'
})

Required: currency, items (may be empty), total. Everything else is optional. A cart without an items array, a string currency or a finite numeric total is ignored, with a warning in the browser console.
Unknown extra keys are kept and passed through to the bot (for example coupon or loyaltyPoints).
The bot sees the cart only where an AI prompt references it: ${context.cart} is replaced with the whole cart as JSON, and ${context.previousCart} with the cart before the last change. Nothing is added to prompts automatically, so a field such as freeShippingThreshold is used only when a prompt with ${context.cart} asks for it. See the Cart Updated event for an example prompt.
Keep it compact: every prompt that references ${context.cart} gets the whole object. No descriptions, no image URLs. A cart larger than 8 KB of JSON is ignored, with a warning in the browser console.
Once a cart with at least one item is set, the chat header shows a pill with the formatted total and the number of items. It opens cartUrl (http or https only) in the top window. The pill is hidden while items is empty.
The pill follows the header colours. To change it, pass themeOverride: { header: { cartPill: { text, border, badgeBg, iconUrl } } } to init (all optional). iconUrl replaces the built-in cart icon with your own 20 × 20 px image; it is shown as is, so use one already in the header’s text colour.

`onAddToCart(handler)`

window.amioWebchat.onAddToCart(async ({ variantId, quantity }) => {
  // add to the real cart…
  return { ok: true, cart: currentCart }           // cart = same shape as setCart (recommended)
  // or
  return { ok: false, message: 'Velikost je vyprodaná' }  // shown under the button, already localised
})

There is a single handler. Registering it is what makes product cards show size and colour chips and an add-to-cart button. Without a handler, cards behave as before.
variantId is the ID of the picked variant, taken from your product feed (its item ID, g:id in a Google feed). If your cart expects another ID, see Add to cart from the chat.

What the shopper sees on a product card:

One row of chips per option, for example sizes and colours, each under the option’s name (Size, Colour). An option with more than 8 values, such as a full range of shoe sizes, is a dropdown instead. Values that do not combine with the current pick are faded (in a dropdown, marked as not available); picking one starts a new pick.
The price is the button: a cart icon with the price (and the original price, struck through, on sale items) takes the place of the card’s price line and sits at the right, beside the chips when they fit. Clicking it before every option is picked shakes the row that is missing and shows what to pick, for example Choose a size, for a moment.
While your handler runs, the button shows a spinner. On success it turns green with a check mark for a moment. On failure it shows your message (below).
When the cart from setCart holds this product (any of its variants, matched by variantId), the button turns light green and shows how many. Keep calling setCart after each change so the count stays right.
The card’s link button (such as View product) is not shown on cards with the add-to-cart button. Clicking the card anywhere outside the size and colour controls opens the product page.
quantity is always 1.
Keep message to one short sentence (about 60 characters) of plain text in the shopper’s language, and say what to do next, for example Size 42 is sold out, pick another size. It is shown in small red text under the button, two lines at most; longer text is cut off.
The handler may return a value or a promise. A throw, a malformed result, or no answer within 10 seconds counts as a failure and the shopper sees a generic, localised error.
A returned cart is treated exactly like setCart(cart). Calling both is fine.
Return the updated cart from the handler (or call setCart before the handler resolves), so the change counts as made from the chat. A cart that arrives only after the handler has resolved counts as a change on the page.

When the cart changes, the bot can react: see the Cart Updated event.

Visitor events

window.amioWebchat.onUserEvent((name, params) => {
  window.dataLayer?.push({ event: `amio_${name}`, ...params })
})

The callback gets the event name and, for some events, an object with details. The details differ by event.

Event	Fires when
`launcher_click_open`	the visitor opens the chat with the launcher button
`launcher_click_close`	the visitor closes the chat with the launcher button
`header_click_close`	the visitor closes the chat with the button in the chat header
`message_submit`	the visitor sends a message
`file_submit`	the visitor sends a file
`file_open`	the visitor opens a file from a message
`button_click`	the visitor clicks a button in a message
`quick_reply_click`	the visitor clicks a quick reply
`pop_up_click_open`	the visitor opens the chat from a pop-up message
`pop_up_click_close`	the visitor closes a pop-up message
`pop_up_button_click`	the visitor clicks a button in a pop-up message
`pop_up_quick_reply_click`	the visitor clicks a quick reply in a pop-up message
`call_operator`	the bot hands the chat over to a person. The chat shows a “connecting” screen. Details include `intent` and `context`
`products_displayed`	product recommendations from the bot arrive (see below)
`product_click`	the visitor opens a product card link
`link_click`	the visitor opens any other link in a bot or operator message

Example details for button_click:

{
  type: 'button',
  title: 'Visit Amio',
  payloadType: 'url',
  payload: 'https://amio.io',
  metadata: { browserUrl: 'https://clientWebsite.com' }
}

Product and link events

products_displayed, product_click and link_click are made for measuring how product recommendations perform. Their details use camelCase and always include:

sender: bot or operator
amioContactId: the visitor’s contact ID
metadata: the message metadata merged with what you passed to setMetadata() or setBrowserUrl(), so metadata.browserUrl is there when you set it
answerType: taken from the message metadata (answerType, answer_type or intent, in that order). Defaults to product_recommendation for product events and other for link_click

products_displayed fires once when a new product recommendation from the bot arrives, also while the chat is closed. It covers carousel, grid, rows and hero layouts. It does not fire for messages loaded from the conversation history. products is in display order:

{
  products: [
    { title: 'adidas Forum Low EUR 46', url: 'https://shop.example/product/1', id: 'feed-1' },
    { title: 'adidas Forum2000 EUR 44', url: 'https://shop.example/product/2' }
  ],
  answerType: 'product_recommendation',
  sender: 'bot',
  amioContactId: 'contact-123',
  metadata: { amio_bot: true, product_layout: 'carousel', browserUrl: 'https://shop.example/' }
}

product_click fires when the visitor opens a product card link. position starts at 1, in display order:

{
  title: 'adidas Forum2000 EUR 44',
  position: 2,
  url: 'https://shop.example/product/2',
  answerType: 'product_recommendation',
  sender: 'bot',
  amioContactId: 'contact-123',
  metadata: { amio_bot: true, product_layout: 'carousel', browserUrl: 'https://shop.example/' }
}

A product’s id is included only when the product in the bot’s message has one. It is never derived from the URL.

link_click fires when the visitor opens any other web link in a bot or operator message, including pop-up messages:

{
  url: 'https://shop.example/returns',
  answerType: 'returns',
  sender: 'operator',
  amioContactId: 'contact-123',
  metadata: { intent: 'returns', browserUrl: 'https://shop.example/' }
}