Setting context
Learn how to use web chat to set conversation context variables that are sent to your assistant.
Overview
The context is an important part of nontrivial dialog skills; it is used to store conversation state, including variables you can define for your application, for the duration of a session. (For more information about the context, see the Watson Assistant documentation).
By subscribing to events that are fired when messages are sent to your assistant, you can extend your Web Chat to modify context variables.
Instructions
Context variables are sent and received as part of the message payload. Therefore, to set a new context variable, your website code must manipulate a message being sent to Watson Assistant from web chat.
This tutorial uses an example dialog skill that uses a context variable to determine its responses. This skill looks for the boolean context variable party_time
; when you ask "Is it party time?", the skill responds in the negative or affirmative depending on the value of the context variable.
Before you can use web chat to interact with this skill, you must create an assistant that uses it:
- Download and save the
setting-context.json
file below. - In the Watson Assistant UI, create a new skill by importing the
setting-context.json
file. - Add the new skill to an assistant.
- Create a new web chat integration for the assistant. Make note of the HTML code snippet that is provided when you create the web chat.
For more information about creating assistants and skills, see the Watson Assistant documentation.
Downloadable Files
setting-context.json
A dialog skill configured to react to updated context items.Adding basic embed code
Now embed the web chat code into your website HTML. The embed code should look something like the code snippet below. Remember to change the integrationID
and region
values to the values you were given when you created your web chat.
Basic Embed Code
<!doctype html>
<html>
<body>
<script>
window.watsonAssistantChatOptions = {
// A UUID like '1d7e34d5-3952-4b86-90eb-7c7232b9b540' included in the embed code provided in Watson Assistant.
integrationID: 'YOUR_INTEGRATION_ID',
// Your assistants region e.g. 'us-south', 'us-east', 'jp-tok' 'au-syd', 'eu-gb', 'eu-de', etc.
region: 'YOUR_REGION',
// The callback function that is called after the widget instance has been created.
onLoad: function(instance) {
instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/loadWatsonAssistantChat.js';document.head.appendChild(t);});
</script>
</body>
</html>
Using the pre:send event
Events fired by web chat enable you to react to what web chat is doing. (For more information about the web chat event system, see Events.) We want to watch for Web Chat sending a message back to the assistant so we can make some changes to the message before it is sent. (For this tutorial example, we only need to set a context variable, but you can do many other things. For example, you might need to filter any privately identifiable information out of the message before it is sent to the IBM Cloud, or even play branded audio files when a message is sent or received.)
The pre:send
event passes an object containing the event name and event data to the function that you subscribed as a callback for that event type. The data passed by the pre:send
event is a superset of the Assistant v2 message API response.
Add the pre:send
event handler to your web chat code snippet as shown below. This code snippet uses the instance.on()
method to subscribe the preSendHandler()
function to the pre:send
event type. The preSendHandler()
function sets the value of the party_time
context variable to true
in the message that is about to be sent.
Subscribing to the pre:send
event and updating context
<!doctype html>
<html lang="en">
<body>
<script>
/**
* Following the v2 message API Response
* at https://cloud.ibm.com/apidocs/assistant/assistant-v2#send-user-input-to-assistant,
* we add some items to context.
*/
function preSendhandler(event) {
// When fetching the Welcome Node on startup, the context won't be defined, yet. If you want to add to
// context when fetching welcome node, you will need to define the context.
event.data.context.skills['main skill'] = event.data.context.skills['main skill'] || { user_defined: {} };
event.data.context.skills['main skill'].user_defined.party_time = true;
// You can OPTIONALLY return a promise and we will wait to continue processing until the promise is resolved. If
// you return nothing we will immediately continue processing the event. If you fail the Promise we will cancel
// sending the message.
/*
return new Promise(function(resolve) {
myAsyncThing.then(function(moreData) {
// Do some other manipulation of event.data...
resolve();
});
});
*/
}
window.watsonAssistantChatOptions = {
integrationID: "YOUR_INTEGRATION_ID",
region: "YOUR_REGION",
serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
onLoad: function(instance) {
// Subscribe to the "pre:send" event.
instance.on({ type: "pre:send", handler: preSendhandler });
instance.render();
}
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/loadWatsonAssistantChat.js';document.head.appendChild(t);});
</script>
</body>
</html>