Assistant embed API
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 onemavenoid.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 newopenByDefault
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
This should always be set to "troubleshooter-open"
.
Other events may become available in the future.
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 useisInAppWebView
andalwaysOpen
.
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