DocumentatieAdvanced code responsesIntegration APILaunch Oswald
Search…
Integration documentation
English documentation
What is the integration API
Authentication
Sending a message
Accessing message history
Forget session data
Widget integration
Nederlandstalige documentatie
Wat is de integratie API?
Authenticatie
Bericht versturen
Powered By GitBook
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:
1
<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>
Copied!
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
1
<div id="current-quickreplies">
2
   <a href="#" id="widget-opener">open widget</a>
3
</div>
4
<script>
5
   document.getElementById('widget-opener').onclick = function openWidget() {
6
     document.getElementById('oswald-widget-bubble').contentWindow.postMessage({
7
       eventName: "open-oswald-iframe"
8
     }, "*");
9
   };
10
</script>
Copied!
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):
1
<script>
2
function sendDataToOswald() {
3
metadata = { 'key': 'value' }; // Add your relevant data here
4
let dataToSend = { eventName: "oswald-data", metadata: metadata };
5
document.getElementById('oswald-widget').contentWindow.postMessage(dataToSend, '*');
6
}
7
window.addEventListener("message", sendDataToOswald);
8
</script>
Copied!
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:
1
# -*- coding: utf-8 -*-
2
from responses.responsemessage import ResponseMessage
3
from responses.responsetype import ResponseType
4
from responses.responsedata import ResponseData
5
from responses.response import Response
6
from responses.quickreply import Quickreply
7
​
8
​
9
class Response(Response):
10
​
11
def getResponse(self, sentence, context, options={}):
12
metadata = sentence.metadata # THIS IS YOUR METADATA OBJ (PYTHON DICT/JSON)
13
return ResponseMessage(
14
data=[
15
ResponseData(
16
message=f"Hello. Metadata object is {metadata}",
17
type=ResponseType.text
18
)
19
]
20
)
Copied!
​
English documentation - Previous
Forget session data
Next - Nederlandstalige documentatie
Wat is de integratie API?
Last modified 11mo ago
Copy link
Contents
Customisation
Open widget from your own button or link
Send metadata from your webpage to the chatbot