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".
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 Expressions for Buttons.
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.
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.
TOKEN CONSUMPTION: If the variable is already initialized - 0.3 Tokens of Functions are consumed. If initialization is required - then 1 Token of Functions - as usual.
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, Decreasing or Setting-up the values of each other's variables. To be more 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. 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 - determined 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.
IMPORTANT: Action - can NOT take the value of a variable below zero. If after transaction the value of the destination variable should turn out to be negative, then the chain of execution of Actions will be INTERRUPTED.
Be careful when SUBTRACTING values with Actions of Transactions. Try to secure this Action as much as possible with the help of any additional checks, or Conditions. Be sure to set a common error message for the entire chain - try to describe what is happening to the user as much as possible. SUBTRACTION errors of this Action can lead to unpredictable consequences, because the Action execution chain is interrupted at the place where the error occurred and for this reason it will be executed only partially - some actions of the chain will be executed, and the rest will not work at all.
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 ADDRESSEE side, that is, you specify the recipient's variable that needs to be changed.
2. Next, the bot will ask you to select the Operation type. The variable value can be «Changed» (default) or «Set» (if you know what you're doing).
Action of Transactions can work with three types of variables:
• numeric (set and change available)
• date and time (set only available)
• text (set only available)
When working with Text variables, as well as Date and Time variables, Action of Transactions have the ability to only «Set» a value - accordingly, when choosing these types of variables, the «Change» option will not be available. For Numeric variables Action has a full range of options available. Keep this in mind when creating Action, as well as while reading this guide.
It should be understood that the following descriptions of the various «Changes» of values, calculations, and working with signs - refer exclusively to working with Numeric variables. It makes no sense to separately describe the work with Text variables, as well as with Date and Time variables, because the abilities there are limited to the «Set» option only.
3. At this step, you need to specify the amount of the operation, as well as clearly determine whether the amount will be deducted or added.
The amounts entered here must ALWAYS be positive (NO need to enter any negative numbers here). The sign of the transaction will be unambiguously specified using a separate setting (see below). One way or another, the amount specified here will always be converted to a positive number before being used in calculations.
This is done in order to exclude the possibility of confusion with positive and negative numbers (+/-) during the execution of a transaction, when a minus by a minus will give a plus, and etc. In addition, the amounts used in transactions can be set not only by the admin, but taken from variables, as well as set by the users themselves. This approach will not allow users to control the sign of the transaction, and admins will eliminate the need to check the input data and describe possible input errors.
First, let's define the sign.
3.1 In order to deduct the (positive) amount specified here, you must explicitly indicate this by switching the option "Transaction Decrease Variable" to the Enabled (▶️ On) position. In this case, the amount will be deducted from the addressee.
This option (for the obvious reasons) is only available for the «Change» operation type.
3.2 Depending on your tasks, you can:
● rigidly set this amount - to do this, simply send the bot the required number.
● specify the macros of a numeric variable where the amount will be contained and where this amount should be taken from. Moreover, this variable can be both global and individual.
The variable specified here is a variable on the SENDER's side, that is, you specify the sender's variable, the data of which will be substituted as a sum and used for calculations.
In the case of an individual variable, you can pre-create a Form and, using «Variable Input», allow the user to set the value of this variable himself. Thus, the user will be able to choose the amount to transfer. We remind you that the value specified by the user will always be treated as positive - the sign of the transaction is specified by the admin when creating the Action itself.
4. Next, the bot will ask you to specify the user ID whose variable you want to change. This identifier can be specified rigidly - 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 your user the opportunity, of changing this variable, in order to choose whom he will send his funds to. To do this (as it was in the previous case), a Feedback Form shall be created in advance, where user, by using «Variable Input», will set the value of this variable by himself, thus defining the person for sending his funds to.
User ID is his Telegram ID or Menu Builder's UserCode. Despite the fact, that both of them 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.
5. After that, the bot will ask you to specify the conditions for triggering this Action. Whether or not to specify any conditions depends on your situation.
This condition will be needed, for example, in order to check whether the sender has enough funds on the balance to make a transfer, in case the amount he sent will need to be deducted from the sender's account later. Accordingly, if the condition is not met, then the Action will not work. In most cases it is better to use the Action of Conditions 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 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 approach for deduction that you used to determine the amount for transfer.
Please note that if this Action did not work, it will not, in any way, affect the rest of the Actions in the chain - that means, they will continue to be executed as if nothing had happened. For this reason, if the Action of Transaction is followed by the Action of Number that is deducting from the Balance, then the same condition (or the whole Action of Condition, so to stop the whole further execution) must be added for the deducting Action as well, otherwise it will be executed regardless of whether the transfer has occurred or not.
6. 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.
7. Next, the bot will prompt you to enter a message for the user (receiver) in case this Action was 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 of Messages - allows you (or your user), to send a message to the specified addressee, by pressing a button. We deliberately do not say "to a group" or "channel", because, in fact, this 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 personally to the administrator.
1. The bot will ask you to enter the message itself.
Before creating a message to send, you can enable the option to pin a message in the chat (turned off by default), as well as sending message with no sound. In addition, the message can be specified with a Media Variable to display a picture or file.
«Pin in Chat» - the bot can pin the sent message in the destination chat.
Modes:Off ⏹️ - feature disabled - just send.On ▶️ - feature enabled - send and pin.
«Send with No Sound» - the bot can send a message without sound despite the actual chat settings.
Modes:Off ⏹️ - feature disabled - just send.On ▶️ - feature enabled - send with no sound.
Advanced Mode
«Advanced Mode» - allows you to add Inline Buttons and Media Variable to the message of the Action.
Now we can move on to creating the message itself.
Any available Macros, Expressions, and Markdown markup can be used in this message.
This message is composed in the form of text, at the moment of sending and therefore, when using Macros of Variables and Expressions, after sending it will contain the data of the SENDER in the form in which they were at the moment of sending - regardless of who, when and where it will be shown, regardless of 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 mentioned above, this message can also be sent to an individual user - for this, you need to specify his ID here.
If the group you specified contains Topics, then, as the following step, the bot will offer you a standard menu for specifying the Topic and choosing how to work with it.
For more information about Topics, see the Forms guide.
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 dedicated variable - for example, using the Action of Numbers or Texts.
3. This Action can also be set with Condition, under which it will be executed.
4. Next, you can enter a message that will be shown if the Condition is not met.
This completes the creation of the "Action of Messages".
❖ Action of Texts
Action of Texts - allows you to assign values to the Text variables by bot's user clicking a button.
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 the actual text - that will be assigned to the previously selected variable.
Maximum text length is 200 characters (as it is for any Text Variable).
3. This Action can also be set with Condition under which it will be executed.
4. Next, you can enter a message that will be shown if the Condition is not met.
This completes the creation of "Action of Texts".
"Action of Texts" consume 3 "Tokens of Functions" instead of 1, like other Actions. Working with texts generates more load on the server side.
❖ Action of Clearing
Action of Clearing - allows you to reset the value of a variable while clearing the data it contains.
The variable returns to its original state - NOT INITIALIZED.
1. At the first step, you need to specify the Variable whose value you want to clear. The bot will offer all available Variables created in your bot for selection.
2. This Action can also be set with Condition under which it will be executed.
3. Next, you can enter a message that will be shown if the Condition is not met.
4. Next, you can enter a message that will be shown to the user if the Action worked.
The Action of Clearing is used for one specific purpose - clearing the data and bringing the variable back to its original (uninitialized) state. At your request, the Action of Clearing got ability to set a Condition, but its use as part of chains of other Actions was not originally intended. Therefore - use it for its intended purpose, which is "reset" variable to bring it to its original state of "non-existence". Use it, for example, to clear user data. If you saved any user data in your bot and want to give them the opportunity to clear the information they saved and restore their account to its original state.
To simply reset the value of a Numeric Variable, assign it to 0 (zero) using the Action of Numbers.
IMPORTANT: Use this Action only if you understand exactly what you are doing and what results you will get. As a reminder, the values and the general behavior of "initialized" and "uninitialized" variables can be radically different - and you can get unpredictable results depending on their current state - variables may show different values, may not respond to certain commands, may corrupt some function they being part of. Use the Action of Clearing for YOUR OWN needs and try not to use it in any of functions available to your users, except for some special cases.