This repo provides a set of example and starter kit service desk integrations for use with Watson Assistant web chat – to allow end-users on web chat to escalate to a human agent. We provide starter kits to common live agent platforms, like Genesys Cloud, and also show you how to build custom integrations to other platforms.
This repo provides a development and production build environment for adding your own client-side service desk implementations to the web chat integration for Watson Assistant. These extensions can be shared between teams and also can be submitted as potential contributions to the main web chat project. If you're interested in contributing to this project or proposing that your integration be offered in Watson Assistant, see ./CONTRIBUTING.md.
Important: Any custom code used with Watson Assistant is the responsibility of the developer and is not covered by IBM support.
To find out if your company's tool is feasible for this approach, check out our Adoption Guide here. If you'd like some help to build an integration, contact us here.
We provide reference implementations that provide fully functional integrations with popular service desks. These implementations, while functional, are examples only, and have not been vetted for production use.
In order for web chat to integrate with a custom service desk, there are two basic steps that need to happen:
- Code must be written that communicates with the service desk (such as by starting a conversation or sending a message to a human agent) and satisfies the API contract defined by web chat.
- Web chat needs to be given access to that code, so it can run it.
This repository is intended to help with both of these steps and can be used to build a deployable javascript bundle containing your custom service desk integration. However, it is not required to use any of the processes or tools in this repository for that. If you have your own front-end application and infrastructure for your website you can copy the appropriate code from step 1 above into your application and build and deploy it using your existing infrastructure; it is not required for the integration to be built and deployed separately.
You can read more information with our api documentation.
If you have implemented a service integration that satisfies the web chat API, getting web chat to use it only requires providing a factory function that can create a new instance of your integration. Below contains an example of an empty integration (that doesn't do any communicating with a service desk) to show how to register an integration with web chat. Your integration does not have to be built into a separate javascript bundle or hosted separately from the rest of your front-end application.
<script>
// Your custom service desk integration which can be located anywhere in your codebase.
class MyServiceDesk {
constructor(callback) {
this.callback = callback;
}
startChat() {
console.log('Starting chat');
}
endChat() {
console.log('Ending chat');
}
sendMessageToAgent() {
console.log('Sending message to agent');
}
}
// Regular web chat embed script.
window.watsonAssistantChatOptions = {
integrationID: "YOUR_INTEGRATION_ID",
region: "YOUR_REGION",
serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
onLoad: function(instance) {
instance.render();
},
// **** The important part. This creates an instance of your integration.
serviceDeskFactory: (parameters) => new MyServiceDesk(parameters.callback),
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>This repo can be used as an isolated tool to build and test your integration with your web application. The basic steps to use it are:
- Use the build process in this repo to build a javascript bundle of your integration. This will produce a
servicedesk.bundle.jsfile. Each integration should have a README describing in detail the steps necessary to build it. - Upload the
servicedesk.bundle.jsfile to a hosting location where the file can be downloaded and included in your application. - Add a script tag to your application's HTML file that will load your integration. This will expose a global
WebChatServiceDeskFactoryfunction that can be provided to web chat. - Add the configuration option to web chat to use
WebChatServiceDeskFactory.
<!-- The servicedesk.bundle.js is the script this repo will generate. You are responsible for finding a place to host it. -->
<script>
window.WebChatServiceDeskFactory = {};
setTimeout(function(){const t=document.createElement('script');t.src='YOUR_HOST/servicedesk.bundle.js';document.head.appendChild(t);});
</script>
<script>
// Regular web chat embed script.
window.watsonAssistantChatOptions = {
integrationID: "YOUR_INTEGRATION_ID",
region: "YOUR_REGION",
serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
onLoad: function(instance) {
instance.render();
},
// The function that this project exports and is contained in servicedesk.bundle.js.
serviceDeskFactory: window.WebChatServiceDeskFactory,
};
setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';document.head.appendChild(t);});
</script>Tailor web chat to your needs by initializing it with your own custom options. The web chat configuration options are defined by the parameters of watsonAssistantChatOptions.
In addition to the parameters listed here, it supports the following options:
serviceDesk: {
availabilityTimeoutSeconds: 30,
}
availabilityTimeoutSeconds: The timeout value in seconds to use when determining agent availability. When a connect_to_agent response is received, the system will ask the service desk if any agents are available. If no response is received within the timeout window, the system will return "false" to indicate no agents are available. The default in web chat is 5 seconds.
To set up your development environment, first fork this repository.
To run the default example, go to the src/example/webChat directory and follow the instructions in the README.md.
To enable linting rules specific to this project on your IDE or Code Editor run npm install from the root project directory.
It is recommended you follow the same pattern and add your service-desk-specific files to the ./src/ directory as well. All the code is heavily commented via JSDoc and contains TypeScript type definitions for all properties passed to functions.
See ./docs/API.md for further API documentation, and ./docs/STEPS.md for a recommended sequence of steps for building an integration.
The serviceDeskFactory configuration setting expects a factory that returns an object of functions or a class. These functions and the properties passed to the factory are defined in ./src/types/serviceDesk.ts. The web chat will call these functions as needed to communicate with your service desk code.
One of the items passed into the factory is a callback object. These callbacks are defined in ./src/types/serviceDeskCallback.ts. These are the functions you will call inside your service desk code to communicate information back to the web chat.
As of the 4.5.0 release of web chat, Watson Assistant will pass configuration needed to display a chat history widget in your live agent application interface. This agent application will contain a copy of the conversation your customer had with Watson Assistant for your live agent to be able to view. Visit './docs/AGENT_APP.md' to learn more.
Supporting compatible browsers and all other build concerns are handled for you. Just run npm run build, and dist/servicedesk.bundle.js is generated. Embed this file before the web chat embed script, and it will make window.WebChatServiceDeskFactory available for use.
This project uses jest as its testing framework with TypeScript capabilities enabled. Tests should be under a __tests__ subdirectory and should have file names in the following format: FILE_TO_BE_TESTED_NAME.test.ts.
To run the defined tests, run npm run test.
The following items are not currently in scope for this starter kit and would be your responsibility to implement if you need them:
- Security support (this varies depending on the service desk, but most require generating and sending valid JWTs with messages to the agent)
- Routing to specific agents
- Behavior when all agents are offline
This repository is written in TypeScript. Because the web chat is also written in TypeScript, IBM can standardize and release service desk extensions also written in TypeScript into the main project. The official TypeScript documentation is very thorough and has many valuable resources, starting with TypeScript in 5 minutes. If you are using a modern text editor, you will quickly discover how useful it is to right-click on a complex object argument in a function and view its detailed type definition!