The New Watson Assistant v2 Stateless API: Unlock Enterprise Features Today!

Moving your existing chatbot from v1 to v2 API is now a breeze.

Start using access control, channel integrations, and lifecycle management with stateless v2 API

A few months ago we released the new v2 version of Watson Assistant API. This new v2 version provides several enterprise-grade capabilities, such as automatic application state management, access control, knowledge-base search, and lifecycle management.

Automatic state management provided by the v2 runtime API can significantly simplify your custom application. However, you may already have a tried and true application that manages its own state and uses Watson Assistant’s v1 runtime API in production. In order to help you start using v2 runtime API quickly, and without deferring state management to Watson Assistant, we have released the v2 stateless runtime API.

Although v2 runtime API is a major version upgrade from v1, and provides various new features, moving your application to use v2 stateless from v1 is relatively quick and easy, by following these four steps:

1. Add your dialog skill to an assistant using the Watson Assistant user interface.

Using the Watson Assistant user interface, first create a new assistant. Then, add your existing dialog skill (which was called a workspace before v2 API was released) in to your new assistant.

(Left) A new assistant, named “Technical support assistant”, with no skills, and (right) the same assistant with the skill (i.e. workspace) named “Dialog skill for tech support chatbot”.

2. Change your custom application to use Watson Assistant v2 runtime API URI, instead of the v1 API URI.

The v1 runtime API directly interacted with a skill (which was called a workspace).

{url}/v1/workspaces/{workspace_id}/message

The new v2 API interacts with an assistant, and the URI shape has been changed accordingly:

{url}/v2/assistants/{assistant_id}/message

3. Change where you send application state in the /message API JSON payload.

This is also a quick change in your application code, to simply change the property that contains your application state. The v1 runtime API delivered the state as part of the context property. For example, if your context was stored in a variable called my_context_var, the context property would look like this:

...
"context": {
   "my_context_var": “123”
}
...

In v2 stateless runtime API, the context is sent in the user_defined property, under a property dedicated to the context of the main dialog skill of your assistant, as follows:

...
"context": {
   "skills": {
      "main skill": {
         "user_defined": {
            "my_context_var": “123”
         } 
      }
   }
}
...

There is a reason for this deeper and slightly more complex JSON object. An assistant can contain more than one skill; a dialog skill (referred to as main skill) and a search skill. This structure allows accommodating state for multiple skills, and also state associated with the entire assistant (see v2 API Reference for more details).

4. Change where you send the user_id property in the /message API JSON payload.

user_id identifies the user who is interacting with the assistant, and it is used to identify unique users for billing purposes in Plus and Premium plan. The v1 runtime API required sending user_id in the context.metadata property:

...
"context": {
   "metadata":: {
      ":user_id": "user1234"
}
...

In the v2 runtime API, user_id must be sent in context.global.system property, as follows:

...
"context": {
   "global": {
      "system": {
         "user_id:": "user1234"
}
...

Watson Assistant v2 runtime API opens the door to several powerful enterprise features, such as skill versioning, search skill, access control, and lifecycle management. The new stateless v2 runtime API makes moving your existing v1-based applications to v2 much easier, removing the burden of re-writing state management logic.

Update your applications to use the v2 stateless API, and get the most of your Watson assistant today!