Skip to main content

Adding Maya to your website

This page is written for your web team or agency. It explains how to add Maya to your website — the popover chat widget, full-page chat, full-page search and quick search — and the extra controls you can use once Maya is on the page.

You need three values, which your Maya contact provides: your organisation key (KEY), your organisation identifier (SLUG), and the language Maya should use on the page (LANGUAGE, for example en, nl or fr). The Production snippets below are the ones to use on your live site; use the Staging ones only while testing against a staging environment.

Adding the chat widget​

  1. Load the following script on all pages. You could for example load it in the footer code ( if that loads on all pages ):

Staging

<script src="https://maya-b2b.s3.eu-central-1.amazonaws.com/loaders/staging.js"></script>

Production

<script src="https://d3gievmnjacng1.cloudfront.net/loaders/prod.js"></script>
  1. Add the following div on the page where you want to show the chat in full page mode. Make sure to add in a container with full screen width and full screen height (excluding the height of the header).
 <div     
   id="maya-b2b-full-page"      
   data-organization-key="KEY"      
   data-organization-slug="SLUG"      
   data-language="LANGUAGE"      
   data-widget-mode="full-page">
</div>
  1. Add the following div on existing pages where you want to show the Maya popover chat widget:
<div     
   id="maya-b2b-full-page"      
   data-organization-key="KEY"      
   data-organization-slug="SLUG"      
   data-language="LANGUAGE"      
   data-widget-mode="popover">
</div>

Notes​

  • Do not load multiple environment scripts on the same page as it’ll cause conflicts e.g. do not load staging and prod environment scripts on the same page.
  • The div maya-b2b-full-page should be added in html before including/loading the loader scripts either staging/production.
  • The div for the popover widget should be visible on top of all other content in html. Best approach would be to add it directly inside <body> tag of the html on the pages where the popover widget is required.

Loading the script after the page has fully loaded​

In order to avoid any impact on your PageSpeed Insights / Core Web Vitals scores, we'd suggest not adding the loader <script> tag directly in your HTML. Instead, you could inject it after the browser's load event fires, so that Maya only begins loading once your page has fully loaded. This way, the widget should have no impact on your page speed scores.

Please make sure the maya-b2b-full-page div is already present in the HTML — it typically will be, since the page is fully rendered by the time the load event fires.

This also guarantees the loader only runs once the div is already in the HTML.

Production

<script>
  window.addEventListener('load', function () {
    var s = document.createElement('script');
    s.src = 'https://d3gievmnjacng1.cloudfront.net/loaders/prod.js';
    s.async = true;
    document.head.appendChild(s);
  });
</script>

Staging

<script>
  window.addEventListener('load', function () {
    var s = document.createElement('script');
    s.src = 'https://maya-b2b.s3.eu-central-1.amazonaws.com/loaders/staging.js';
    s.async = true;
    document.head.appendChild(s);
  });
</script>

The same pattern also works for full-page / quick search — you'd just swap the URL for the corresponding search loader (…/search-loaders/prod.js or …/search-loaders/staging.js).

Sending your own context to Maya​

The widget can pass dynamic context from your site to Maya with every message. Typical use cases:

  • User-specific information (e.g. logged-in user details, segment, loyalty tier)
  • Page-specific information (e.g. current product, geo, locale variant)

To send context, set the data-widget-context attribute on the widget element. The value must be a valid JSON string.

Example:

<div     
   id="maya-b2b-full-page"      
   data-organization-key="KEY"      
   data-organization-slug="SLUG"      
   data-language="LANGUAGE"      
   data-widget-mode="popover"
   data-widget-context='{"name":"John Doe"}'>
</div>

Opening the popover chat on demand​

Usage instructions:

  • Check if window.openMayaPopoverChat exists, this will exist only when our js build loads so better to check it in a loop until it succeeds.
  • Call window.openMayaPopoverChat(true)  when the function is found. true parameter opens the popover , false parameter closes it.

Sample js code to add in html DOM:

<script>
  (function() {
    const interval = setInterval(function() {
      if (window.openMayaPopoverChat) {
        clearInterval(interval);
        window.openMayaPopoverChat(true); // true = open
      }
    }, 100);
  })();
</script>

Showing a notification bubble​

Usage instructions:

  • Check if window.addMayaPopoverNotification exists. It only exists once our JS bundle has loaded, so check in a loop until it succeeds.
  • Call window.addMayaPopoverNotification('Your message') to show a notification bubble above the popover avatar. The user can dismiss it.
  • Pass null to clear the notification.

Sample js code to add in html DOM:

<script>
  (function() {
    const interval = setInterval(function() {
      if (window.addMayaPopoverNotification) {
        clearInterval(interval);
        window.addMayaPopoverNotification('Need help planning your trip?');
      }
    }, 100);
  })();
</script>

Markdown formatting​

The notification message supports Markdown and emojis. Supported features:

  • Bold: **text**
  • Italic: *text*
  • Links: [label](https://example.com)
  • Line breaks: press Enter once to start a new line

Filtering on a specific brand​

If you run several brands under one Maya account, add a data-brand attribute to the widget div so Maya only answers for that brand. Your Maya contact provides the brand code.

Full page

 <div     
   id="maya-b2b-full-page"      
   data-organization-key="KEY"      
   data-organization-slug="SLUG"      
   data-language="LANGUAGE"      
   data-widget-mode="full-page"
   data-brand="BRAND_CODE">
</div>

Popover

<div     
   id="maya-b2b-full-page"      
   data-organization-key="KEY"      
   data-organization-slug="SLUG"      
   data-language="LANGUAGE"      
   data-widget-mode="popover"
   data-brand="BRAND_CODE">
</div>

Cookies Maya sets​

We add the following cookies on the users’ browser for functionality and tracking. You need to make sure these cookies are not blocked by your website security or cookie tool. You probably need to add these to the list of cookies as well in your cookie policy/banner.

Chat:

  • maya_chat_slug_ENV*LANGUAGE*ORGANIZATION_SLUG
    • Keeps the conversation going across page changes and page refreshes.
  • maya_chat_token_ENV*LANGUAGE*ORGANIZATION_SLUG
    • Keeps the conversation going across page changes and page refreshes.
  • maya_is_popover_chat_open_ENV
    • If a visitor leaves the browser with the popover open on desktop, it stays open on their next visits until they close it.
  • maya_chat_auto_open_popover_ENV_mobile
    • The same behaviour on mobile.
  • maya_is_grid_mode_ENV
    • Remembers that a visitor was on the grid tab in full-page mode on mobile, so the grid is shown again after a page change or refresh.
  • maya_is_test_case
    • Marks a conversation as a test conversation, so test chats are not counted as real ones.
  • maya_is_internal_case
    • Marks a conversation as internal, so conversations started by your own team are reported separately.

ENV = dev/staging/production LANGUAGE = nl/en/fr/etc ORGANIZATION_SLUG = (see widget)

Adding Maya full-page search​

  1. Load the following script on the page where you want to show full page search:

Staging

<script src="https://maya-b2b.s3.eu-central-1.amazonaws.com/search-loaders/staging.js"></script>

Production

<script src="https://d3gievmnjacng1.cloudfront.net/search-loaders/prod.js"></script>
  1. Add the following div on the page where you want to show the full page search. Make sure to add in a container with full screen width and full screen height (excluding the height of the header).
 <div     
   id="maya-b2b-full-page"      
   data-organization-key="KEY"      
   data-organization-slug="SLUG"      
   data-language="LANGUAGE"      
   data-widget-mode="search">
</div>
  1. Load the following script on all the pages where you want to show the quick search:

Staging

<script src="https://maya-b2b.s3.eu-central-1.amazonaws.com/search-loaders/staging.js"></script>

Production

<script src="https://d3gievmnjacng1.cloudfront.net/search-loaders/prod.js"></script>
  1. Add the following div where you want to show the quick search widget.
 <div     
   id="maya-b2b-full-page"      
   data-organization-key="KEY"      
   data-organization-slug="SLUG"      
   data-language="LANGUAGE"      
   data-widget-mode="quick-search">
</div>

Notes​

  • Do not load multiple environment scripts on the same page as it’ll cause conflicts e.g. do not load staging and prod environment scripts on the same page.
  • The div maya-b2b-full-page should be added in html before including/loading the loader scripts either staging/production.
  • quick-search widget takes 100% height and width of the parent div. You need to give a height and width to the parent div in HTML DOM. Widget auto takes up all the provided space in case of quick-search

Functions you can call from your website​

Maya exposes the following functions on browser window. They only exist once our JS bundle has loaded, so check for the function in a loop until the check succeeds before calling it (as in the samples below).

window.sendMayaUserMessage(message)​

Sends a message to Maya on behalf of the user. It appears in the conversation as if the user had typed it, and Maya replies to it as usual.

  • The popover chat opens automatically — you do not need to also call window.openMayaPopoverChat(true).
  • If Maya is still answering a previous message, your message is queued and sent as soon as she is done.

Sample js code to add in html DOM:

<script>
  // WAITING FOR OUR CHAT BUNDLE TO LOAD
  (function() {
    const interval = setInterval(function() {
      if (window.sendMayaUserMessage) {
        clearInterval(interval);
        window.sendMayaUserMessage('I am looking for a hotel in Rome');
      }
    }, 100);
  })();
</scrip

window.openMayaPopoverChat(state)​

Opens or closes the popover chat widget, without sending any message. true opens it, false closes it.

Sample js code to add in html DOM:

<script>
	// WAITING FOR OUR CHAT BUNDLE TO LOAD
  (function() {
    const interval = setInterval(function() {
      if (window.openMayaPopoverChat) {
        clearInterval(interval);
        window.openMayaPopoverChat(true); // true = open, false = close
      }
    }, 100);
  })();
</script>

OR SIMPLY

<script>
  (function() {
      if (window.openMayaPopoverChat) {
        window.openMayaPopoverChat(true); // true = open, false = close
      }
  })();
</script>

window.addMayaPopoverNotification(message)​

Shows a notification bubble above the popover avatar, which the user can dismiss. It is a teaser message next to the launcher — not a message inside the conversation.

  • Pass null to clear the notification.
  • The message supports Markdown and emojis: bold **text**, italic *text*, links [label](https://example.com), and line breaks (press Enter once to start a new line).

Sample js code to add in html DOM:

<script>
	// WAITING FOR OUR CHAT BUNDLE TO LOAD
  (function() {
    const interval = setInterval(function() {
      if (window.addMayaPopoverNotification) {
        clearInterval(interval);
        window.addMayaPopoverNotification('Need help planning your trip?');
      }
    }, 100);
  })();
</script>

OR SIMPLY

<script>
  (function() {
      if (window.addMayaPopoverNotification) {
        clearInterval(interval);
        window.addMayaPopoverNotification('Need help planning your trip?');
      }
  })();
</script>