GREEN-API demo chatbot#
Python demo chatbot is an example of chatbot created with Python chatbot Whatsapp library, which is a library designed specifically to build Whatsapp chatbot provided by API service Green API.
The chatbot provides a demonstration of APIs available for users - sending messages of texts, images, locations, files, and contacts.
Scan the following QR to start or follow the link to start a chat with the bot to see how it works:
To launch this chatbot on a personal Whatsapp account user is encouraged to follow the guideline:
1. Installation#
Preparing the python environment to run the project is required. To set up an environment one should go to the python official website and download the latest release compatible for the OS.
This action will download the installer, which one will need to open and start. Follow the guidelines in the installer and complete the installation.
To check if the environment was established correct, run the following command in cmd / bash:
python --version
Python 3.N.N
Or if one's familiar with distributed version control system s/he can clone the project by running:
git clone https://github.com/green-api/whatsapp-demo-chatbot-python.git
cmd to the path and type in Enter. Then, use the package manager pip to install the whatsapp-chatbot-python and other modules required to run the code.
The following command calls the pip package manager and installs the modules to the environment. The package manager is installed in the environment by default.
python -m pip install -r requirements.txt
2. Launching a chatbot#
To use the chatbot on Whatsapp account one must sign up to personal cabinet, as the chatbot is based on the APIs provided. There's a guideline available for new users how to set up the account and get parameters for working with API, mainly:
idInstance
apiTokenInstance
bot.py file and fill up the account's parameters with idInstance and apiTokenInstance values correspondingly in the 23th line. Initialization is essential to synchronize with one's Whatsapp account: id_instance = ''
api_token_instance = ''
bot = GreenAPIBot(id_instance, api_token_instance)
python bot.py
The parent library of the chatbot whatsapp-chatbot-python will change the settings of the associated account by calling SetSettings API to.
The following settings will turned, namely:
"incomingWebhook": "yes",
"outgoingMessageWebhook": "yes",
"outgoingAPIMessageWebhook": "yes",
The settings update will take a few minutes, so the associated instance will be unavailable during the time. The messages sent to the chatbot meanwhile will not be processed.
Then there will be deletion of the old notifications, another process invoked by the parent library whatsapp-chatbot-python, which is essential to make sure chatbot will not process the messages from the already opened chats.
After the initialization is completed, chatbot is ready to answer the messages. The whole process of initialization will take up to 5 minutes.
To stop the chatbot hover the cmd / bash from the current directory and click Ctrl + C
3. Setup#
The chatbot has default values for links to send files and images, but users can change them to their liking.
To do that, provide one link to the pdf/any other format file and one to jpg. Links can lead to cloud storage or open source. In the 101th line in the bot.py file:
def option_2(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
notification.api.sending.sendFileByUrl(
chatId=notification.chat,
urlFile='https://...png',
fileName='...png',
caption=f'{data["send_file_message"][user.language]}'
f'{data["links"][user.language]["send_file_documentation"]}',
)
urlFile="" and give it a name in the fileName="". Then it should look similar to the following:
def option_2(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
notification.api.sending.sendFileByUrl(
chatId=notification.chat,
urlFile='https://...somefile.pdf',
fileName='somefile.pdf',
caption=f'{data["send_file_message"][user.language]}'
f'{data["links"][user.language]["send_file_documentation"]}',
)
def option_3(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
notification.api.sending.sendFileByUrl(
chatId=notification.chat,
urlFile='https://...someimage.jpg',
fileName='someimage.jpg',
caption=f'{data["send_image_message"][user.language]}'
f'{data["links"][user.language]["send_file_documentation"]}',
)
4. Usage#
If everything was set up correct, the code is running and the Whatsapp chatbot should be working on the number associated with instance. Importantly, instance must be authorized in the personal cabinet for code to work.
Let's try to send a message to chatbot!
Any message will invoke the bot to start a conversation. As bot provides the service on two languages - English and Russian - even before welcoming a user, a choice of language is encouraged:
[1] - English
[2] - Русский
Welcome the to the GREEN-API chatbot, user! GREEN-API provides the following kinds of message services. Type in a number to see how the corresponding method works
1. Text message 📩
2. File 📋
3. Image 🖼
4. Contact 📱
5. Location 🌎
To restart the conversation type stop
For exapmle, by sending 1 to chatbot the user will get:
This message is sent via sendMessage method
If you want to know how the method works, follow the [link](../../../api/sending/SendMessage.md)
Sorry, I cannot understand what you are talking about, type menu to see the available options
Thank you for using the GREEN-API chatbot, user!
5. Code structure#
The main part of the code is contained within the bot.py file. It imports the chatbot library, on which the chatbot is based:
from whatsapp_chatbot_python import (
BaseStates,
GreenAPIBot,
Notification,
filters,
)
bot = GreenAPIBot(
ID_INSTANCE,
API_TOKEN_INSTANCE
)
@bot.router.message(type_message=filters.TEXT_TYPES,
state=None)
user class is within the user_manager.py file and has 2 fields: @dataclass
class User:
language: Optional[str] = None
ts: Optional[datetime] = None
id, chosen language, authorization status, and timestamp of last interaction with bot. Every field has a role in the logic, which will be explained later. So, returning to bot.py, after the user sends a first message to the chatbot, there's checking if the user has active chat with the bot on the server side. If not, new user is created and the state of the chat is set to ACTIVE.
notification.state_manager.update_state(notification.sender,
States.ACTIVE.value)
user = manager.check_user(notification.chat)
notification.answer(data['select_language'])
notification.answer() is the function of the chatbot library, it takes the parameters of user and sends a text message to the assigned user. The data['select_language'] is the text we prepared for the chatbots answers, which is: "1 - English\n2 - Русский"
The chatbot sees that user with such number has active chat by checking the filter state=States.ACTIVE.value. The function sets the user's language field and sets the value of the state to state=States.LANGUAGE_SET.value, letting the bot to know that the language of interaction in this chat is already selected:
@bot.router.message(type_message=filters.TEXT_TYPES,
state=States.ACTIVE.value,
text_message=['1', '/1', '1.', '1 '])
def set_eng(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
user.set_language('eng')
notification.state_manager.update_state(notification.sender,
States.LANGUAGE_SET.value)
notification.answer(
f'{data["welcome_message"][user.language]}'
f'{notification.event["senderData"]["senderName"]}'
f'! '
f'{data["menu"][user.language]}'
)
['1', '/1', '1.', '1 '] in case the user sent redundant symbols. After that the chatbot sets state of the chat to state=States.LANGUAGE_SET.value and expects commands 1-5 from the user So, if user sends 1, router will proceed to the following line:
@bot.router.message(type_message=filters.TEXT_TYPES,
state=States.LANGUAGE_SET.value,
text_message=['1', '/1', '1.', '1 '])
def option_1(notification: Notification) -> None:
user = manager.check_user(notification.chat)
if not user: return message_handler(Notification)
notification.answer(
f'{data["send_text_message"][user.language]}'
f'{data["links"][user.language]["send_text_documentation"]}'
)
This message is sent via sendMessage method
If you want to know how the method works, follow the [link](../../../api/sending/SendMessage.md)
data.yml file and loaded to the bot.py by following: with open("data.yml", 'r', encoding='utf8') as stream:
data = safe_load(stream)
data['welcome_message']['eng'] as the welcome message in English, and data['welcome_message']['ru'] as in Russian: welcome_message:
ru: "Добро пожаловать в GREEN-API чатбот, "
eng: "Welcome the to the GREEN-API chatbot, "
ts is updated: def update_ts(self):
self.ts = datetime.now()
if diff > 120:
self.users.get(chat).set_language(None)
6. Message handling#
As chatbot states, all the messages were sent by 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 library whatsapp-chatbot-python, where methods of sending and receiving messages is already intergarted, that's why the process of receiving messages is automated, and sending text messages is simplified.
For example, chatbot answers the person who sent a message by following:
notification.answer(data["select_language"])
notification.api.sending.sendContact(
chatId=notification.chat,
contact={
"phoneContact": notification.chat.split("@")[0],
"firstName": notification.event["senderData"]["senderName"],
},