GREEN-API demo chatbot#

Java demo chatbot this is an example of a chatbot written using Java chatbot Whatsapp library, which is designed specifically for writing chatbots using the Green API service.

The chatbot clearly demonstrates the use of the API to send text messages, files, pictures, locations and contacts.

Scan the QR code or follow the link to start communicating with the chatbot

To launch a chatbot on your own Whatsapp account, follow the instructions:

1. Installation
2. Launching a chatbot
3. Setup
4. Usage
5. Code structure
6. Message handling

1. Installation#

To run the project you will need any IDE. Open your code editor and create a new project from source control. To do this, click file - new - Project from Version Control System. In the window that opens, enter the project address:

https://github.com/green-api/whatsapp-demo-chatbot-java.git

The environment for launching the chatbot is ready, now you need to configure and launch the chatbot on your Whatsapp account.

2. Launching a chatbot#

In order to set up a chatbot on your Whatsapp account, you need to go to your personal account and register. For new users, instructions are provided for setting up an account and obtaining the parameters necessary for the chatbot to work, namely:

idInstance
apiTokenInstance

Don't forget to enable all notifications in your instance settings. After receiving these parameters, find the class BotStarter and enter idInstance and apiTokenInstance into the createBot() method signature. Data initialization is necessary to link the bot with your Whatsapp account:

var bot = botFactory.createBot(
     "{{INSTANCE}}",
     "{{TOKEN}}");

You can then run the program by clicking start in the IDE interface or entering the following query on the command line:

mvn clean install exec:java -Dexec.mainClass=com.greenapi.demoChatbot.BotStarter
or
./mvnw spring-boot:run

The whatsapp-chatbot-java library contains a mechanism for changing instance settings using the SetSettings, which is launched when the chatbot is turned on.

All settings for receiving notifications are disabled by default; the chatbot will enable the following settings:

     bot.greenApi.account.setSetting(InstanceSettingsReq.builder()
            .incomingWebhook("yes")
            .outgoingMessageWebhook("yes")
            .outgoingAPIMessageWebhook("yes")
            .pollMessageWebhook("yes")
            .markIncomingMessagesReaded("yes")
            .build());

The process of changing settings takes several minutes, during which time the instance will be unavailable. Messages sent to the chatbot during this time will not be processed.

After the settings are applied, notifications about previously received incoming messages will be deleted. This process is also written in the library whatsapp-chatbot-java and starts automatically after changing the settings.

This is necessary so that the chatbot does not start processing messages from old chats.

After changing the settings and deleting incoming notifications, the chatbot will begin to respond to messages as standard. In total, this process takes no more than 5 minutes.

To stop the chatbot, use the keyboard shortcut Ctrl + C in the command line.

3. Setup#

By default, the chatbot uses links to download files from the network, but users can add their own links to files, one for a file of any extension pdf / docx /... and one for a picture.

Links must lead to files from cloud storage or public access. In the class Endpoints {:target="_blank"} the following code:

case "2" -> {
    answerWithUrlFile(incomingMessage, 
        YmlReader.getString(new String[]{"send_file_message", lang.getValue()}) +
        YmlReader.getString(new String[]{"links", lang.getValue(), "send_file_documentation"}),
        "https://images.rawpixel.com/image_png_1100/cHJpdmF0ZS9sci9pbWFnZXMvd2Vic2l0ZS8yMDIzLTExL3Jhd3BpeGVsb2ZmaWNlMTlfcGhvdG9fb2ZfY29yZ2lzX2luX2NocmlzdG1hc19zd2VhdGVyX2luX2FfcGFydF80YWM1ODk3Zi1mZDMwLTRhYTItYWM5NS05YjY3Yjg1MTFjZmUucG5n.png",
        "corgi.pdf",
        false);
    return currentState;

case "2" -> {
    answerWithUrlFile(incomingMessage, 
        YmlReader.getString(new String[]{"send_file_message", lang.getValue()}) +
        YmlReader.getString(new String[]{"links", lang.getValue(), "send_file_documentation"}),
        "https://...somefile.pdf",
        "somefile.pdf",
        false);
    return currentState;

All changes must be saved, after which you can launch the chatbot. To launch the chatbot, return to step 2.

4. Usage#

If the previous steps have been completed, then the chatbot should be working on your Whatsapp account. It is important to remember that the user must be authorized in personal account.

Now you can send messages to the chatbot!

The chatbot will respond to any message sent to your account. Since the chatbot supports several languages, before greeting the interlocutor, the chatbot will ask you to select a language of communication:

1 - English
2 - Kazakh
3 - Russian

Welcome to GREEN-API chatbot, user! GREEN-API provides the following types of data sending. Select a number from the list to check how the sending method works

1. Text message 📩
2. File 📋
3. Picture 🖼
4. Audio 🎵
5. Video 📽
6. ...

To return to the beginning write stop or 0

For example, by sending 1, the user will receive in response:

This message was sent via the sendMessage method.

To find out how the method works, follow the link
https://green-api.com/docs/api/sending/SendMessage/

Sorry, I didn't quite understand you 😔, write a menu to see possible options

Thank you for using the GREEN-API chatbot, user!

5. Code structure#

The main chatbot file is BotStarter {:target="_blank"}, it contains the main method and program execution begins with it. In this class, the bot object is initialized using the BotFactory class, the first scene is set, and the bot is launched.

public static void main(String[] args) {
     var context = SpringApplication.run(BotStarter.class, args); //Initiate the Spring application context
     var botFactory = context.getBean(BotFactory.class); //Import BotFactory bean from context

     var bot = botFactory.createBot( //Initialize the bot with INSTANCE and TOKEN parameters
     "{{INSTANCE}}",
     "{{TOKEN}}");

     bot.setStartScene(new Start()); //Setting the bot's starting scene

     bot.startReceivingNotifications(); //Start the bot
     }

The BotFactory class is a Bean that is configured in BotConfig. His task is to create a bot object. In the BotConfig configuration you can fine-tune the RestTemplate class for sending requests or substitute your own StateManager implementation if you have one. In this example, BotConfig uses standard, recommended default values.

@Configuration
public class BotConfig {

     @Bean
     public RestTemplate restTemplate() { //Standard Spring class for sending http requests.
         return new RestTemplateBuilder().build();
     }

     @Bean
     public StateManager stateManager() { //StateManager - interface for working with state.
         return new StateManagerHashMapImpl(); //StateManagerHashMapImpl is its standard implementation. You can write your own and substitute it if you do not want to store the data in a hashmap.
     }

     @Bean
     public BotFactory botFactory(RestTemplate restTemplate, StateManager stateManager) { //BotFactory bean to initialize the bot object
         return new BotFactory(restTemplate, stateManager);
     }
}

This bot uses scenes to organize its code. This means that the chatbot logic is divided into fragments (scenes), the scene corresponds to a certain state of the dialogue and is responsible for processing the response.

Each chat can only have one scene active at a time.

For example, the first scene Start is responsible for the welcome message. Regardless of the text of the message, the bot asks what language is convenient for the user and includes the following scene, which is responsible for processing the response.

There are 3 scenes in the bot:

• Scene Start - replies to any incoming message, sends a list of available languages. Launches the MainMenu scene.
• Scene MainMenu - processes the user's selection and sends the main menu text in the selected language. Launches the Endpoints scene
• Scene Endpoints - executes the user-selected method and sends a description of the method in the selected language.
• Scene CreateGroup - Scene creates a group if the user said he added the bot to his contacts. If not, returns to the "endpoints" scene.

Class SessionManager contains the isSessionExpired method which returns true if the user does not write to the bot for more than 2 minutes. It is used to set the starting scene again if the bot has not been written to for a long time.

Class YmlReader contains the getString() method which returns strings from the strings.xml file by key. This file is used to store the texts of the bot's responses.

6. Message handling#

As the chatbot indicates in its responses, all messages are sent via the API. Documentation of the sending methods.

When it comes to receiving messages, they've been handled by HTTP API. Documentation of the methods of receving messages.

The chatbot uses the library whatsapp-chatbot-java, where methods for sending and receiving messages are already integrated, so messages are read automatically, and sending regular text messages is simplified.

For example, a chatbot automatically sends a message to the contact from whom it received the message:

     answerWithText(incomingMessage, YmlReader.getString(new String[]{"select_language"}));

     greenApi.service.getAvatar(incomingMessage.getSenderData().getChatId());