# Introduction

This client side API is available after you correctly integrated the moinAI Chat Widget into your website.

Keep in mind: The examples here are purposefully written in ES5 Javascript syntax to be fully compatible for Google Tag Manager integration. Feel free to use ES6 if you dont use GTM and like to do so.

# Integration

Just integrate this line into your Website with the proper IDs and the moinAI Chat Widget will show up on your site.

<script 
type="text/javascript" 
id="moinloader" 
src="https://widget.moin.ai/moin-loader.js?id=INSERT_YOUR_BOTID_HERE&channelid=INSERT_YOUR_CHANNEL_ID_HERE">
</script>

Injecting this multiple times wont affect anything. Once the Widget has detected another present Widget it wont load a second time. Keep this in mind when deploying multiple channels of the same bot on a site with e.g. multiple languages that might use the same CMS / GTM integration.

The script can easily have the defer or async tag if you prefer.

Once the Widget is integrated it will bootstrap itself and start working. If you wish to only show the widget at a later point consider either integrating the widget at a later point or using the Javascript client side API that we provide to correctly hide and the show the Widget as needed.

# Getting Started

If you wish to start manipulating the widget with the API right away you will have to register a chatWidgetReadyfunction in the global window object. This function is called ny the moinAI Chat Widget after successfull initiation and after making sure everything works.

window.chatWidgetReady = function() {

  /* the moinAI Chat Widget will call this function
  * upon bootstrapping itself and having full interoperability
  * place your code in here
  */

}

❗️❗️ Attention: keep in mind that a second registering of this function will overwrite the function before it. You have to consolidate your API functions here and/or make sure your usage of the API is clearly happening while the site and widget are expected to be interoperable. ❗️ ❗️

# Methods

# api.open()

# Arguments

none

# Usage

Open the Widget. Does nothing if already open.

window.knowhere.api.open()

# api.close()

# Arguments

none

# Usage

Close the Widget. Does nothing if already closed.

window.knowhere.api.close()

# api.toggle()

# Arguments

none

# Usage

Toggle the Widget open state. Open->Close ; Close->Open

window.knowhere.api.toggle()

# api.teaser({options})

# Arguments

# showTeaser

  • Type: Boolean
  • Default: true

# showAvatar

  • Type: Boolean
  • Default: true

# message

  • Type: string
  • Default: ''

# quickActions

  • Type: Array
  • Default: []

Expects quickActions Objects like:

{
  text: 'quickActionText', 
  intent: 'intent_identifier_1'
}

# Usage

Open teaser without Avatar and without quick actions

window.knowhere.api.teaser({
    showTeaser: true, 
    showAvatar: false,
    message: 'Open the Widget? 🍄' 
})

Open a teaser with quick actions and avatar

window.knowhere.api.teaser({
    showTeaser: true, 
    showAvatar: true,
    message: 'Open the Widget?',
    quickActions: [
     {text: 'yeah!', intent: 'intent_identifier_1'},
     {text: 'NO!', intent: 'intent_identifier_2'}
    ]
})

Results in:
api_teaser

*** Altenative, more compact Param description ***

{
  showTeaser: Boolean [Default: true], // display teaser
  showAvatar: Boolean [Default: true], // display the avatar
  message: String  [Default: '']// teaser message
  quickActions: Array [Default: []]// possible teaser quick actions 
}

Each teaser will overwrite the teaser before it.

# api.hideWidget()

# Arguments

none

# Usage

Hide the widget Bubble, Teaser and the Widget itself when it is showing. Does nothing if already hidden.

window.knowhere.api.hideWidget()

# api.showWidget()

# Arguments

none

# Usage

Show the widget again after a hideWidget call.

window.knowhere.api.showWidget()

# api.addContext({context})

# Arguments

context object

# Usage

Add context object to conversation. Only use this if you know what you are doing!

window.knowhere.api.addContext({context})

# api.getContext()

# Arguments

context object

# Returns

[context]

# Usage

Get array of manually added context objects.

window.knowhere.api.getContext()

# api.setWidgetzIndex(index)

# Arguments

new z index value of the whole widget

# Usage

Set the zIndex of the widget for compatibility with other elements on the site.

window.knowhere.api.setWidgetzIndex(index)

# api.setWidgetPosition(bottom,right,unit,showAnimation)

# Arguments

bottom: relative to bottom
right: relative to right
unit: unit that is used. all css units are allowed. e.g. 'px', '%' etc. default: 'px'
showAnimation: bool if the moving should be animated. default false

# Usage

Move widget icon. The widget will ALWAYS open to the top left of the icon.

window.knowhere.api.setWidgetPosition(bottom,right,unit,showAnimation)

# api.on(event, callback)

# Arguments

event: eventtype you wish to register on for, values: 'widget.interaction' , 'user.click', 'user.input' ricallbackght: relative to right

# Usage

Move widget icon. The widget will ALWAYS open to the top left of the icon.

        window.knowhere.api.on('widget.interaction', function (data)  {
          console.log('CUSTOMER EVENT WIDGET HANDLER widget.interaction', data)
        })

        window.knowhere.api.on('user.click', function (data)  {
          console.log('CUSTOMER EVENT CLICK HANDLER user.click', data)
        })

        window.knowhere.api.on('user.input', function (data)  {
          console.log('CUSTOMER EVENT INPUT HANDLER user.input', data)
        })