Telegram Matcher #

The telegram-matcher tool retrieves the latest Telegram messages belonging to the chatrooms and users whose information is present in the configuration and checks if any of them match the specified patterns. Note that only messages that have not been checked before are retrieved when this tool is executed.

For this tool to work properly, the Telegram scout has to be configured as described here. On top of that, the Telegram bot whose token is used in the Telegram scout’s configuration must be added as a member to all the chatrooms whose IDs are used in the telegram-matcher tool’s configuration.

The telegram-matcher tool cannot be backtested. More information about strategy backtesting can be found here.

Configuration #

{
	"type": "telegram-matcher",
	"context_id": "telegram-matcher-id-123",
	"description": "a simple tool",
	"chatrooms": [
		123456789,
		987654321
	],
	"usernames": [
		"currer",
		"ellis"
	],
	"patterns": [
		"down",
		"[0-9]+% drop",
		"[0-9]+ below {{tools.sma-checker.value}}"
	],
	"condition": {
		"type": "constant",
		"target": "2",
		"operator": "equal"
	}
}

type - string
The type of the tool configuration.
Tool configuration types are described in detail here.
context_id - string (optional; default: unused)
The ID of the tool that is used when inserting data into the context store.
The context data store and its IDs are described in detail here.
description - string (optional; default: unused)
The description of the tool and its purpose.
chatrooms - array of ints
The array of Telegram chatroom IDs. At least one ID must be specified.
usernames - array of strings
The array of Telegram usernames. At least one username must be specified.
patterns - array of strings (context)
The patterns that are used when processing Telegram messages. Each pattern may be a simple text value or a regular expression containing multiple context value placeholders. At least one pattern must be specified.

The supported regular expression format is described in detail here.

Regular expressions can be tested here.

Context value placeholders are replaced with real data before the regular expressions are parsed, so there is no need to have any special escape characters for the placeholders themselves. Also, since this tool starts processing messages once the configuration to which it belongs becomes active (this is being done so that the tool would not miss any messages before the first cycle or between any subsequent cycles; note that these patterns, with new context data, are updated upon each execution), not all context data may be available. To avoid situations when context placeholders are replaced with an empty value, a colon followed by a value that is used only when the context value is not found could be used (e.g., {{tools.sma.value:not found}}).
condition - object
The condition that is used when checking the number of Telegram message matches.
- type - string (enum)
  The type of the condition that determines what additional properties are required and how the target value is formed. Possible types are as follows:
  - constant
    When this type is active, the target value that is specified in the configuration is used as the condition’s target value. The additional properties of this type are the following:
    - target - string (decimal)
      The target value that is used without any additional processing. It cannot be less than 0.
- operator - string (enum)
  The operator that is used when comparing the number of Telegram message matches to the condition’s target value. Possible values:
  - equal, eq, ==
    The equality operator checks if the number of Telegram message matches is equal to the condition’s target value.
  - greater-than, gt, >
    The greater than operator checks if the number of Telegram message matches is greater than the condition’s target value.
  - less-than, lt, <
    The less than operator checks if the number of Telegram message matches is less than the condition’s target value.
  - greater-than-or-equal, ge, >=
    The greater than or equal operator checks if the number of Telegram message matches is greater than or equal to the condition’s target value.
  - less-than-or-equal, le, <=
    The less than or equal operator checks if the number of Telegram message matches is less than or equal to the condition’s target value.
  - not-equal, ne, !=
    The inequality operator checks if the number of Telegram message matches is not equal to the condition’s target value.

Report #

{
	"type": "telegram-matcher",
	"permit": true,
	"matches": [
		{
			"chatroom": 123456789,
			"username": "currer",
			"pattern": "down",
			"message": "The price is going down"
		},
		{
			"chatroom": 987654321,
			"username": "ellis",
			"pattern": "[0-9]+% drop",
			"message": "Another 2% drop"
		}
	],
	"condition": {
		"type": "constant",
		"result": true
	}
}

type - string
The type of the tool report.
Tool report types are described in detail here.
permit - boolean
The property that determines whether the tool gave its permission to continue strategy execution or not.
The tool execution flow is described in detail here.
matches - array of objects
The array of Telegram match objects that contain messages that matched at least one of the patterns. Each match object has the following properties:
- chatroom - int
  The ID of the Telegram chatroom to which the matched message belongs.
- username - string
  The username of the Telegram user that sent the message.
- pattern - string
  The pattern that the message matched.
- message - string
  The message that matched the pattern.
condition - object
The report of the condition that was used when checking the number of Telegram message matches.
- type - string (enum)
  The type of the condition that determines what additional properties are included in the report. Possible types are as follows:
  - constant
    When this type is processed, no additional properties are added.
- result - boolean
  The property that determines whether the comparison was successful or not.

If an error occurs during the telegram-matcher tool’s execution, only type and error properties are added to the report. The error property is described in detail here.

Context #

The objects that the telegram-matcher tool inserts into the context store are as follows:

tools.<context-id>.permit - boolean
The object that determines whether the tool gave its permission to continue strategy execution or not.
tools.<context-id>.condition - map
The results of the condition that was used when checking the number of Telegram message matches.
- The type of the condition determines what additional objects are inserted into the context store. The types and their objects are as follows:
  - constant
    When this type is processed, no additional objects are inserted into the context store.
- tools.<context-id>.condition.result - boolean
  The object that determines whether the comparison of the number of Telegram message matches and the condition’s target value was successful or not.

If an error occurs during the telegram-matcher tool’s execution, only the tools.<context-id>.error object is inserted into the context store. This context data object is described in detail here.