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 handles basic form-filling within a chat flow by collecting user information and making API calls to the rainmaker backend services to meet user needs. It utilizes StateCharts, similar to State Machines, to manage the user's state in the chat flow and store provided information. XState, a JavaScript implementation of StateCharts, is employed to code all chat flows.

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

XState - Basic Introduction

XState is a JavaScript implementation of StateCharts. There is detailed documentation available to study XState. Some of the XState concepts 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

Below are some tips for using XState, which have been followed throughout the pilot chat flows:

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

2. Ensure that each state has a unique ID value to avoid duplicates. Having duplicate IDs can cause unexpected behavior in the application.

3. Surround any actions, such as onEntry, with 'assign' for effective handling of state changes and updates.

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 back-end 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.

Chat Flow

Below are some guidelines for coding chat interactions using XState:

1. Interaction with the user, such as sending a message or processing incoming messages, should be coded as states in the State Machine.

2. It's recommended to test any chat flow using the provided react-app. Follow the instructions in the README file of the react-app for testing.

3. Follow standard patterns when coding chat interactions. These patterns are explained below and can also be studied by browsing through the code of pilot use cases like PGR and Bills.

4. Chat states should only contain dialogue-specific code. Backend service-related code should be written in separate files, such as ...-service.js.

5. Code that doesn't involve asynchronous API calls can be written within the onEntry function or action.

6. If an API call is needed, follow the invoke-onDone pattern. Write asynchronous functions in separate service files, and process the consolidated data returned by these functions in the dialogue file's state.

7. Helper functions should be written in the dialog.js file. It's advisable to use these functions instead of writing custom logic in dialogue files whenever possible.

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 stores, updates and reads the user’s state in a datastore. 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 data (any sensitive data like the name and mobile number of a user are removed) before storing it in the datastore.

2. Repository: It is the datastore that stores the user states. To reduce dependency, an in-memory repository is also provided configured using environment variables. So to run the chatbot service, Although PostgreSQL is not a strict requirement, using it as the repository provider is recommended.

3. Channel Provider: It supports multiple WhatsApp Providers. Any one of the providers is configured for use. A separate console WhatsApp Provider is present for the developer to test the chatbot server locally. Additionally, a Postman collection is provided to simulate receiving messages from users to the server..

4. Localisation: Messages to be sent to the user are stored within the chatbot. Here, the localisation service is not used. The messages are typically present near the bottom of the dialogue files. A separate localisation-service.js is provided to retrieve the messages for the localisation codes 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: Simplifies initial dialogue development by allowing configuration of a dummy service instead of coding API calls to backend services. This can be set up via environment variables and modifying the service-loader.js file.

6. Telemetry: Chatbot logs telemetry events to a Kafka topic with the provision to mask any sensitive data before indexing the events onto ElasticSearch by egov-indexer. Below are the list of events that get logged:

   • Incoming message

   • Outgoing message

   • State transitions

Overview

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 here to access the sheet containing all messages with the localisation codes.

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.

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 localisation 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

The XState-Chatbot is a revamped version of the chatbot, which provides functionality to the user to access PGR module services like filing complaints, tracking complaints and notifications from WhatsApp. It allows the user to view receipts and pay bills for Property, Trade Licence, Fire NOC, 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 searching and viewing bills/past payment receipts and to improve speed and convenience for bill payments. 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 counter.

Integration Approach

Integration of New Whatsapp Provider

Whatsapp provider is a third-party service that acts as an intermediary between the user WhatsApp client and the XState-Chatbot server. All messages coming/going to/from the user pass through the WhatsApp provider. The chatbot calls the WhatsApp provider to send messages to the user. When a user responds to any WhatsApp message the WhatsApp provider calls the Chatbot service configured endpoint with details like messages sent by the user, the sender 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. The final output from the chatbot is also 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

The integration of PGR with a chatbot can be enabled and disabled by making changes in this file. By exporting the respective PGR service file, the PGR service feature can be sable and vice versa.

Configuration Details

Configuration of PGR version in chatbot

To configure the PGR module to use in Xstate-chatbot - the below variable values need to change in the environment file as per the requirement.

• pgrVersion

• pgrUpdateTopic

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

Adding Information Images 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

2. Upload the image into the filestore server. Use the upload file API from the Postman collection here.

3. For the PGR information image mention the filestore id here in the environment file.

4. For open search, the information image mentions the filestore id here in the environment file.

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

The integration of the Bill payment and receipt search feature with the chatbot is enabled and disabled by making changes in this file. The payment and receipt search feature can be enabled and vice versa by exporting the respective bill service and receipt service file.

Configuration of module for Bill payment and Receipt search

To configure the list of modules to appear as an option for payment and receipt, Add the module business service code to the list present in the environment file.

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

Add the message bundle, validation and service code for the locality searcher in egov-bill and egov-receipt files.

Configuration of Telemetry File

Add this telemetry file in the config repo and mention the filename in the respective environment yaml 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