Assistant embed API · Mavenoid help center

The assistant is embedded in a web page or mobile app using a JavaScript snippet like the following:

<script>
  // --- begin mavenoid embedded troubleshooter ---
  (function(m,a,v,e,n,o,i,d) {
    d=m.createElement(e);d.async=true;d.src="https://app.mavenoid.com"+v;
    i=m.getElementsByTagName(e)[0];i.parentNode.insertBefore(d,i);n[o]=n[o]||[];
  })(document,0,"/embedded/embedded.js","script",window,"mavenoid");
  // --- end mavenoid embedded troubleshooter ---

  mavenoid.config = {
    noIframe: false,
    clientId: "01234567890",
  };
  mavenoid.push({ event: "troubleshooter-open", orgName: "example-org", position: "right"});
</script>

The last line of JavaScript, which contains mavenoid.push, is what causes the assistant to display on the page or in the app. This mavenoid.push call can be configured to change the behavior of the assistant by modifying the parameters that are passed into it.

Don't add multiple mavenoid.push calls or duplicate any parameters. There should be exactly one mavenoid.push call which takes exactly one object which has each parameter, no more than once, as a comma-separated list inside the curly braces.

For example, if you want the assistant to appear on the left side instead of the right and start already opened, you should replace the existing position parameter and add a new openByDefault parameter, resulting in a line like this:
mavenoid.push({ event: "troubleshooter-open", orgName: "example-org", position: "left", openByDefault: true});

The following parameters may be passed to the mavenoid.push call to configure the behavior of the assistant.

Required parameters

`event`

string (usually "troubleshooter-open")

What event to push to Mavenoid, and thus which action the assistant should take. For normal embedding, this should always be set to "troubleshooter-open". There are a few other options that may be useful if you are controlling the assistant with JavaScript.

These events are currently available:

troubleshooter-open: Loads the assistant with the configuration specified through all other included parameters. If the assistant was already loaded, this will reload it with the new configuration.
troubleshooter-show: Opens the assistant if it has already been loaded with a troubleshooter-open event.
troubleshooter-hide: Closes the assistant if it is currently open.
troubleshooter-unmount: Unloads the assistant from the page. To open it again, it will first need to be reloaded with another troubleshooter-open event.

event: "troubleshooter-open"

`orgName`

string

The name of your Mavenoid organisation.

orgName: "example-org"

Optional parameters

`alwaysOpen`

boolean
Default value: false

If false, display a button the user can click to open the assistant when closed or close it when open. If true, instead open the assistant immediately (similar to openByDefault) and also remove the button so that the assistant cannot be closed from within its own UI.

You may wish to set this to true if embedding the assistant in a standalone web page or in a mobile app.

alwaysOpen: true

`buttonText`

This parameter is only used in the previous version of the assistant. In the current version, the button's icon(s) and label(s) are instead configured in your organization's appearance settings.

string
Default value: "Get instant help!"

What text to display on the assistant button when the user hovers over it.

buttonText: "Have any questions?"

`defaultLang`

string (an ISO language code)

If specified and there is a translation available matching the provided language code, the assistant will display that translation's text. If not specified or there is no matching translation, the assistant will decide which language to use based on what is available and what the user's browser indicates. The user can also override this within the assistant and pick a different language.

defaultLang: "sv"

`initFormData`

Record<string, string>

If specified, prepopulates the specified form data keys with the specified values.

See Understand form data - How form data gets set - JavaScript for more information.

initFormData: {name: "A User", email: "[email protected]"}

`isInAppWebView`

boolean
Default value: false

If false, the assistant's close button displays a v character to indicate that it will minimize the assistant, and the width of the assistant is determined by the viewport dimensions. If true, the close button instead displays an x character (assuming it hasn't been removed by alwaysOpen) to indicate that it will close the assistant, and the width of the assistant is always the full viewport.

You may wish to set this to true if embedding the assistant in a standalone web page or in a mobile app.

isInAppWebView: true

`onClose`

() => void

A function to run when the user clicks the assistant's close button.

The primary use case is for when the assistant is embedded in a mobile app. This function can then be used to signal the app that the webview should be closed.

/**
 * One way is to navigate to a special URL and watch for it on location changes.
 */
onClose: function () { window.location.assign("close:"); }

/**
  * Another way is to post a message to the webview's parent page that the assistant was closed.
 */
 onClose: function () { window.postMessage("ASSISTANT_CLOSED", "%YOUR_DOMAIN%") }

`openByDefault`

boolean
Default value: false

If false, display a button the user can click to open the assistant. If true, instead open the assistant immediately.

You may wish to set this to true if embedding the assistant in a standalone web page or in a mobile app.

If you also want to prevent the assistant from being closed, see alwaysOpen.

openByDefault: true

`position`

string (one of "right" or "left")
Default value: "right"

Where the button and assistant will be positioned on the page. Use "right" or "left" to place the button and assistant on that side of the page.

position: "left"

In the previous version of the assistant, this parameter also accepted the value "fullscreen" to have the assistant fill the whole screen, such as if it is being used in a mobile app. In the current version, instead use isInAppWebView and alwaysOpen.

`productId`

integer

The numeric ID of the flow to embed. If none is specified and your organization has exactly one published and visible flow, that flow will be embedded; if none is specified and your organization has multiple published and visible flows, a list of flows will be presented instead.

While this parameter is technically optional, we strongly encourage you to use it. Otherwise, existing embedded assistants may change their behavior if you publish more flows.

productId: 4337631

`themeKey`

number

Which color theme to use for this assistant out of those specified in the organization's appearance settings. Zero-indexed.

This feature may not be available in the Basic plan. To learn more, please contact your Mavenoid representative.

themeKey: 2