Widget integration

Our widget is very easy to integrate on your own webpage. For some customers it's even easier than others since we offer our integration as one line of HTML which can be included by using tools like Google Tag Manager or by adding it to your code itself.

To find this one-line HTML integration, navigate to the Integrations > Widget page on the Oswald Dashboard. On the widget page you can find the Widget Script section with a single line integration like this:

<script>var t=new XMLHttpRequest;t.open("GET","https://api.oswald.ai/api/v1/chats/YOUR_UNIQUE_WIDGET_TOKEN/widget"),t.onreadystatechange=function(){if(200==t.status){var e=document.createElement("script");e.innerHTML=t.responseText,document.body.appendChild(e)}},t.send(null);</script>

Adding this line to your source code is all you need to do, and the widget will be running on your web page!

Customisation

There are a few customization options available for the widget integration. These can be selcted by adding the corresponding query parameter the url in the script above:

https://api.oswald.ai/api/v1/chats/YOUR_UNIQUE_WIDGET_TOKEN/widget?key=value&key2=value2

key	type	value
open	boolean	true --> Widget opens automatically false --> Widget stays closed until opened by user
startCommand	string	"your text command" --> send a custom start command to trigger a specific scenario in your chatbot onWidgetOpen.
locale	string	The language your bot needs to run in. E.g. "en-GB"
session	string	A custom sessionID for your conversation. When your page has multiple views/pages where the widget is active, you might want to assign a unique ID to each user so they can continue their conversation where they left off. If you don't provide a unique session ID yourself, the widget will generate a new one on each page reload/change, restarting the conversation from scratch and losing the previous context.

Open widget from your own button or link

You can create your own button to open the widget by using the following piece of code

<div id="current-quickreplies">
   <a href="#" id="widget-opener">open widget</a>
</div>
<script>
   document.getElementById('widget-opener').onclick = function openWidget() {
     document.getElementById('oswald-widget-bubble').contentWindow.postMessage({
       eventName: "open-oswald-iframe"
     }, "*");
   };
</script>

If you would like to hide the default Oswald chat button, you can do so by adding CSS styling to render the button somewhere off-screen.

Send metadata from your webpage to the chatbot

Let's say your chatbot is running on a specific page of your website or you already know the name of your users since they are logged in, you might want to provide this information to the chatbot through the metadata JSON object. To pass data to your widget (and thus the chatbot it connects to) simply add another Javascript block to your source code or through Google Tag Manager (or equivalent technology):

<script>
    function sendDataToOswald() {
        metadata = { 'key': 'value' };  // Add your relevant data here
        let dataToSend = { eventName: "oswald-data", metadata: metadata };
        document.getElementById('oswald-widget').contentWindow.postMessage(dataToSend, '*');
    }
    window.addEventListener("message", sendDataToOswald);
</script>

Reading out the metadata object in Oswald is very easy. Toggle the code switch on your response node where you want to extract the metadata and write your response like this:

# -*- coding: utf-8 -*-
from responses.responsemessage import ResponseMessage
from responses.responsetype import ResponseType
from responses.responsedata import ResponseData
from responses.response import Response
from responses.quickreply import Quickreply


class Response(Response):

  def getResponse(self, sentence, context, options={}):
    metadata = sentence.metadata  # THIS IS YOUR METADATA OBJ (PYTHON DICT/JSON)
    return ResponseMessage(
      data=[
        ResponseData(
          message=f"Hello. Metadata object is {metadata}",
          type=ResponseType.text
        )
      ]
    )