Integration guide

What you need to know

Bambuser Chat embeds easily on any website with a lightweight JavaScript code snippet. It will only appear after important website content because it loads asynchronously, and it won't interfere with any other on-page content, code, or SEO because it's in an iframe. It's also extendible so you can listen to and interact with it using the Bambuser Chat API for more advanced setups.

Set up Bambuser Chat

1. Add the Bambuser Chat tag

Ahead of implementation, we will send you two App IDs for each website region. In each case, one App ID is for your Staging environment and one for your Production environment.

1. Staging App ID - add this to your Staging website pre-production or any other environment for testing which is not public and best reflects the live environment.
2. Production App ID - add this to your live production environment. Bambuser will need to complete your production website's configuration and confirm that everything is set up correctly before the JavaScript is deployed. This step will usually take place at the end of the integration process just before going live.

Default

The default integration is to include the following script tags on your website. It will automatically initiate the messenger widget for your customers when your agents are online in the store app.

<script>
  window.HeroWebPluginSettings = { applicationId: "Your_App_ID" };
  (function (i, a, m, h, e, r, o) {
    i.HeroObject = e;
    (i[e] =
      i[e] ||
      function () {
        (i[e].q = i[e].q || []).push(arguments);
      }),
      (i[e].l = 1 * new Date());
    (r = a.createElement(m)), (o = a.getElementsByTagName(m)[0]);
    r.async = 1;
    r.src = h;
    o.parentNode.insertBefore(r, o);
  })(window, document, "script", "https://cdn.usehero.com/loader.js", "hero");
</script>

GTM

This is the Plug-and-Play solution that gets you started with receiving calls within just a few minutes.

How to install

1. Add a new tag
2. Edit the tag configuration
3. Add the application id in the configuration
4. Select a trigger of when the widget should be shown
5. Done!

You can now preview and test on your site before publishing for your customers

Read more

You can read the full guide of GTM setup here.

Now the Chat will be visible on your website, if not please consult the Chat is Not Appearing on My Website troubleshooting document.

hint

After adding the Bambuser Chat code to the website please activate the Inspector Tool in order to spot the any issues that might appear.

2. Track Shopper Events

Bambuser Chat can empower store team members with context on how shoppers are behaving on your website to support their conversations. For this to work, you will need to set up Bambuser Chat to track the specific actions shoppers take on your website.

required

Make sure 'Product view' and 'Purchase' Shopper Event tracking is set up at launch. Bambuser Chat will not work properly without these events in place.

Product View

The Product View Shopper Event gives store experts who are about to chat to shoppers, context on which products they have been viewing.

Product View fields:

Name	Value	Type	Required	Description
type	ecommerce:detail	text	yes	The type of tracking
products	See example	array	yes	The product details

<script>
  hero("track", {
    type: "ecommerce:detail",
    products: [
      {
        id: "314-7216-102",
        name: "Tennis Shoe Classic - Size 10",
        image: "https://example.com/images/314-7216-102.jpg",
        price: 70.99,
        currency: "USD",
        brand: "Plausible Co.",
        category: "Footwear > Sports > Tennis",
        location: "https://example.com/products/314-7216",
      },
    ],
  });
</script>

Purchase

The Purchase Shopper Event gives store experts who are about to chat to shoppers, context on which products they have recently purchased.

Purchase fields:

Name	Value	Type	Required	Description
type	ecommerce:purchase	text	yes	The type of tracking
purchase	See example	object	yes	The purchase details
products	See example	array	yes	The product details

<script>
  hero("track", {
    type: "ecommerce:purchase",
    purchase: {
      id: "abcd",
      subtotal: 70.99,
      currency: "USD",
      total: 74.98,
      tax: 14.2,
      shippingCost: 3.99,
      shippingMethod: "Store pickup",
      coupon: "SUMMER_SALE",
    },
    products: [
      {
        id: "314-7216-102",
        name: "Tennis Shoe Classic - Size 10",
        image: "https://example.com/images/314-7216-102.jpg",
        price: 70.99,
        currency: "USD",
        quantity: 1,
        brand: "Plausible Co.",
        category: "Footwear > Sports > Tennis",
        location: "https://example.com/products/314-7216",
      },
    ],
  });
</script>

Basket Add

The Basket add Shopper Event gives store experts who are about to chat to shoppers context on which products are in the shopper's basket.

Basket add fields:

Name	Value	Type	Required	Description
type	ecommerce:add	text	yes	The type of tracking
products	See example	array	yes	The product details

<script>
  hero("track", {
    type: "ecommerce:add",
    products: [
      {
        id: "314-7216-102",
        quantity: 1,
        basketQuantity: 1,
        name: "Tennis Shoe Classic - Size 10",
        image: "https://example.com/images/314-7216-102.jpg",
        price: 70.99,
        currency: "USD",
        brand: "Plausible Co.",
        category: "Footwear > Sports > Tennis",
        location: "https://example.com/products/314-7216",
      },
    ],
  });
</script>

Basket Remove

The basket remove Shopper Event gives store experts who are about to chat to shoppers, context on which products have been removed from a shopper's basket.

Basket remove fields:

Name	Value	Type	Required	Description
type	ecommerce:remove	text	yes	The type of tracking
products	See example	array	yes	The product details

<script>
  hero("track", {
    type: "ecommerce:remove",
    products: [
      {
        id: "314-7216-102",
        quantity: 1,
        basketQuantity: 0,
        name: "Tennis Shoe Classic - Size 10",
        image: "https://example.com/images/314-7216-102.jpg",
        price: 70.99,
        currency: "USD",
        brand: "Plausible Co.",
        category: "Footwear > Sports > Tennis",
        location: "https://example.com/products/314-7216",
      },
    ],
  });
</script>

Category View

The Category view Shopper Event gives store experts who are about to chat to shoppers, context on which product categories they have been viewing on your website.

Category view fields:

Name	Value	Type	Required	Description
type	event	text	yes	The type of tracking
action	category-view	text	yes	The type of interaction
value	-	text	yes	The name of the category
location	-	text	yes	URL of the category tracked

<script>
  hero("track", {
    type: "event",
    action: "category-view",
    value: "Accessories",
    location: "https://example.com/categories/accessories",
  });
</script>

Search

The Search Shopper Event gives store experts who are about to chat with shoppers, context on which products shoppers have recently searched for on your website.

Search event fields:

Name	Value	Type	Required	Description
type	event	text	yes	The type of tracking
action	search	text	yes	The type of interaction
value	-	text	yes	The value being searched
location	-	text	yes	URL of the page being tracked

<script>
  hero("track", {
    type: "event",
    action: "search",
    value: "bedding sets",
    location: "https://example.com",
  });
</script>

eCommerce Subfields are the mandatory items you will need to provide Bambuser Chat with to ensure Shopper Events track all the key information.

note

Please note if all recommended fields have not been included during set up, Bambuser Chat will fall back on the data provided in your Product Feed.

Purchase array item subfields

Name	Type	Required	Description
id	text	yes	The purchase/order ID
subtotal	number	yes	The total price for all products in a purchase
currency	text	yes	The purchase currency (ISO 4217)
total	number	no	The overall adjusted total calculated price for all of the product a purchase
tax	number	no	The purchase tax
shippingCost	number	no	The purchase shipping cost
shippingMethod	text	no	The purchase shipping method
coupon	text	no	The purchase coupon

Product array item subfields

Name	Type	Required	Description
id	text	yes	The unique product or SKU (must exactly match one product in the Product Feed)
quantity	number	yes*	The product quantity
basketQuantity	number	yes**	The new basket quantity for this product
name	number	recommended	The product name
image	number	recommended	The product image URL
price	number	recommended	The product price
currency	text	recommended	The product currency (ISO 4217)
location	text	recommended	The product URL
brand	text	no	The product brand
category	text	no	Must match the category hierarchy for this product as defined in the Product Feed E.g. Menswear > Shoes > Brogue

3. Integrate Product Feed

With the Bambuser Chat, experts can recommend products to website visitors during a chat to drive sales. These product recommendations are sent as Product Cards, which a store team member can send to a shopper during a chat.

How to integrate your Product Feed with the Bambuser Chat

For this to work, the Bambuser Chat needs access to a Product Feed in CSV format.

To share your Product Feed with Bambuser Chat, you can share a publicly accessible URL or an SFTP for Bambuser Chat to fetch it from - or we can provide an SFTP for you to put it in.

required

Please ensure each product entry contains:

• Product SKU Code
• Product Title
• Product Image(s) URL
• Product URL
• Price
• Description
• Currency
• Category
• Stock Quantity

optional

We also recommend you include other fields that contain terms your associates may use to describe or search for a product such as:

• Sale Price
• Size Variant
• Color Variant
• Additional image URLs
• Style Code or Master SKU (i.e. to group SKUs)
• Brand Name
• Barcode Number

Bambuser Chat indexes the Product Feed at least once per day so that the products available for associates to share in chats with shoppers are representative of the latest online product catalogue. Bambuser Chat can refresh the product feed more frequently if necessary.

Stock Changes

We recommend ensuring all products remain in a product feed, whether they are in stock or out of stock. Simply declare the stock quantity as 0 when out of stock, and we'll do the rest.

This ensures Bambuser Chat still has access to all products in your inventory, and experts can recommend these products.

Creating Your Product Feed

To ensure a seamless handover and quick setup, we recommend sending Bambuser Chat your Product Feed in an easy-to-handle format.

Below we've assembled an example table of property names that you can use when setting up your Product Feed to send to Bambuser Chat. If using these names is not possible, the Bambuser Chat team can map your feed as part of the launch process.

Property	Type	Required	Description	Example
sku_code	string	yes	The unique identifier for a specific product.	314-7216-102
group_sku	string	no	The identifier for a group of products: each variation i.e. size / colour or fabric will have a unique identifier it's sku_code. The group_sku is used to ensure product variations appear under the same product in the app.	314-7216
title	string	yes	A product’s title.	Relaxed Fit T-shirt
description	string	yes	Description of the product with all markdown or HTML removed.	Our classic 100% cotton relaxed fit shirt
currency	string	yes	The ISO-4217 currency code for this product. This will generally be the same for all products in a feed.	USD
normal_price	number	yes	How much the product usually costs.	99.99
sale_price	number	no	If the product is on sale, how much it costs while on sale.	79.99
stock_quantity	number	yes	How many units of this product are currently in stock. You can supply a 1 / 0 for in and out of stock, respectively.	34
url	URL	yes	A link to the product’s product detail page.	https://example.c/products/01234ADefGH
categories	string	yes	The category breadcrumb trail for this product, as a delimited string.	Ladies fashion > Jeans & Trouser > Skinny jeans
image_url	URL	yes	A link to the main image for this product.	https://example.c/products/01234ADefGH/images/01.jpg
alternate_image	URL	no	One or more links to images for this product. CSV If you have multiple additional images use columns with an incremented number e.g. alternate_image_1 alternate_image_2 XML Wrap each URL in the same tag e.g. <alternate_image>URL_1</alternate_image><alternate_image>URL_N</alternate_image>	https://example.c/products/01234ADefGH/images/02.jpg
gender	string	no	If you have gender specific products, you can supply a value for gender.	unisex
size	string	no	Include for products that have size variations.	XX-Small
color	string	no	Include for products that have colour variations.	Navy
fit	string	no	Include for products that have fit variations.	Relaxed
fabric	string	no	Include for products that have fabric information.	98% Cotton, 2% Elastane
barcode	string	no	Include if you need to show barcode information.	0100234567890
collar	string	no	Include for products that have collar variations.	Point
feature	string	no	Include for products that have feature information.	Hidden Pocket

Representing discounted/sale prices

If a product is currently on sale, we can display it in the Bambuser Chat for Product Experts (not to shoppers) with "strikethrough" pricing. If you provide a sales_price value for a product, we will display the normal_price crossed-out, and the sale_price in its place.

For example:

"normal_price": 449.00,
"sale_price": 369.00,
"currency": "USD",

Upload the Product Feed in VS Dashboard

The Product Feed ingestion tool can be accesed in the VS Dashboard under Settings tab.

Get notified of any issues with your Product Feed.

Bambuser Chat indexes the Product Feed at least once a day to ensure your product experts have access to your latest online offering. If there are any issues, which means indexing fails, your designated contacts will be notied by email.

Proactively resolve product feed issues.

The email will contain a CSV file containing clear details of what the errors are to make it quick and simple for you to resolve these. In this section, you'll find details about what each error means, and how you'll be able to resolve them.

Happy Product Feed, high performing product experts.

Being able to quickly resolve any issues helps keep your product feed up-to-date. That in turn helps you ensure your product experts have access to the latest information on pricing, availability and assortment to continue making recommendations and driving sales.

Troubleshooting

• Chat Not Appearing on My Website
• Sales are Not Attributed
• Product Feed validation errors

Chat FAQ

Which languages are supported?

The Bambuser Chat plugin and Bambuser Chat mobile app are localized into the following languages:

• English (US)
• Chinese (simplified)
• Chinese (traditional)
• Danish
• Dutch
• Finnish
• French
• German
• Italian
• Japanese
• Korean
• Norwegian
• Polish
• Portuguese
• Spanish
• Swedish

The language shown will depend on the languages selected in the shopper's browser settings for the Plugin or the product expert's mobile device for the App.

How big is the Javascript file and when is it loaded?

The Bambuser Chat JavaScript is designed to offer maximum functionality with minimum impact on your overall site performance.

The Chat JavaScript loads asynchronously for optimal performance, ensuring all priority website content is loaded before the Chat JavaScript starts to load. It also loads only the parts that are needed depending on the user interaction. The following details what is loaded in each scenario.

The Loader is a JavaScript file which handles the loading of theChat launcher button and messenger. It's as small as possible whilst still allowing us to understand display rules, determine sales attribution and understand the shopper journey to inform the product expert. On a page where Chat won't show to a shopper, such as a checkout page, this is all that loads.

Total load: 27 KB

On pages where the customer can interact with the Chat, there are three exclusive scenarios which determine the plugin size: The Launcher and Launcher Bubble loads but the user does not interact with the plugin.

Total load: 275 KB

The Launcher is interacted with to open the Messenger.

Total load: 340 KB

The Launcher is interacted with to open the Messenger and the customer starts a conversation.

Total load: 445 KB

There are a number of other minor asynchronous loads beyond this, but these are used by a minimum number of users for specific functions around map and country selector functionality. These are kept to a minimum.

We are continually committed to reducing the file size where possible.