> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/local-governance/v2.7/platform/configure-digit/services-overview/core-services/xstate-core-chatbot/xstate-chatbot-integration-document.md). # XState-Chatbot Integration Document ## Overview The [XState-Chatbot](https://github.com/egovernments/core-services/tree/xstate-chatbot/xstate-chatbot) is a revamped version of the [chatbot](https://github.com/egovernments/core-services/tree/master/chatbot), 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 The integration of PGR with a chatbot can be enabled and disabled by making changes in this [file](https://github.com/egovernments/core-services/blob/xstate-chatbot/xstate-chatbot/nodejs/src/machine/service/service-loader.js).\ 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](https://github.com/egovernments/eGov-infraOps/blob/master/helm/environments/qa.yaml#L207) 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’. **Configuration of city and locality search with nlp-search engine** To enable the fuzzy search for city and locality selection in PGR complaint flow\ The variable **nlp-geoSearch** has to be set true in the [environment file](https://github.com/egovernments/DIGIT-DevOps/blob/master/deploy-as-code/helm/environments/qa.yaml#L221).\ To use the nlp-search engine with xstate chatbot, make sure that a stable build is deployed and all the mdms data are present for that particular environment.\ To know more about the nlp-search engine service please refer to the Reference document section. **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*** 2. Upload the image into filestore server. Use the upload file API from this postman collection([https://www.getpostman.com/collections/bdb059c5af698f0d81d6)](https://www.getpostman.com/collections/bdb059c5af698f0d81d6) 3. For PGR information image mention the filestore id [here](https://github.com/egovernments/DIGIT-DevOps/blob/master/deploy-as-code/helm/environments/qa.yaml#L219) in the environment file. 4. For open search, the information image mentions the filestore id [here](https://github.com/egovernments/DIGIT-DevOps/blob/master/deploy-as-code/helm/environments/qa.yaml#L220) 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. {% file src="/files/-MgiGjchMmswC6q2C-Je" %} Value First Whatsapp User Guide {% endfile %} #### 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](https://github.com/egovernments/core-services/blob/develop/xstate-chatbot/nodejs/src/machine/service/service-loader.js). 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 in the list present in the [environment](https://github.com/egovernments/DIGIT-DevOps/blob/master/deploy-as-code/helm/environments/qa.yaml#L216) file. **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. Add the message bundle, validation and service code for locality searcher in [egov-bill](https://github.com/egovernments/core-services/blob/develop/xstate-chatbot/nodejs/src/machine/service/egov-bill.js) and [egov-receipt](https://github.com/egovernments/core-services/blob/develop/xstate-chatbot/nodejs/src/machine/service/egov-receipts.js) file. | Environmental Variables | Description | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WHATSAPP_BUSINESS_NUMBER` | The mobile number to be used on server | | `VALUEFIRST_USERNAME` | Username for configured number for sending messages to user through whatsapp provider API calls | | `VALUEFIRST_PASSWORD` | Password for configured number for sending messages to user through whatsapp provider API calls | | `GOOGLE_MAPS_API_KEY` | Maps API key to access geocoding feature | | `ROOT_TENANTID` | Contains state level tenantid value | | `SUPPORTED_LOCALES` | This variable contains the list supported language in chatbot. If there is a need to add new language in chatbot, then its respective locale need to add in this list. | | `PGR_VERSION` | Contains PGR version value to use (i.e v1 or v2) | | `PGR_UPDATE_TOPIC` | Depends on PGR version respective PGR update kafka topic name should mention here. Example: If `PGR_VERSION: 'v2'` then `PGR_UPDATE_TOPIC: 'update-pgr-request'` | | `BILL_SEARCH_LIMIT` | Limit for showing maximum number of bills on search. | | `RECEIPT_SEARCH_LIMIT` | Limit for showing maximum number of receipts on search. | | `COMPLAINT_SEARCH_LIMIT` | Limit for showing maximum number of complaints on search. | | `BILL_SUPPORTED_MODULES` | Contains the list of modules to be use for bill payment and receipts search. | | `INFORMATION_IMAGE_FILESTORE_ID` | Contains the filestoreid of informational image, which shows how to share the user current location. | | `OPEN_SEARCH_IMAGE_FILESTORE_ID` | Contains the filestoreid of open search informational image, which shows how to use open search pay feature for bill payment | | `USER_SERVICE_HARDCODED_PASSWORD` | This variable contain fixed value of login password and otp. This value has to configured in *env*-secrets.yaml. | | `GEO_SEARCH` | Boolean flag to enable and disable city / locality nlp search | **Configuration of Telemetry File** Add this [telemetry file](https://github.com/egovernments/configs/pull/629/files) in [config repo](https://github.com/egovernments/configs/tree/DEV/egov-indexer) and mention the filename in the respective [environment yaml file](https://github.com/egovernments/DIGIT-DevOps/blob/master/deploy-as-code/helm/environments/qa.yaml#L263). #### **Searcher config file:** [configs/localitySearcher.yml at qa · egovernments/configs](https://github.com/egovernments/configs/blob/qa/egov-searcher/localitySearcher.yml) **Cron job mdms entry:** [RAIN-2768 Added entry in cron job api config file · egovernments/egov-mdms-data@30881ab](https://github.com/egovernments/egov-mdms-data/commit/30881ab4f759c8b607417be2047b46865ec953ef) #### **Localisation for PGR service** Information Images for PGR and Open Search ![Location Share Image](/files/-MgiGjctC0KqjwVSad9l) ![Open Search Image](/files/-MgiGjcvUsug087Wijrq) ## Reference Docs ### Doc Links | Title | Link | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Chatbot Message Localisation | [Chatbot Message Localisation Doc](/local-governance/v2.7/platform/configure-digit/services-overview/core-services/xstate-core-chatbot/xstate-chatbot-message-localisation.md) | | nlp-search engine | [NLP Engine Service](/local-governance/v2.7/platform/configure-digit/services-overview/core-services/nlp-engine-service.md) | ### API List | Title | Link | | ------------------------ | ------------------------------------------------------------- | | /xstate-chatbot/message | | | /xstate-chatbot/reminder | | | /xstate-chatbot/status | | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.digit.org/local-governance/v2.7/platform/configure-digit/services-overview/core-services/xstate-core-chatbot/xstate-chatbot-integration-document.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.