This blog post is about a simple example to use the Watson Assistant API v2 with the Node.js SDK to get a Watson Assistant sessionID and send a message to Watson Assistant using this sessionID. Here is the GitHub project watson-assistant-simple-node-js-server-example.

The objective is only to start a chat session and return the values we get from Watson Assistant API v2 methods. The simple Node.js server has implemented following REST endpoints :

• GET getsession (which creates a new sessionID)
• POST sendmessage

The project contains examples for using Postman.

The blog post is structured in:

• Connect to an assistant in the right environment
• Implement a simple endpoint
• Use the example
• Summary

CONNECT TO AN ASSISTANT IN THE RIGHT ENVIRONMENT

Therefor we will first connect to our Watson Assistant service instance with the environmentID. Because we need to know to which environment we want to connect our server.

A small diagram with simplified dependencies. In my case I connected to the draft environment.

The GitHub project also contains a bash script to list the environments using cRUL.

The following code shows an extract of a return value of a bash script execution.

{"environments":[
    {"name":"draft",
     "description":"My Example Assistant",
     "environment":"draft",
     "assistant_id":"df8d00f8-e9cc-XXXXXXXX",
     "orchestration":{"search_skill_fallback":false},
     "environment_id":"3d6d1cd6-29fd-XXXXXXXX",
     "session_timeout":120,
      ...
}

The relevant code in server.js file to connect to the right environment of the Watson Assistant service.

const assistant = new AssistantV2({
    version: e_version,
    authenticator: new IamAuthenticator({
      apikey: e_apikey,
    }),
    serviceUrl: e_serverUrl,
  });

IMPLEMENT A SIMPLE ENDPOINT

When we are connected to the right assistant with the right environment, we can use this connection and we mostly just reuse the code given in the Watson Assistant API v2 documentation for the Node.js SDK in the implementation of our REST endpoint.

app.get('/getsession', (req, res) => {   
    assistant.createSession({
        assistantId: e_environmentID
    })
    .then(createSessionresult => {
        console.log(JSON.stringify(createSessionresult.result, null, 2));
        sessionID = JSON.stringify(createSessionresult.result, null, 2);
        res.statusCode = 200;
        res.write(sessionID);
        res.end();
    })
    .catch(createSessionError => {
        console.log(createSessionError);
        res.statusCode = 500;
        res.write(createSessionError);
        res.end();
    });  
});

This is a simplified diagram of the given dependencies of our scenario.

USE THE EXAMPLE

Here are the steps you can follow to run this example on your local machine.

STEP 1: CLONE THE PROJECT TO YOUR LOCAL COMPUTER

git clone https://github.com/thomassuedbroecker/
watson-assistant-simple-node-js-server-example.git
cd
watson-assistant-simple-node-js-server-example/code/simple-server

STEP 2: CONFIGURE THE ENVIRONMENT VARIABLES

Here we need an environmentID. We can find this ID in the Watson Assistant user interface, by navigating to the Environments page and selecting the environment you want to use (such as Draft or Live). Then you open the environment settings and copy the value from the appropriate field. (Contains the Link to the IBM Cloud documentation)

The image below shows the environment ID in the IBM Cloud UI.

We also need an API key and a base URL from the Credentials. The image blow shows the API key and the URL in the IBM Cloud UI.

• Create an .env file

cat .env-template > .env

• Configure the .env file to your needs

WATSON_ASSISTANT_VERSION='2021-11-27'
WATSON_ASSISTANT_API_KEY='XXXX'
WATSON_ASSISTANT_SERVICE_URL='https://api.us-south.assistant.watson.cloud.ibm.com'
WATSON_ASSISTANT_ENVIRONMENT_ID='XXX'

STEP 3: RUN LOCAL ON PORT 3010

npm install
npm start

STEP 4: OPEN BROWSER AND INVOKE THE GET SESSION ENDPOINT

It returns the newly created sessionID.

open http://localhost:3010/getsession

• Example output:

{
"session_id": "37d13c72-1643-4add-bee5-574c6fd062dc"
}

STEP 5: IMPORT THE POSTMAN COLLECTION INTO POSTMAN

The images shows the import button in postman.

Select the /postman/watson-assistant-example.postman_collection.json in the project for the import.

STEP 6: AFTER THE IMPORT YOU HAVE A NEW COLLECTION INSIDE YOUR POSTMAN

The images shows the imported collection.

STEP 7: SEND A MESSAGE

Here again the simplified diagram of the given dependencies of our scenario.

STEP 7.1: GET A SESSIONID

Now we need to get the sessionID with GET request using the getsession endpoint. We copy the value of the sessionID to use it inside the next REST endpoint invocation.

STEP 7.2: INSERT THE SESSION ID INTO THE BODY OF THE POST REQUEST USING THE SENDMESSAGE ENDPOINT

This is the JSON format which is used in the POST request sendmessage body in Postman. Now we insert the copied sessionID into the body of the request inside postman.

{ "sendmessage" : {
  "sessionID" : "XXXX",
  "message_type": "text",
  "text": "Hello"
  }
}

Now we see the output of the sendmessage request in the expected JSON format.

SUMMARY

The usage of the Watson Assistant API v2 is very easy and good documented, but you need to understand the environment topic. At the moment the documentation talks about the assistantID to pass into an invocation as an example, this can cause a misunderstanding. Here a screen shot of the IBM Cloud documentation “createsession” created on 09.12.2022.

I hope this was useful for you and let’s see what’s next?

Greetings,

Thomas

watsonassistant, #nodejs, #ibmcloud, #rest, #javascript

Original blog post on www.suedbroecker.net SIMPLE NODE.JS SERVER EXAMPLE USING THE WATSON ASSISTANT API V2