Let's start developing chatbots with a basic simple chatbot. It will not gather any data or work with any third-party API, a simple "send the word - get the answer" type.
First, because API.chat chatbot is a state-machine at its core we start with designing a simple state-machine flow on paper or any public flowchart software.
Design chatbot flow
All chatbots begin in Start state. The user will be put in that state when he writes anything to the chatbot for the first time. This is the place where we can welcome him, and ask what kind of system he uses.
Let's begin with the chatbot scenario.
Create the chatbot scenario
1. We will start with a simple single-state scenario. On any message (including /start) it will show a welcome message and two buttons. We can use Markdown and === symbol in transition body will split the response message into two messages.
the transition could be read as such:
On any (*) message, change user state to Start, send reply "Welcome to VSCode shortcuts helper", then send "Please choose your operation system" and show keyboard [Windows][MacOS]
2. Let's add a second state where we process user replies. We add 3 new states: ChoosOS, StartWindows, StartMacOS.
Let's read ChooseOS transitions from top to bottom:
On message contains windows, change user state to StartWindows, send reply "What section you need shortcuts of?" and show multiline keyboard. Comma (,) split buttons in one row, semicolon (;) split buttons in rows if supported by messenger.
On message contains MacOS, change user state to StartMacOS, send reply "What section you need shortcuts of?" and show the multiline keyboard.
On any other (*) message, change user state to ChooseOS, send reply "Please choose your operation system" and show keyboard [Windows][MacOS]
After any of the first two transitions, the user will end up in the corresponding state with a visible keyboard, and the chatbot will await some kind of reply from him.
3. A lot of duplication code here though, let's eliminate it using no-stop attribute.
Note that <transition input="windows" next="StartWindows" no_stop="true"/> became navigational transition - it does not provide any response to the user anymore.
Let's read how chatbot will behave from the beginning:
On any (*) message, change user state to ChoseOs, save reply "Welcome to VSCode shortcuts helper" for later, then process user input again.
On message contains windows, change user state to StartWindows, then process user input again.
On message contains MacOS, change user state to StartMacOS, then process user input again.
On any other (*) message, change user state to ChooseOS, send all previously saved replies in this chain, then send reply "Please choose your operation system" and show keyboard [Windows][MacOS]
In StartWindows, StartMacOS
On any (*) message, change user state to StartWindows/StartMacOS, send all previously saved replies in this chain in this chain, then send reply "What section you need shortcuts of?" and show the multiline keyboard.
Сonsecutive no-stop transitions form a chain. Chains in API.chat have a hard limit of 15 steps in it. Let's look a bit close at how these chains are shown to the user. Here is a listing of talks with the chatbot.
And that what happens if we send "windows" as the first message, the chatbot will jump all the way to StartWindows and end there.
4. Next let's add transitions to catch our buttons. We can use either keyword or exact attribute. We will do both for demonstration purposes.
I omit replies for now to save space.
The difference between keywords and exact attribute is that the first one will trigger transition if the user message contains input and the second one - only on exact 1 to 1 match.
A pending_keyboard="Menu" attribute will show a Menu button after the answer. This button will trigger any (*) transition to show all options.
One more chat listing. If the user inputs "File management on windows" from the Start it will first trigger on windows keyword, then on management keyword, and show the proper answer.
If the user sends File management, the chatbot will not recognize such input and trigger on any (*) transition. After the selection of Windows, the user will be prompted to input File management again. This is a limitation of scenarios that will be explored in future articles.
5. Finally let's add original documents and fill responses
We added Show all options to the keyboard and corresponding transition to show an original document. Note the render_url="true" attribute which is used to show a document preview if messenger supports it.
That was a quickstart on how to create a basic chatbot, without any integrations, data storage, or complex logic in API.chat XML scenario. Now we can deploy chatbot, connect telegram and expand it even more.