Objective

This document aims to facilitate communication between the software developers and whoever is localising the chatbot messages. The goal is to make it clear and as unambiguous as possible.

The Google Sheet containing all the messages with the codes is:

https://docs.google.com/spreadsheets/d/1j5ldAHbwdR2jTCgUuxlrEdLKDZuHmkJg589v7OML-eA/edit?usp=sharing - Connect to preview

Structure of the project

The project is organised such that all the messages are contained within the files present inside the /machine directory. /service directory, which is present inside it, also includes files that could contain localization messages.

Guidelines to be followed by developers

(According to the standard pattern followed in the project, all the localization messages will be present near the end of the file in a JavaScript object named “messages”.)

Developers will be the ones first filling up the sheet with codes (and the English version of the messages). Below are the guidelines to be followed when writing the codes in the sheet:

1. The standard separator to be used is .(dot)

2. The first part is the filename—Eg: “pgr.”, when the filename is pgr.js.

3. Use “service.” as a prefix when the file is present inside the /service directory.

   1. In the /service directory, filenames are like egov-pgr.js

   2. For localization messages contained in those files, instead of writing “egov-pgr” just write “pgr”

   3. So the prefix for such files would be “service.pgr.”

4. All the message bundles would be present in the “messages” object near the end of the file. They have been organized in a pattern in the JS object like fileComplaint.complaintType2Step.category.question

   1. The corresponding localization code for such a message bundle in the sheet would be “pgr.fileComplaint.complaintType2Step.category.question”, where the first “pgr.” is added as the prefix for the file name.

Guidelines for writing messages

Once the localization codes have been written correctly (and the English version of the messages) in the sheet, it should be easy to add the new message in the corresponding new column. Some guidelines to follow when adding new messages:

1. The parameter names are written within (double curly brackets)

2. The content inside these curly brackets should be written in English even when writing messages for any new language

Overview

Goal: To onboard developers onto the XState-Chatbot code base so that they can modify existing flows or create new ones.

This document sticks to explaining the chatbot's core features and does not dive into the use cases implemented by the chatbot. There is another document dedicated to it.

Prerequisites

• NodeJS

• XState

• PostgreSQL

• Kafka(optional)

Key Functionalities

• Build a chat flow to facilitate a user to interact with rainmaker modules

• Link a chat flow with backend services

Deployment Details

1. Deploy the latest version of xstate-chatbot

2. Configure /xstate-chatbot to be a whitelisted open endpoint in zuul

3. Add indexer-config to the egov-indexer to index all the telemetry messages

Other configuration details are mentioned as part of the XState-Chatbot Integration Document.

Overall Philosophy of Chatbot

This chatbot solves the basic form filling aspect of a chat flow. By collecting the information from the user, an API call can be made to the rainmaker backend services to fulfill what the user wants to do. It uses the concept of StateCharts (similar to State Machines) to maintain the state of the user in a chat flow and store the information provided by the user. XState is a JavaScript implementation of StateCharts. All chat flows are coded inside the XState framework.

This chatbot does not have any Natural Language Processing component. In the future, we can extend the chatbot to add such features.

Basic Introduction to XState

XState is a JavaScript implementation of StateCharts. There is detailed documentation available to study XState. Few of the concepts of XState that are used in Chatbot are listed below. Basic knowledge of these concepts is necessary. It can also be learned while going through the chat flow implementation of pilot use cases of PGR and Bills.

1. State

   1. State Nodes

   2. Hierarchical State Nodes

2. Actions

   1. onEntry

   2. invoke…onDone…onError

3. Guard Conditions

Few tips about using XState. These have been followed throughout the pilot chat flows.

1. If we want to move to any state which is not at the same hierarchical level, then we should assign it a unique id value. If it has an id value, we can address it using the # qualifier in the target attribute.

2. As id should be unique, please make sure there aren’t multiple states with the same id value. If there is a duplicate, the machine won’t function as expected.

3. Any actions(like onEntry) should be surrounded by assign.

assign( (context, event) => { ... } )

This would include almost all functions except the guard condition code snippets.

Understanding the Chat Flow

All the interactions with the user - sending a message to the user and processing an incoming message from the user is coded as a state in the State Machine. It would be a nice start to test any chat flow with the supplementary react-app provided for the developers to execute the state machine locally. (Please follow the guidelines in the README of the react-app.)

We have followed few standard patterns to code any chat interaction. Please try to follow these patterns to code any new chat flow. These patterns are explained below. You can also study those by browsing through the code of the pilot use cases of PGR and Bills.

1. The chat states would only include dialog-specific code. Any code related to backend service should be written as a part of a separate …-service.js file.

2. Any code that doesn’t include any asynchronous API call can be written as a part of the onEntry function or action.

3. If the function needs to make an API call, that would have to be written with the invoke-on Done pattern. The asynchronous function should be written as a part of the service file. The consolidated data returned by it can be processed in the state of the dialog file.

4. Helper functions are written indialog.jsfile. It is advised to use those functions as much as possible rather than writing any custom logic in dialog files.

Scaffolding

Apart from the chat flow and its backend service API calls, few other components are present in the project. These components do NOT need to be modified to code any new chat flow or changing an existing chat flow. These components with a short description for each are listed below:

1. Session Manager: It manages sessions of all the users on a server. It will store the user’s state in a datastore, update it, and read it when any new message is received on the server. Based on the state of the user, it will create a state machine and send the incoming message event to the state machine. It sanctifies the state (any sensitive data like the name and mobile number of a user are removed) before storing the state to the datastore.

2. Repository: It is the datastore where the states of the users get stored. To reduce dependency, an in-memory repository is also provided, which can be used by configuring an environment variable. So to run the chatbot service, PostgreSQL isn’t a hard dependency, but it is advisable to use the PostgreSQL repo provider.

3. Channel Provider: There can be many different WhatsApp Providers. Any one of the providers will be configured to be used. A separate console WhatsApp Provider is present for the developer to test the chatbot server locally. Postman collection to mimic receiving messages from a user to the server is present in the project directory.

4. Localization: Every message to be sent to the user is stored within the chatbot. Localization service is not being used. These messages are present near the bottom of the dialog files. A separate localization-service.js is provided to get the messages for the localization codes for the messages that are not owned by the chatbot. For example, the PGR complaint types data is under the ownership of the PGR module, and the messages for such can be fetched from the egov-localization-service using the functions provided in the localization-service.js.

5. Service Provider: To ease the initial dialog development, instead of the coding API calls to the backend services, we can configure the chat flow to use a dummy service. This can be configured using an environment variable and modifying the service-loader.js file.

6. Telemetry: Chatbot logs telemetry events to a kafka topic. (Any sensitive data will get masked before indexing the events onto ElasticSearch by egov-indexer.) Following events get logged:

   1. Incoming message

   2. Outgoing message

   3. Transition of state

Overview

is a revamped version of the , which provides functionality to the user to access PGR module services like file complaint, track complaint, notifications from whats app, It allows the user to view receipts and pay the bills for Property, Trade Licence, FireNOC, Water and Sewerage and BPA service module.

Key Functionalities

• File PGR complaint

• Track PGR complaint

• Support images when filing complaints

• Notifications to citizen when an employee performs any action on the complaint

• Allow user to search and pay bills of different modules.

• Allow user to search and view receipts of different modules.

• Allow user to change the language of their choice to have a better experience.

• Put user interactions on an elastic search for Telemetry.

Integration

Integration Scope

XState chatbot can be integrated with any other module to improve the ease of search and view bills/past payment receipts and to improve speed and convenience for bill payment. It can be integrated with the PGR module for easiness of creation and tracking of the complaint.

Integration Benefits

• Increase in convenience and ease of making the bill payment.

• Increase in no. of users opting for online payment.

• Improvement in demand collection efficiency

• Creating an additional channel for payment.

• Remove dependency on mobile/web app or counter.

Integration Details

Integration of New Whatsapp Provider

Whatsapp provider is a third-party service that works in the middle of a user's WhatsApp client and XState-Chatbot server. All messages coming/going to/from user pass through WhatsApp provider. Chatbot calls WhatsApp provider to send messages to the user. When a user responds with any WhatsApp message the WhatsApp provider calls Chatbot service’s configured endpoint with details ex:- user sent message, sender’s number etc.

If any new WhatsApp provider is to be used with a chatbot, code must be written to convert the provider’s incoming messages to the format that the chatbot understands and also final output from the chatbot should be converted to WhatsApp provider’s API request format.

Currently, the XState-Chatbot service is using ValueFirst as the WhatsApp Provider. This will require provider-specific environment variable to be configured. If the provider changes then, all these environment variable will also change. Few of those environment variables are stored as secrets, so these values need to be configured in env-secrets.yaml.

As this is a revamped version of the chatbot service, all of the secrets should already be present. There is no need to create new secrets.

Integration of PGR complaint feature in XState-Chatbot

Configuration of PGR version in chatbot

• pgrVersion

• pgrUpdateTopic

To configure PGR v2 in XState chatbot then pgrVersion should be ‘v2' and pgrUpdateTopic should be 'update-pgr-request’.

Adding Information Image in PGR complaint creation

To configure the filestoreid for informational image follow the steps mention below

Configuration of Compliant status template messages

For Compliant status update notifications to citizen when an employee performs any action on the complaint.

For example:

a) if supportedLocales: process.env.SUPPORTED_LOCALES || 'en_IN,hi_IN'

then valuefirst-notification-resolved-templateid: "12345,6789"

b) if supportedLocales: process.env.SUPPORTED_LOCALES || 'hi_IN,en_IN'

then valuefirst-notification-resolved-templateid: "6789,12345"

Integration of Bill Payment and Receipt Search feature in Xstate-Chatbot

Configuration of module for Bill payment and Receipt search

For example: If bill-supported-modules: "WS, PT, TL" then Water and Sewerage, Property, Trade license module would appear for bill payment and receipt search.

Configuration of Xstate-Chatbot localisation message

XState-Chatbot does not have any MDMS data, nor does it store any messages in localization-service. If any message needs to be modified, the changes will have to be made in the source code, then build the new docker image and deploy it. For Configuration details of the XState-chatbot localisation message please refer to the links in Reference Docs.

Configuration of Telemetry File

Reference Docs

Doc Links

API List