Widget Code Snippet & Expert JavaScript API

Typically you integrate a LoyJoy experience into your website by copying the code snippet from the Publish tab and pasting it into your website. This is the approach recommended to 99% of all websites and users.

However, in specific cases it can be necessary to fine-tune the integration with help of LoyJoy JavaScript API. The LoyJoy JavaScript API is a powerful programming interface to control the LoyJoy chat on your website. It allows you to show and hide the LoyJoy chat bubble, open and close the chat messenger, and much more.

caution

Only use the JavaScript API if you really understand JavaScript and need to influence the chat programmatically, i.e. you are a developer. Instead, for most use cases the code snippet from the Publish tab should suffice.

Reasons for using the JavaScript API instead of the code snippet from the Publish tab in combination with widget parameters might be: (1) You want to use Callback Parameters, (2) for data protection reasons you want to send params via JavaScript and not as widget query parameters.

The LoyJoy script registers the global function LoyJoy in the DOM window object and does not render the chat. Also it does not change other parts of the DOM.

<script src="https://stable.loyjoy.com/widget.js"></script>

danger

Do NOT add attributes async or defer to the script above or the following code randomly might run into a race condition.

Then render LoyJoy DOM chat elements into the DOM in an overlay as configured in the LoyJoy manager with the LoyJoy boot command.

<script>
LoyJoy('boot', {
  process: PROCESS_ID
})
</script>

Alternatively, you also can render the LoyJoy chat into the page flow. To achieve this insert a div with the id loyjoy-chat with a size defined by you, and let LoyJoy inject LoyJoy DOM elements into the div, automatically.

<div id="loyjoy-chat" style="width: 376px; height: 600px; line-height: 0; padding: 0"></div>

<script>
LoyJoy('boot', {
  process: PROCESS_ID
})
</script>

Configuration Parameters

Optionally you can add configuration parameters to the snippet. By default such parameters should be configured in LoyJoy Manager, however there can be exceptions that require programmatic access as follows:

Locale

A string in the format <language-iso-6391>-<region-iso-31662> (two-letter-codes) overwrites the customer’s settings regarding language and region. This language and region will be saved as the customer’s language and region.

<script>
LoyJoy('boot', {
  locale: 'de-CH',
  process: PROCESS_ID
})
</script>

Open

Tells the chat to open the chat messenger on load independent of other configuration settings.

<script>
LoyJoy('boot', {
  open: true,
  process: PROCESS_ID
})
</script>

Fullscreen

Tells the chat to render the chat UI in fullscreen for all screen sizes, so not only on mobile but also on tablets etc. This is helpful when you want to render the chat in an app (Android or iOS) in a WebView.

<script>
LoyJoy('boot', {
  fullscreen: true,
  process: PROCESS_ID
})
</script>

Restart

Tells the chat to restart the process after (1) a page reload, (2) calling LoyJoy('boot') or (3) jumping to another experience. This removes the chat history and restarts the experience from the beginning. In contrast to reset the session remains intact, i.e. the customer remains signed in and variables are not removed.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  restart: true
})
</script>

Reset

Tells the chat to reset the process after a page reload (or after a new LoyJoy('boot')). This removes the chat history and restarts the experience from the beginning.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  reset: true
})
</script>

By default the chat stores the chat history and customer variables in a local storage object loyjoy-chat. This behavior can be disabled either (1) configuratively in an experience in the LoyJoy manger, or (2) programatically via the JavaScript API. The following snippet disables the local storage programatically, so that the chat does not write to local storage object loyjoy-chat.

<script>
LoyJoy('boot', {
  cookie: false,
  process: PROCESS_ID
})
</script>

Event Listeners

The chat emits chat events such as open, close, sign-up that you can listen for with one or more event listener callback functions. Argument type contains the event name such as open, close, sign-up, argument detail contains a context object with chat event context information such as process_id and process_name.

<script>
LoyJoy('boot', {
  eventListeners: [function (type, detail) {}],
  process: PROCESS_ID
})
</script>

Freely Selected Parameters

Passes freely selected parameters to the experience that can be evaluated in the BPMN process using BPMN conditions and other expressions. For example, the parameters can be accessed with the GetParam function in LoyJoy.

<script>
LoyJoy('boot', {
  params: {
    foo: 'bar'
  },
  process: PROCESS_ID
})
</script>

Callback Parameters

Similar to freely selected parameters you can supply a callback function that will be evaluated dynamically. The callback also results in a parameter that can be used in the BPMN process with the GetParam function.

<script>
LoyJoy('boot', {
  callbacks: {
    foo: () => window.location.href
  },
  process: PROCESS_ID
})
</script>

Service Worker

By default LoyJoy will try to load the service worker from /service-worker.js to enable e.g. push notifications. To prevent LoyJoy from trying to load the service worker you can use the parameter serviceWorkerDisable. This is useful, if there is no /service-worker.js present and you want to prevent an HTTP 404 error.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  serviceWorkerDisable: true
})
</script>

IFrame

Tells the chat to render the chat messenger in an iframe instead of a web component. Not recommended, however might be necessary if JavaScript of your hosting web page modifies DOM elements of LoyJoy web components and you cannot fix this.

<script>
LoyJoy('boot', {
  process: PROCESS_ID,
  iframe: true
})
</script>

Control the Chat Programatically

Open

Opens the LoyJoy chat. Opposite to close.

<script>LoyJoy('open')</script>

Close

Closes the LoyJoy chat. Opposite to open.

<script>LoyJoy('close')</script>

Toggle

Opens the LoyJoy chat if it is closed. Closes the chat if it is open.

<script>LoyJoy('toggle')</script>

Remove

Removes the LoyJoy DOM elements from the DOM.

<script>LoyJoy('remove')</script>

Hide

Hides the LoyJoy element in DOM (display: none), but does not remove it. Opposite to show.

<script>LoyJoy('hide')</script>

Show

Makes the LoyJoy element visible in DOM. Opposite to hide.

<script>LoyJoy('show')</script>

GetVariable

Returns a variable value promise for the given variable name. Variable names are evaluated like in the process engine, i.e. process-specific variables are evaluated in the scope of the current process.

<script>LoyJoy('getVariable', 'firstname')</script>

You can also create the widget code snippet programmatically. This is useful if you want to dynamically change the widget parameters, if you want to load the widget code snippet only under certain conditions or if you are using a JavaScript framework like React, Angular or Vue.js.

Waiting for the onload event of the widget script is important, because the widget script loads the LoyJoy JavaScript API and the LoyJoy object is only available after the widget script has been loaded.

document.getElementById('loyjoy-script')?.remove()

var widgetScript = document.createElement('script')

widgetScript.async = true
widgetScript.defer = true
widgetScript.id = 'loyjoy-script'
widgetScript.onload = function () {
  LoyJoy('boot', {
    process: PROCESS_ID
  })
}
widgetScript.src = 'https://stable.loyjoy.com/widget/' + PROCESS_ID
widgetScript.type = 'text/javascript'

document.body.appendChild(widgetScript)

Widget Code Snippet & Expert JavaScript API