XState WebChat Service

Introduction :

XState-Webchat is a chatbot developed on the technology XState. XState is a JavaScript implementation of the concept of state charts. Web Chatbot is developed as a backend service that will receive messages incoming from the user, and send messages to the user using Websocket as communication channel. The main functionalities of webchat include provisions to citizens for raising a complaint, giving feedback, and rating a service.

Requirements:-

Prior Knowledge of Javascript.
Prior Knowledge of NodeJS
Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.
Prior Knowledge of PostgresSQL
Prior Knowledge of Kafka and related concepts like Producer, Consumer, Topic, Kafka Streams etc.
Prior knowledge of XState library. Please refer the following link:
XState Core Chatbot | Basic Introduction to XState

Features:

Raise a complaint
Provide a feedback
Provide rating on a service.
Notifications to citizen after receiving complaint/feedback/rating.

Input to Chatbot

Example:- Refer the following file
https://github.com/egovernments/DIGIT-Dev/blob/CITIZEN_FEEDBACK_WEBCHAT/core-services/xstate-webchat/webchatbot-request.json

Chatbot input JSON Format:

{
"message": {
"type": "text",
"input": "1"
},
"user": {
"mobileNumber": "7878787878"
},
"extraInfo": {
"filestoreId": "917834811114",
"applicationId": "PB-MT-107-000754",
"comments": "User complaint comments"
}
}

Explanation for fields:

user:- stores information about sender of message
mobileNumber:- Mobile number of sender
Message: represents user sent message details
- type:- type of message ex:- text,image
- input:- the actual message body sent by the sender
extraInfo
- Object to keep extra information that may be used while sending response to user in last stage, ex:- source mob number. All the details which is not mentioned should be kept here. Chatbot will ignore if any new value stored here.

Send chatbot output message to user

{
    "message": "Last Bill Generated BILL-157608 is Rs. 604. Do you want to report this as incorrect?",
    "step": "intermediate",
    "optionType": "button",
    "option": [
        {
            "key": "1",
            "value": "Yes"
        },
        {
            "key": "2",
            "value": "No"
        }
    ]
}

Configuration for each state:

id : id of state,ex:- citizenComplaint
initial : initial state, ex:- complaintCategory
onEntry : function to be executed on entry, ex:- onEntry: assign((context, event) => { const message = dialog.get_message(messages.complaintMenu.prompt, context.user.locale); const grammer = dialog.constructContextGrammer(messages.complaintMenu.options.list, messages.complaintMenu.options.messageBundle, context.user.locale); context.grammer = grammer; dialog.sendMessage(context, message, true); })
target : target state
invoke : make a call to an external service
Refer this file for an example
https://github.com/egovernments/DIGIT-Dev/blob/CITIZEN_FEEDBACK_WEBCHAT/core-services/xstate-webchat/nodejs/src/machine/citizen-complaint.js

Modifying the chat flow

The workflow for the chatbot uses the concept of finite state machines which is developed using Xstate library Machine. The workflow implementation is present in nodejs/src/machine/. To modify the workflow, please make changes to those file.

Modifying messages without any change to workflow flow could be handled by just modifying the files in messages directory.

Any external api calls are written as part of files present in nodejs/src/machine/service which would get called from the state machine.

Localization

The message temples are saved in the following file. In case any more messages are required to be added, it should be done in the same file.
https://github.com/egovernments/DIGIT-Dev/tree/CITIZEN_FEEDBACK_WEBCHAT/core-services/xstate-webchat/nodejs/src/machine/messages

Flow Diagram:

High Level Diagram of chatbot interactions

Flow Diagram of Chatbot-User conversation

Flow Diagram of Chatbot notifications

Steps for testing

Webchat application uses TCP protocol based Websockets as communication channel between client and server.A WebSocket is a persistent connection between a client and server. WebSockets provide a bidirectional, full-duplex communications channel that operates over HTTP through a single TCP/IP socket connection. As chabot requires a real-time event driven message exchange between client and server so Websocket is preffered for this use-case over HTTP REST based communication.

Most of the current API testing tools like Postman, Swagger etc. have very good support for HTTP APIs but they offer limited fatures for Websocket APIs. Postman currently supports Websocket API request for testing and debugging of the appplication but does not allow to create and share Wbsocket API as Postman collection. API request to be used for webchat interaction is present in ./nodejs/webchatbot-request.json.

The URL for testing is as follows:

ws://dev.digit.org/xstate-webchat