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 unambiguous.

Click on the link to the google sheet below to access all the messages with the codes:

Click here to download the file.

Message Localisation Details

Project Structure

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.

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

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

   • 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

   • 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.

Message Writing Guidelines

Once the localization codes have been written correctly (and the English version of the messages) in the sheet, it is 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.

Chatbot Fundamentals

This chatbot solves the basic form-filling aspect of a chat flow. By collecting the information from the user, an API call is made to the rainmaker backend services to fulfil the user requirements. 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. Some concepts of XState used in the 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 in PGR and Bills.

1. State

   • State Nodes

   • Hierarchical State Nodes

2. Actions

   • onEntry

   • invoke…onDone…onError

3. Guard Conditions

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

1. To move to any state which is not at the same hierarchical level, assign a unique ID value. If it has an ID value, address it using the # qualifier in the target attribute.

2. Since the ID should be unique, make sure there are no multiple states having the same ID value. If there is a duplicate, the application will not function as expected.

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

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

This includes almost all functions except the guard condition code snippets.

Pre-requisites

• 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 in the XState-Chatbot Integration Document.

Chat Flow

All the interactions with the user - sending a message to the user and processing an incoming message from the user are 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 applied some 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 dialogue-specific code. Any code related to the backend service should be written as a part of a separate …-service.js file.

2. Any code that does not 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 dialogue 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 dialogue files.

Scaffolding

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

1. Session Manager: It manages the 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 creates a state machine and sends 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 in 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 dialogue 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 dialogue development, instead of 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.) The following events get logged:

   1. Incoming message

   2. Outgoing message

   3. Transition of state

Overview

The is a revamped version of the , which provides functionality to the user to access PGR module services like file complaints, track complaints, 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 citizens when an employee performs any action on the complaint

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

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

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

• Put user interactions on an elastic search for Telemetry.

Integration Details

Integration Scope

The 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 apps or counters.

Integration Approach

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 the user pass through the 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:- the 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 the WhatsApp provider’s API request format.

Currently, the XState-Chatbot service is using ValueFirst as the WhatsApp Provider. This will require provider-specific environment variables to be configured. If the provider changes then, all these environment variables will also change. A 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 Details

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’.

Configuration of city and locality search with nlp-search engine

Adding Information Image in PGR complaint creation and Open search information image

To configure the filestoreid for an informational image follow the steps mentioned below

1. Download the images from the section Information Images for PGR and Open Search

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"

(Note: Both lists should not be empty - they must contain at least one element)

Configuration of push notification template messages with a button

Template messages with buttons are maintained in the same way as described in the previous section (Configuration of push notification template messages)

There are two types of button message

• Quick Reply

• Call To Action

The Value First document below provides more details.

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

Configuration of module for Bill payment and Receipt search

For example: If the applicable modules are defined in the variable - bill-supported-modules: "WS, PT, TL" -the defined modules will appear in the bill payment and receipt search. In the given example, the modules Water and Sewerage, Property Tax, and Trade license will appear for bill payment and receipt search.

Configuration of Telemetry File

Searcher config file:

Cron job mdms entry:

Localisation for PGR service

Information Images for PGR and Open Search

Reference Docs

Doc Links

API List