Actions Types
The functionality of Actions is extensive and flexible in its application - therefore, a description of all the nuances of working with it is a huge and rather tedious document, which, nevertheless, must be familiarized with. If this is your first time reading it, just read it in its entirety. In the future, to clarify the details, you can refer to its individual parts as a reference. In this document, we will talk in detail about the types of Actions.
Creating a new Action is a step-by-step configuration wizard. The types and number of steps will depend on the type of Action you actually configure. Each Action can be assigned with an individual condition as well as corresponding success and failure messages. individual action's conditions affect ONLY whether the Action itself will work or not. Individual Action's conditions DO NOT affect the rest of the chain of added Actions.
To interrupt the entire chain, there is a separate Action - Action of Conditions.
❖ Action of Numbers
Action of Numbers - allows you to perform operations with data of numeric variables. Subtract, add and carry out other mathematical operations.
For more complex calculations, use Expressions (Expressions Guide).
Select "Action Numbers".
1. Specify the variable, for the Action you create, to work with.
2. Select one of the Operation Types.
For the convenience of working with data when Action is triggered, you will be prompted to use one of two types of actions:
2.1. "Change the Value" - in this case, the value you specified will be added (or subtracted if the value is negative) to the existing value of the variable.
2.2. "Set the Value" (Set) in this case, the value of the variable will be set equal to the value you specified, regardless of its original value (the data existed in the variable before, will be overwritten).
3. Specify the value.
The following data can be used as the specified value:
● Regular number (Any natural number, decimal or negative).
● Variable's macros (different one's or the same). To do this, a corresponding plug-in must be purchased in the bot - see the "Additional Information" section.
● Expression containing Numbers and / or macros. To do this, a corresponding plug-in must be purchased in the bot - see the "Additional Information" section.
● Macros or Expressions containing Macros and "Time" Functions. A link to the manual on Variables of Date and Time will be in the "Additional Information" section at the end of the document.
In this mode Action of Numbers can work with Date and Time variables. With the help of expressions or functions, these variables can be assigned values, including possibility to "add" time to the time that already set in the variable.
For example, the expression:{dt_add("%tvariable%", 3, "m")}
will calculate and set a date 3 months later than the existing one in the tvariable
variable.
Read more about Date and Time variables in the manual.
4. After that (if you purchased the "Conditions for Buttons" plugin for your bot), you will be prompted to enter a condition under which this Action will be triggered. You can also set corresponding messages for the case of non-fulfillment of this condition. The "Condition" is always an "Expression".
Macros and Expressions in Buttons.
Conditions.
To connect, go in your bot:☞ 🔐Admin | 🧩Extensions | 📂Buttons
Read more about "Conditions for Buttons" in Conditions guide.
Read more about Expressions in Expressions guide.
If the individual Action's condition entered here is not met, this is not an error, just this particular Action will not execute. The chain of execution of other Actions will not be interrupted and will continue its further execution.
The Condition itself and its messages are not required to be entered - click "Set Empty" if you do not need them in this case.
Next, you will be prompted to enter a message in case the Condition is not met. It is not mandatory to enter a message about the failure of the execution - click "Set Blank" if you do not need it in this case.
Next, you can enter a message that will be shown to the user if the Action is successfully executed.
In this message, special macros are available to show the changes that Action makes to the variable. It is especially useful when using random or variable accrual amounts. A combination macro is used for this:%varname_v%
where "varname
" is the name of the variable that was changed and amount of change ("delta") of which, you want to display.
Please note that these macros can be used in the "Expressions" of the Action itself.
Here's an example (although the use of expressions is not the subject of this tutorial).
Let's say you have 2 Actions:
Action 1. balance
= {-1 * randi(10, 200)}
- will assign a number from -10 to +200.
Action 2. invest
= {1 * %balance_v%}
as a result, the invest
variable will be added with amount AS BIG AS variable balance
was changed for.
Also, these macros can be used in GENERAL messages about success or failure for the entire chain of Actions.
It is not necessary to enter a message about the success of the execution - click "Set Empty" if you do not need it in this case.
After that, a new Action will be created and its data will appear as a message with inline control buttons in the chat with the bot.
❖ Action of Conditions
Action of Conditions - unlike the individual conditions of each Action, it allows interrupting further execution of the entire chain of Actions if its condition is not met.
Please note that the moment of its possible interruption will also depend on where exactly, in the chain of Actions, the "Action of Conditions" are placed. All previous Actions will be executed, all subsequent ones - will not.
This Action is created in the same way as it was described earlier.
1. You will be asked to add the Condition itself to be checked. The "condition", as in the previous case, is always an "Expression".
1.1 Then you need to enter a message that will be shown if the Action's Condition is not met (Error message). It is not mandatory to enter this message - press "Set Empty" if you do not need it in your case.
Sometimes, when adding a Condition to this Action, it is difficult to understand the mechanics of its operation, which does not allow us to clearly predict at what point this Action will be triggered. There is a small section in the "Guide on Conditions" that may facilitate understanding, in addition, there you can learn all the nuances of working with Conditions.
The button in which your Actions are added, in the overwhelming majority of cases, will contain its own messages - messages cotaining information for which the button was actually created. In this regard, it is necessary to determine the behavior of the button itself in the event of a condition failure.
Here you have two options:
● You can let the button show, to the user, those messages that were added - regardless of the non-fulfillment of the Condition.
● Or prohibit button from showing its messages if the Conditions are not met.
There are many user cases for each of the options.
❖ Action of Referrals
Action of Referrals - intended for making accruals (adding rewards) to Referral Parents of the user who has pressed the button with this Action.
Accruals (rewards) occurs on the variable you specified as a percentage of the number you specified (you can also use the variable's Macros if you purchased the corresponding plugin).
Macros and Button Expressions.
To connect, go in your bot:☞ 🔐Admin | 🧩Extensions | 📂Buttons
Percentages can be specified for each level of the referral system. By default, one level is available, but with the help of extensions, this number can be increased to the desired amount, creating Multi-level referral systems.
This Action is created in the same way as the previous two.
1. You specify the variable where the rewards for each level should be accrued to.
2. Then the number itself - the percentage of which should be credited up the referral system.
Please note that the number indicated by you, will only be set as a "starting point" and will NOT be credited to anyone - it solely serves as a starting point for accrual amounts.
3. The next step will ask you to specify the amount of reward for each active level.
The rewards are indicated in a column, for each level on a new line. Each number is a percentage of the original number you specified in a previous step. In order for the distribution of reward to have a natural look, the amount of reward should decrease with each new level. Although in some cases there may be exceptions.
For example:
20
10
5
Above is the setting for a three-level referral system where the rewards are 20%, 10% and 5% for each level, respectively.
In the picture below, the settings for accruals of 10%, 1%, 0.1%:
Note that "." (period) is used to separate the decimal values.
The number of referral levels for which the accruals are indicated may be less than the actual number of referral levels in your system. However, the first number will always correspond to the first level, the second to the second, and so on.
Please note that the number of "executions" (read Tokens of Funstions) for such an Action is calculated by the number of actual accrual actions and therefore is directly related to the number of Referral Parents of the user for whom the accrual is taking place.
4. If the "Conditions for Buttons" plugin is purchased in your bot, then you will be prompted to enter a condition under which this Action will be executed.
Macros and Expressions in Button.
Conditions.
To connect, go in your bot:☞ 🔐Admin | 🧩Extensions | 📂Buttons
You can also set some corresponding message in case of non-fulfillment of this condition. We remind you that the "Condition" is always an "Expression". Read more about Expressions in the corresponding manual.
If the individual Action's condition entered here is not met, this is not an error, just this particular Action will not work. The chain of execution of Actions will not be interrupted and will continue its further execution.
The Condition itself and its messages are not required to be entered - click "Set Empty" if you do not need them in your case.
❖ Action of Initialization
Action Initialization - allows you to set the initial value for any variable. In this case, the variable must be either new and never used by user before, or empty - cleared to its original state by the corresponding command (see below).
For example, you can use it for a Date and Time Variable. The point is that the new Date and Time variable will always show the current time, which sometimes leads to unpredictable results in expressions. So, to set any specific value for this variable - to "initialize" it - this function can be used. In addition, it can be used for initial charges of any amount to the user. When added to a button, this Action will be triggered only once and will make only one charge to specified variable - after which, for this user, it will no longer be triggered.
1. When creating this Action, first you will be asked to specify a variable, which later going to be "initialized" - that is, set the value one-time.
2. Then, of course, you need to specify the value that will actually be assigned to the variable.
3. After that, you can specify a message that will be shown to the user, proving that this Action has worked. It is not mandatory to add the message, you can leave it empty, if you do not want to inform the user or let him know that some data has been changed.
This completes the creation of this Action.
Nuances of working with the Action of Initialization:
● This Action will works only if the variable that it has to change is absolutely empty. That is, it is either just created and there is no value in it for this reason, or it has been cleared with commands like:/varclearall
and /vardel
and is empty for this reason (for more information about these commands, see the manual on variables). After clearing the variables with these commands, Action of Initialization will work again.
● For numeric variables, zero is also a value and Action will not work. So making Action work by assigning 0 (zero) to a numeric variable will not work - you need to use the commands provided above.
● This Action works with Numeric, Text and Date & Time variables. Does NOT work with Global.
❖ Action of Commands
Action of Commands - allows you to refer to any button by its command, with all the corresponding consequences. Including transferring the user to the desired menu - if the command of the button itself is configured accordingly.
You can read more about working with commands in the commands guide.
Can be used for non-linear menu navigation. Including, if necessary, create for the users impression of a dynamically changing menu, when the user gets a different result when pressing the same button. This mechanic is described for inline buttons in "LifeHack # 4" (see this guide at the link), but now such approach can be used for regular buttons as well.
1. When creating this Action, you must first enter the command that the Action should send. This command belongs to the button whose functionality you want to access using this Action.
Please note that if you need to transfer the user to the menu of the button you are referring to, then you need to remember that this action is configured within the button itself, when adding a command. For that being said, the button itself determines whether it is necessary to transfer the user there. Action - only accesses this button by its command.
2. After adding a command, you will be prompted to enter a Condition for triggering this Action. This step is optional and depends on your specific situation.
3. As in all previous cases, after adding the Condition, you will be prompted to enter a message in case the Condition is not met - an error message.
4. Next, you need to determine whether the command transition will interrupt the further execution of the remaining Actions in the list below. By default, execution will be aborted. If you change this setting and allow execution, then after the transition and completion of all possible actions in the destination button, the bot will return to the execution of the remaining Actions in original button.
5. In addition to interrupting the execution of the following Actions, at the same stage, you can tell the bot whether, after completing all the actions associated with the transition by command, bot also has to show the message of the button from which the actual transition was made.
This completes the creation of the "Action of Command".
Nuances of working with Action commands:
● The maximum number of sequential automatic transitions by command - 5 (five).
❖ Action of Transactions
Action of Transactions - allows your users to make changes by increasing or decreasing the values of each other's variables.
InToabenarrowmoresense,specific, Action will allow users to make transfers of certain digital assets inside the bot.
In simple words - to transfer money to each other or tokens that are, for example, on their balance sheets.balance. However, money transfers are only a small part of the spectrum of possible ways to use this functionality.
When creating a function with the participation of this Action, the user can be given a choice of the amount, or it can be rigidly set. At the same time, whether funds will be added or taken away - determinesdetermined by the admin when setting up this Action.
The user can NOT choose the sign (+/-) of the number that he sends.
Regardless of what number he specifies for a transaction, the sign will be determined by the admin when composing this Action, and the number sent by the user, positive or negative, will always be turned into a positive one before being added to the formula specified by the admin or being processed by it.
The user can be given a choice of the addressee, or it can also be rigidly set. Everything will depend on the specific circumstances and objectives.
1. When creating, first of all, you need to specify the variable that the Action data will change.
The variable specified here is a variable on the ADDRESSADDRESSEE side, that is, you specify the recipientrecipient's variable that needs to be changed.
2. After that, the bot will ask you to specify the amount to change.
Depending on your tasks, you can:
● rigidly set this amount - to do this, simply send the bot the required number.
● specify the macromacros of a digitalnumeric variable in whichwhere the amount will be contained and where this amount should be taken from. Moreover, this variable can be both global and individual.
In the case of an individual variable, you can create a form in advance and, by entering a variable, allow the user to set the value of this variable himself. Thus, the user by himself, will be able to choose the amount to transfer himself.transfer.
● you can make the variable positive or negative - to do this, put a minus sign in front of the sum (or before the macro of a digitalnumeric variable). In this case, the amount will be taken awaydeducted from the addressee.
3. Next, the bot will ask you to specify the user ID whose variable you want to change. This identifier can be specified hardrigidly - just by sending it to the bot. However, in the overwhelming majority of cases, it is better to set this identifier through a macro of a specific text variable.
This will allow you to easily change this value yourself and give theyour user the opportunity, byof changing this variable, in order to choose whowhom he will send his funds to. ForTo do this (as it was in the previous case), a Feedback Form isshall be created in advanceadvance, in which thewhere user, by using the“variable "Variable Input"input”, setswill set the value of this variable,variable therebyby independentlyhimself, determiningthus todefining whomthe heperson sendsfor sending his funds.funds to.
User ID is his Telegram ID or Menu Builder UserCode. Although both are numeric, this variable must be TEXT or, in some special cases, it can be global.
We do NOT recommend using numeric variables to store identifiers, because these identifiers can start from zero, and a numeric variable will delete it when saving - which will lead to an error that can be searched for a long time and not found.
4. After that, the bot will ask you to specify the conditions for triggering this Action. Whether or not to specify any terms depends on your situation.
This condition will be needed, for example, in order to check whether the sender has enough funds on the balance sheet to make a transfer, provided that the funds sent to you will later need to be debited from the sender's account. Accordingly, if the condition is not met, then the Action will not work. In most cases it is better to use a Condition Action and break the entire chain.
As you understand, a separate Action is just a link in a chain of sequence of actions. Therefore, the Action of the Transaction in the queue of Actions can be followed by the Action of Numbers, which will deduct the amount sent from the balance. Use the same charge-off approach that you used to determine the transfer amount.
Please note that if this Action did not work, then this will not affect the rest of the Actions in the chain in any way - that is, they will continue to be executed as if nothing had happened. For this reason, if the Action of Transactions is followed by Action of Numbers to write off the balance, then a similar condition must be added for the Action of writing off the balance (or even Action Conditions, which will completely interrupt further execution), otherwise the write-off will be performed independently from whether the translation itself occurred or not.
5. After creating the Condition, the bot will prompt you to enter a message that will be shown to the user if this Condition did not work. In other words, an error message.
You can use macros and emojis in this message , but you cannot use markdown.
This message is optional and you do not need to create it.
6. Next, the bot will prompt you to enter a message for the user in case this Action is successfully triggered. You can use macros and emojis in this message, but you cannot use markdown. This message is optional and can be omitted either.
This completes the creation of the "Action of Transactions".
❖ Action of Messages
Action Messages - allows you (or your user), by pressing a button, to send a message to the specified addressee. We deliberately do not say "to a group" or "channel", because in fact Action allows you to send messages to anyone who has a Telegram ID - that is, not only to groups and channels, but also to the bot users themselves or to the administrator personally.
1. The bot will ask you to enter the message itself.
Any available Macros, Expressions, and Markdown markup can be used in the message.
This message is formed in the form of text at the time of sending and therefore, when using Macros Variables and Expressions, after sending it will contain the data of the SENDER in the form in which they were at the time of sending - regardless of who, when and where it will be shown, regardless on the state of the original variables at the time of showing.
2. Next, you need to enter the ID of the Chat, Group or User of the bot - the place where you want to send the message. Most often this is a Group or Channel (how to set up a bot to work in a group or channel), but, as we wrote above, a message can also be sent to an individual user - for this, you need to specify his ID here.
In this setting, you can use Variable Macros and Expressions - this way the addressee can be substituted dynamically, for example, by pre-writing its ID into a separate variable - for example, using the Action of Numbers or Texts.
3. This Action can also set the Condition under which it will be executed.
4. Next, you can enter a message that will be shown if the Condition is not true.
This completes the creation of the "Messages Action".
❖ Action of Texts
Action Texts - allows you to assign values to Text variables by clicking a button by a bot user.
The functionality of this Action may be expanded in the future.
1. At the first step, you need to specify the Text Variable whose value you want to set. The bot will offer for selection only the Text Variables created in your bot.
2. Next, the bot will ask you to specify a value - that is, text - that will be assigned to the previously selected variable.
Maximum text length for 200 characters (as for any Text Variable).
3. This Action can also set the Condition under which it will be executed.
4. Next, you can enter a message that will be shown if the Condition is not true.
This completes the creation of the "Action Texts".
"Action Texts" consume 3 "Function Tokens" instead of one, like other Actions. Working with texts generates more load on the server side.