ASK Frontend

Overview

ASK Frontend provides two web components for talking with ASK.

These two components are ask-button and ask-chat.

Installation

ASK Frontend is delivered in two variants:

The remainder of the document explains the usage of the iife variant.

If you are integrating ASK into a Vue application and want to use the Vue components, feel free to reach out to us for further support.

ask-button Setup

The <ask-button> component provides all you need for quickly integrating ASK into your site.

It will add a button to open the ASK chat to your site. The chat will be shown using the <ask-chat> component.

  1. Add Script 
    <script src="https://dist.aboutsomethink.org/ask-frontend.iife.js"></script>
  2. Add Configuration 
    <script>
  window.askSetup({
    botID: 23,                                // Replace with bot id provided for your deployment
    token: "deadbeefdeadbeefdeadbeefdeadbeef" // Replace with token provided for your deployment
  })
</script>
  3. Add Web Component 
    <ask-button></ask-button>

Full example

<html lang="en">
  <head>
    <!-- Add the ask-frontend script into the head -->
    <script src="https://dist.aboutsomethink.org/ask-frontend.iife.js"></script>
    <script>
      window.askSetup({
        botID: 23,                                // Replace with bot id provided for your deployment
        token: "deadbeefdeadbeefdeadbeefdeadbeef" // Replace with token provided for your deployment
      })
    </script>
  </head>
  <body>
    <!-- Add the ask-button into the body -->
    <ask-button></ask-button>
  </body>
</html>

ask-chat Setup

<ask-chat> provides a component for implementations that want to provide a more customized experience.

This component just provides the chat logic and allows for integration into your site in any way you like, for example including the chat into specific pages.

  1. Add Script 
    <script src="https://dist.aboutsomethink.org/ask-frontend.iife.js"></script>
  2. Add Configuration 
    <script>
  window.askSetup({
    botID: 23,                                // Replace with bot id provided for your deployment
    token: "deadbeefdeadbeefdeadbeefdeadbeef" // Replace with token provided for your deployment
  })
</script>
  3. Add Web Component 
    <ask-chat></ask-chat>

By default, the component extends to the available height using height: 100%. This can be overwritten by passing styles to the component, like this:

<ask-chat style="height: 400px;"></ask-chat>

Example creating a chat dialog

<button onclick="chat.show()">open modal</button>

<dialog id="chat" style="width: 80dvw; height: 60dvh;">
  <form method="dialog" style="position: absolute; right: 10px">
    <button>✕</button>
  </form>

  <ask-chat></ask-chat>
</dialog>

Configuration

The configuration is validated automatically.

If there are any errors, they will be logged to the browser console and ASK Frontend will abort.

Required

There are two settings that are required for all configurations:

Setting Description
botID ID of the bot the chat should interact with.
token Token for authenticating to the ASK API.

For special cases where a different means of authentication is used, token can be set to null. In this case, no authentication header will be sent by the SDK.

Optional

There are the following settings that allow for further customization of the configuration:

Setting Description
apiEndpoint Allow overriding the API Endpoint. This is useful for testing, or if you have your own ASK instance.
botName Override the name used to show the authorship of the bot's chat messages.
chatTitle Set a different heading for the chat. If it's null, it will be hidden.
enableDebug If true, it's possible to reset the Bot to a certain state, and to see some current state debug information.
headers An object containing addional headers that should be sent to the API.
keepOpen If set to true the modal or dialog (depending on modal) stays open when navigating.
language Select a translation. Currently, "de" and "en" are supported.
languageSwitch If set to true, show a language switcher.
linkMethod How to handle links. By default links are opened in the same tab. Other options are "newTab" and "callback".
linkCallback JavaScript callback for link click. Required when linkMethod is "callback". preventDefault() is run before the callback.
modal Configure how <ask-button> shows the chat. By default it is shown in a drawer, with this set to true, it's shown as a modal.
stateIdentifier Override the identifier that is used to store the bot's state. By setting the same identifier for different bots, we can make them share their state.
streamMessages If false, Server Sent Events ("streaming of messages") will not be used.
style Injected CSS into the shadow DOM of the web component.

Example configuration

window.askSetup({
  botID: 23,
  token: "deadbeefdeadbeefdeadbeefdeadbeef",
  apiEndpoint: "https://recbot-acme.reelport.com",
  chatTitle: "Talk with ACME Bot",
  language: "en",
  languageSwitch: true,
  linkMethod: "callback",
  linkCallback: (url) => {
    window.open(url, "_blank");
  },
  modal: true,
  style: "h3 {color: #88f;}",
});

Customize Styles

ASK Frontend uses Tailwind CSS with daisyUI for styling.

To customize the style, you can override CSS variables for the web component.

All variables are evaluated in the OKLCH color space using the oklch() function.

A color picker for this space can be found here.

An example configuring ASK Frontend to use a dark theme looks like this:

ask-button {
  --a: 41.342% 20.732% 321.82;  /* Accent color */
  --ac: 100% 0% 0;              /* Accent contrast */

  --b1: 8% 0% 0;                /* Background 100 */
  --b2: 4% 0% 0;                /* Background 200 */
  --b3: 0% 0% 0;                /* Background 300 */
  --bc: 100% 0% 0;              /* Background contrast */

  --n: 79.37% 0% 0;             /* Neutral color */

  --p: 41.342% 20.732% 321.82;  /* Primary color */
  --pc: 100% 0% 0;              /* Primary contrast */

  --s: 86.811% 44.384% 91.688;  /* Secondary color */
  --sc: 13.189% 44.384% 91.688; /* Secondary foreground */
}

To get further information, or to explore themes, see daisyUI's color documentation.

For more detailed customization, the style configuration option of the setup function can also be used to inject styles directly into the shadow DOM.

Chat commands

In the chat, users can enter /clear to start a new conversation.

State

ASK Frontend uses localStorage to store its state.

This means that you can use the following code to clear the bot's history, e.g. when the user logs out:

localStorage.clear();

Advanced usage

If more detailed settings are required, there are advanced ways to use the ASK Frontend, see the regarding documentation.