exteraGram Plugins

https://plugins.exteragram.app/docs
Admin
Develop Telegram plugins using Python with Chaquopy and Aliucord's Xposed method hooking to modify...
Tokens:106,830
Snippets:948
Trust Score:5.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install ElyxBuilder and generate a new project

Source: https://plugins.exteragram.app/docs/elyx/quick-start

Install ElyxBuilder, create a project directory, and run the interactive wizard to generate the initial plugin project.

```bash
python -m pip install --upgrade ElyxBuilder
mkdir elyx_hello
cd elyx_hello
elyb new
```

--------------------------------

### Install ElyxBuilder and create a new project

Source: https://plugins.exteragram.app/docs/elyx/development

Install ElyxBuilder and generate a new project with `elyb new`. Run from the directory containing `refmap.yml`.

```bash
python -m pip install --upgrade ElyxBuilder
elyb new
```

--------------------------------

### Localization strings file example

Source: https://plugins.exteragram.app/docs/elyx/metadata

Example strings_en.yml file providing the plugin_description key used by the description placeholder. If a key is missing, its key name is used as replacement text.

```yaml
# strings_en.yml
plugin_description: Adds better link previews.
```

--------------------------------

### Install ElyxBuilder CLI

Source: https://plugins.exteragram.app/docs/elyx/elyxbuilder

Install the ElyxBuilder CLI. Requires Python 3.10 or newer.

```bash
python -m pip install --upgrade ElyxBuilder
```

--------------------------------

### Example asset directory tree

Source: https://plugins.exteragram.app/docs/elyx/assets

Example directory tree showing the expected layout of the asset directory. The tree includes files and a subdirectory named icons.

```text
plugin/res/
|-- logo.svg
|-- loading.json
|-- banner.png
|-- defaults.yml
|-- about.txt
`-- icons/
    |-- add.svg
    `-- remove.svg

```

--------------------------------

### Full Example: Java Proxy with extera_utils

Source: https://plugins.exteragram.app/docs/class-proxy

Complete example of creating a Java proxy class with extera_utils. It shows field declarations, argument normalization, constructor, override, overload, and method mapping. The final lines create an instance and access its Java representation.

```python
from extera_utils.classes import (
    Base,
    java_subclass,
    joverride,
    joverload,
    jmethod,
    jfield,
    jconstructor,
    jpreconstructor,
)
 
 
@java_subclass(SomeJavaClass)
class DemoProxy(Base):
    counter = jfield("int", default=0)
    title = jfield("java.lang.String", default="Demo")
 
    @jpreconstructor(["java.lang.String", "int"])
    def normalize_args(cls, title, counter):
        return [title.strip(), max(0, counter)]
 
    def __init__(self, title, counter):
        self.python_state = {"created_with": title}
 
    @jconstructor(["java.lang.String", "int"])
    def init_fields(self, title, counter):
        self.title = title
        self.counter = counter
 
    @joverride()
    def onAttached(self):
        self.counter += 1
        return super().onAttached()
 
    @joverload("setValue", ["int"])
    def set_value_int(self, value):
        self.counter = value
        return super().set_value_int(value)
 
    @joverload("setValue", ["java.lang.String"])
    def set_value_text(self, value):
        self.title = value
 
    @jmethod("debugLabel", "java.lang.String", ["int"])
    def build_debug_label(self, extra):
        return f"{self.title} ({self.counter}, extra={extra})"
 
 
instance = DemoProxy.new_instance("  Example  ", 5)
java_instance = instance.java
```

--------------------------------

### Verify ElyxBuilder Installation and Commands

Source: https://plugins.exteragram.app/docs/elyx/elyxbuilder

Verify the installation and inspect the commands supported by the installed version. Python 3.11 is required only when creating compiled .pyc builds.

```bash
elyb --version
elyb --help
```

--------------------------------

### Custom template example

Source: https://plugins.exteragram.app/docs/first-plugin

Example template that can be set in the plugin settings to change the output.

```text
Welcome back, {name}.
```

--------------------------------

### Local import directory structure

Source: https://plugins.exteragram.app/docs/elyx/troubleshooting

Example directory structure for a local import scenario.

```text
src/
|-- __init__.py
`-- feature.py
```

--------------------------------

### Example plugin layout at root

Source: https://plugins.exteragram.app/docs/elyx/project-structure

Shows a minimal plugin structure with refmap.yml, metainfo.yml, main.py, assets, and strings directories at the archive root.

```text
my_plugin/
|-- refmap.yml
|-- metainfo.yml
|-- main.py
|-- assets/
`-- strings/
```

--------------------------------

### enable_plugin

Source: https://plugins.exteragram.app/docs/dev-server

Enable an installed plugin.

```APIDOC
## [TCP] enable_plugin

### Description
Enable an installed plugin.

### Method
TCP

### Endpoint
127.0.0.1:42690

### Parameters
#### Request Body
- **plugin_id** (string) - Required - The identifier of the plugin to enable.

### Request Example
{
  "@": "enable_plugin",
  "#": "request-3",
  "plugin_id": "example_plugin"
}

### Response
#### Success Response
- **ok** (boolean) - Indicates success.
```

--------------------------------

### Start debugger request

Source: https://plugins.exteragram.app/docs/dev-server

Request to start a remote debugger with host, port, and platform fields.

```json
{
  "@": "start_debugger",
  "#": "debug-1",
  "host": "127.0.0.1",
  "port": 5678,
  "platform": "vscode"
}
```

--------------------------------

### Watch for changes and rebuild

Source: https://plugins.exteragram.app/docs/elyx/elyxbuilder

Starts the watch mode, polling the project every 10 seconds and starting a build after a change. The first argument is the polling interval in seconds. The --args string is passed to the build command. ElyxBuilder stores the most recent result as builds/latest.eaf, or with the archive extension configured for the project. In the interactive watch screen, press P to pause/resume and Q to exit. Note that elyb watch rebuilds the archive but does not install it on a device.

```bash
elyb watch 10 --args "--ast -v -nf"
```

--------------------------------

### Plugin file layout

Source: https://plugins.exteragram.app/docs/elyx/modules-and-imports

Example file layout for a plugin with a main module, a helper module, and a features package. This structure supports the imports shown in the following examples.

```text
main.py
helpers.py
features/
|-- __init__.py
`-- links.py
```

--------------------------------

### Example refmap.json

Source: https://plugins.exteragram.app/docs/elyx/project-structure

JSON equivalent of the refmap configuration.

```json
{
  "metainfo": "plugin/meta.yml",
  "main": "plugin/src/main.py",
  "strings": "plugin/locales",
  "assets": "plugin/res",
  "wheels": "wheels"
}
```

--------------------------------

### Complete minimal metadata

Source: https://plugins.exteragram.app/docs/elyx/metadata

Complete minimal metadata example. Everything else is optional, but production plugins should normally include description, author, app_version, and sdk_version.

```yaml
id: my_plugin
name: My Plugin
version: "1.0.0"
```

--------------------------------

### Example refmap.yml

Source: https://plugins.exteragram.app/docs/elyx/project-structure

YAML format for the refmap file, recommended because it is concise and contains no executable code.

```yaml
metainfo: plugin/meta.yml
main: plugin/src/main.py
strings: plugin/locales
assets: plugin/res
wheels: wheels
```

--------------------------------

### Example plugin layout with nested plugin directory

Source: https://plugins.exteragram.app/docs/elyx/project-structure

Shows an alternative layout where distributable files are under a plugin/ directory, with refmap pointing to the correct locations.

```text
my_plugin/
|-- refmap.yml
|-- plugin/
|   |-- meta.yml
|   |-- src/
|   |   |-- __init__.py
|   |   `-- main.py
|   |-- locales/
|   `-- res/
`-- wheels/
```

--------------------------------

### Builder-only key example

Source: https://plugins.exteragram.app/docs/elyx/project-structure

Shows how tools can add their own values to refmap, e.g., elyxbuilder.

```yaml
elyxbuilder: plugin/.elyxbuilder
```

--------------------------------

### Nested entry point layout

Source: https://plugins.exteragram.app/docs/elyx/modules-and-imports

Example layout for a plugin with a nested entry point. This structure is used to illustrate relative imports.

```text
plugin/
|-- __init__.py
|-- main.py
`-- feature.py
```

--------------------------------

### Valid plugin id examples

Source: https://plugins.exteragram.app/docs/elyx/metadata

Valid plugin id examples. An id must contain 2 to 32 characters, only ASCII letters, digits, and underscores, and remain stable across updates.

```text
elyx_hello
weather2
MyPlugin
```

--------------------------------

### Installed plugin layout

Source: https://plugins.exteragram.app/docs/elyx/project-structure

Shows the runtime extraction layout under the app's plugin storage.

```text
<app files>/plugins/
|-- ElyxPlugins/
|   `-- <plugin_id>/
|       |-- refmap.yml
|       |-- main.py
|       `-- ...
|-- elyx_local_libs/
|   `-- <plugin_id>/
`-- archives/
```

--------------------------------

### Correct archive layout

Source: https://plugins.exteragram.app/docs/elyx/project-structure

Shows the installable archive must contain project files directly at its root.

```text
my_plugin.elyx
|-- refmap.yml       <- discovered
|-- metainfo.yml
`-- main.py
```

--------------------------------

### Absolute import example

Source: https://plugins.exteragram.app/docs/elyx/troubleshooting

Use this import when importing from outside the src directory.

```python
from src.feature import Feature
```

--------------------------------

### elyx_compare_folder

Source: https://plugins.exteragram.app/docs/dev-server

Compare local hashes with installed files.

```APIDOC
## [TCP] elyx_compare_folder

### Description
Compare local hashes with installed files.

### Method
TCP

### Endpoint
127.0.0.1:42690

### Parameters
#### Request Body
- **data** (string) - Required - Base64-encoded compressed JSON payload containing the folder comparison data.

### Request Example
{
  "@": "elyx_compare_folder",
  "#": "request-10",
  "data": "base64encodedpayload"
}

### Response
#### Success Response
- **changes** (array) - List of file changes detected.
```

--------------------------------

### refmap main key example

Source: https://plugins.exteragram.app/docs/elyx/project-structure

Specifies the path to the Python entry module. The module must contain at least one class inheriting from BasePlugin.

```yaml
main: plugin/src/main.py
```

--------------------------------

### General Example: Telegram Plugin Settings with All Built-in Types

Source: https://plugins.exteragram.app/docs/plugin-settings

Complete example of a Telegram plugin settings page using almost every built-in setting type: Switch, Selector, Input, EditText, Divider, Text, and Custom controls. It also defines a custom sticker view factory with create/bind functions and a sub-page for nested settings.

```python
from typing import Any, List
 
from android.view import Gravity, View
from android.widget import LinearLayout
 
from org.telegram.messenger import AndroidUtilities, MediaDataController, UserConfig
from org.telegram.ui.Components import BackupImageView, LayoutHelper, UItem
 
from base_plugin import BasePlugin
from ui.settings import (
    Custom,
    Divider,
    EditText,
    Header,
    Input,
    Selector,
    SimpleSettingFactory,
    Switch,
    Text,
)
 
 
def create_sticker_view(context, list_view, current_account: int, class_guid: int, resources_provider):
    main_layout = LinearLayout(context)
    main_layout.setOrientation(LinearLayout.VERTICAL)
    main_layout.setGravity(Gravity.CENTER)
    main_layout.setPadding(
        AndroidUtilities.dp(20),
        AndroidUtilities.dp(20),
        AndroidUtilities.dp(20),
        AndroidUtilities.dp(20),
    )
 
    image_view = BackupImageView(context)
    image_view.setRoundRadius(AndroidUtilities.dp(45))
 
    # The view is created here once. Do not bind item-specific data here yet.
    main_layout.addView(image_view, LayoutHelper.createLinear(130, 130, Gravity.CENTER, 0, 0, 0, 16))
    return main_layout
 
 
def bind_sticker_view(view, item, divider: bool, adapter, list_view):
    sticker_set_name = "CactusPlugins"
    sticker_index = 0
 
    # This runs when the view should display actual content.
    MediaDataController.getInstance(UserConfig.selectedAccount).setPlaceholderImageByIndex(
        view.getChildAt(0),
        sticker_set_name,
        sticker_index,
        "130_130",
    )
 
 
StickerSettingFactory = SimpleSettingFactory(
    create_sticker_view,
    bind_sticker_view,
    is_clickable=False,
    is_shadow=False,
)
 
 
class MyPlugin(BasePlugin):
    def _on_test_switch_change(self, new_value: bool):
        self.log(f"Test switch changed to: {new_value}")
 
    def _on_test_input_change(self, new_value: str):
        self.log(f"Test input changed to: {new_value}")
 
    def _on_test_selector_change(self, new_index: int):
        self.log(f"Test selector changed to index: {new_index}")
 
    def _on_text_click(self, view: View):
        self.log("Text item clicked!")
 
    def _create_sub_page(self) -> List[Any]:
        return [
            Header(text="This is a Sub-Page"),
            Text(text="You can nest settings pages."),
        ]
 
    def create_settings(self) -> List[Any]:
        return [
            Header(text="General Settings"),
            Switch(
                key="test_switch_key",
                text="Test Switch",
                default=True,
                subtext="This is a sample switch control.",
                icon="msg_settings",
                on_change=self._on_test_switch_change,
                link_alias="test_switch",
            ),
            Selector(
                key="test_selector_key",
                text="Test Selector",
                default=1,
                items=["Option A", "Option B", "Option C"],
                icon="msg_list",
                on_change=self._on_test_selector_change,
            ),
            Input(
                key="test_input_key",
                text="Test Input",
                default="Hello, World!",
                subtext="A simple single-line text input.",
                icon="msg_text",
                on_change=self._on_test_input_change,
            ),
            EditText(
                key="multiline_key",
                hint="Enter multiple lines of text here...",
                default="",
                multiline=True,
                max_length=1000,
            ),
            Divider(text="This is a divider with text."),
            Text(
                text="Click for Sub-Page",
                icon="msg_arrow_forward",
                on_click=self._on_text_click,
                create_sub_fragment=self._create_sub_page,
                link_alias="sub_page_link",
            ),
            Text(
                text="This is red text",
                icon="msg_error",
                red=True,
            ),
            Divider(),
            Header(text="Custom Controls"),
            Custom(factory=StickerSettingFactory.instance.java),
            Custom(item=UItem.asShadow("This is a custom UItem shadow.")),
        ]
```

--------------------------------

### config.json data file

Source: https://plugins.exteragram.app/docs/elyx/modules-and-imports

Example config.json data file that can be imported as a module. Its stem must be a valid module path.

```json
{
  "api_url": "https://example.com",
  "limits": {
    "page_size": 50
  }
}
```

--------------------------------

### Import the managed DSL from extera_utils.classes

Source: https://plugins.exteragram.app/docs/class-proxy

Import the recommended managed DSL classes and decorators from extera_utils.classes. This is the starting point for using the class proxy API.

```python
from extera_utils.classes import (
    Base,
    java_subclass,
    joverride,
    joverload,
    jmethod,
    jMVELmethod,
    jMVELoverride,
    jclassbuilder,
    jfield,
    jgetmethod,
    jsetmethod,
    jconstructor,
    jpreconstructor,
)
```

--------------------------------

### Settings Storage Helpers

Source: https://plugins.exteragram.app/docs/plugin-class

Methods to get, set, export, and import persistent plugin settings.

```APIDOC
## Settings Storage Helpers

### Description
These methods allow plugins to store and retrieve persistent settings.

### Methods
- **get_setting(key, default=None)** - Returns the value for the given key, or the default if not set.
- **set_setting(key, value, reload_settings=False)** - Sets the value for the given key. If reload_settings is True, settings are reloaded.
- **export_settings()** - Returns a dictionary of all current settings.
- **import_settings(settings, reload_settings=True)** - Imports settings from a dictionary. If reload_settings is True, settings are reloaded.

### Example
```python
current_value = self.get_setting("enabled", True)
self.set_setting("enabled", not current_value, reload_settings=True)

backup = self.export_settings()
self.import_settings(backup, reload_settings=False)
```
```

--------------------------------

### Normalized attribute lookup examples

Source: https://plugins.exteragram.app/docs/elyx/assets

Shows how attribute lookup normalizes filenames: non-alphanumeric characters become underscores and the extension is removed.

```text
empty-state.svg -> assets.empty_state
logo.dark.png   -> assets.logo
```

--------------------------------

### Access Raw Java Object

Source: https://plugins.exteragram.app/docs/class-proxy

Shows how to get the raw Java object from a Python peer, and how to create a raw Java instance directly.

```python
java_instance = instance.java
java_instance2 = MySubclass.new_java_instance("text", 123)
```

--------------------------------

### refmap assets key example

Source: https://plugins.exteragram.app/docs/elyx/project-structure

Specifies the path to the root resource directory. When present and non-empty, plugin modules can use 'from elyx import assets'.

```yaml
assets: plugin/res
```

--------------------------------

### Add minimal SVG asset as assets/wave.svg

Source: https://plugins.exteragram.app/docs/elyx/quick-start

Minimal valid SVG example to save as assets/wave.svg. The plugin accesses it via assets.wave without the .svg extension.

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path fill="#4A90E2" d="M7 11V4a1 1 0 0 1 2 0v5h1V3a1 1 0 0 1 2 0v6h1V4a1 1 0 0 1 2 0v6h1V6a1 1 0 0 1 2 0v7c0 5-3 8-8 8s-7-3-7-7v-3a2 2 0 0 1 4 0Z"/>
</svg>
```

--------------------------------

### Strings localization lookup example

Source: https://plugins.exteragram.app/docs/elyx/public-api

Create a locale-aware Strings object and use it to look up translated strings with named placeholders. Supports get, get_with_locale, and pluralize methods.

```python
catalog = Strings({
    "en": {"hello": "Hello, {name}!"},
    "ru": {"hello": "Привет, {name}!"},
})
 
catalog("hello", name="Alice")
catalog.get("hello")
catalog.get_with_locale("hello", locale="ru")
catalog.pluralize(5, "file_forms")
```

--------------------------------

### ReplyPlugin using self.client(account)

Source: https://plugins.exteragram.app/docs/multi-account

Example plugin that uses self.client(account) to get an AccountClient bound to the account from the hook. This avoids repeating the account parameter for each helper call.

```python
from base_plugin import BasePlugin, HookResult
 
 
class ReplyPlugin(BasePlugin):
    def on_plugin_load(self):
        self.add_hook("TL_updateNewMessage")
 
    def on_update_hook(self, update_name: str, account: int, update) -> HookResult:
        if update_name != "TL_updateNewMessage":
            return HookResult()
 
        client = self.client(account)
 
        me = client.get_user_config().getCurrentUser()
        client.send_text(update.message.dialog_id, f"replying as {me.first_name}")
 
        return HookResult()
```

--------------------------------

### Create a project interactively with elyb new

Source: https://plugins.exteragram.app/docs/elyx/elyxbuilder

Starts the interactive wizard in an empty directory. The wizard asks for the plugin name, author, id, version constraints, optional icon, and the refmap and metadata formats; press Enter to accept a generated value.

```bash
elyb new
```

--------------------------------

### Create Instances

Source: https://plugins.exteragram.app/docs/class-proxy

Shows how to create Python peer instances, with and without constructor arguments.

```python
instance = MySubclass.new_instance()
instance2 = MySubclass.new_instance("text", 123)  # provide java-constructor args
```

--------------------------------

### Implement create_settings for settings screen

Source: https://plugins.exteragram.app/docs/plugin-class

Implements create_settings to expose a settings screen with a Header and a Switch. The Switch uses key, text, and default parameters.

```python
from typing import Any, List
 
from base_plugin import BasePlugin
from ui.settings import Header, Switch
 
 
class MyPlugin(BasePlugin):
    def create_settings(self) -> List[Any]:
        return [
            Header(text="General"),
            Switch(key="enabled", text="Enable feature", default=True),
        ]
```

--------------------------------

### Using *args

Source: https://plugins.exteragram.app/docs/intents

Shows how to define a callback that accepts *args to receive the standard positional bundle.

```APIDOC
## Callback: on_any_link(*args)

### Description
Defines a callback that accepts *args to receive the standard positional bundle from the SDK.

### Method
N/A (SDK callback registration)

### Endpoint
N/A

### Parameters
#### Callback Parameters
- **args** (tuple) - Required - Contains the standard positional bundle in order: `intent`, `scheme`, `host`, `path`, `query_args`, `action`, `flags`, `type`, `categories`.

### Request Example
```python
def on_any_link(*args):
    intent, scheme, host, path, query_args, action, flags, type, categories = args
    print(scheme, host, path, flags)

IM.new_global_before_handler(on_any_link, scheme="tg")
```

### Response
No response; callback executes with the provided positional bundle.
```

--------------------------------

### Invalid plugin id examples

Source: https://plugins.exteragram.app/docs/elyx/metadata

Invalid plugin id examples. These fail the id rules: too short, contains hyphens, spaces, or non-ASCII characters.

```text
a
my-plugin
my plugin
плагин
```

--------------------------------

### Build project with ElyxBuilder

Source: https://plugins.exteragram.app/docs/elyx/development

Build the project with AST output, verbose logging, and no formatting. Run from the directory containing `refmap.yml`.

```bash
elyb build --ast -v -nf
```

--------------------------------

### Get assets from environment

Source: https://plugins.exteragram.app/docs/elyx/assets

Inspects the environment to obtain the asset collection when assets are optional. The get method returns None if the asset directory is not present.

```python
from elyx import get_environment
 
assets = get_environment().get("assets")
```

--------------------------------

### Create a local project layout

Source: https://plugins.exteragram.app/docs/setup

A simple folder structure for a plugin project, with a Python file for the plugin. Keep the filename stable; the least surprising setup is filename == __id__ + ".py".

```text
my-plugin/
`-- hello_world.py
```

--------------------------------

### Usage example for parse_text with HTML and Markdown

Source: https://plugins.exteragram.app/docs/text-formatting

Shows how to parse HTML and Markdown formatted strings with parse_text and pass the resulting dictionary to send_message. The HTML example uses <b>, <i>, and <a> tags; the Markdown example uses **bold**, __italic__, and [text](url). The comment notes that client_utils functions handle parsing automatically via the parse_mode argument.

```python
from extera_utils.text_formatting import parse_text
from client_utils import send_message
 
# Parsing HTML
html_input = "<b>Bold</b>, <i>Italic</i>, and <a href='https://example.com'>Link</a>"
parsed_html = parse_text(html_input, parse_mode='HTML')
 
# parsed_html is roughly:
# {
#   "message": "Bold, Italic, and Link",
#   "entities": [TL_messageEntityBold(...), TL_messageEntityItalic(...), TL_messageEntityTextUrl(...)]
# }
 
# You can pass this dictionary directly to send_message (via kwargs unpacking if keys match params)
# But client_utils functions handle this automatically via parse_mode argument.
 
# Parsing Markdown
md_input = "**Bold**, __Italic__, and [Link](https://example.com)"
parsed_md = parse_text(md_input, parse_mode='Markdown')
```

--------------------------------

### Create main.py plugin class

Source: https://plugins.exteragram.app/docs/elyx/quick-start

Defines ElyxHelloPlugin with on_plugin_load and create_settings. Uses elyx.assets.wave (no .svg extension) and settings.get with default 'Alice'. No top-level __id__ or __name__ constants; metadata comes from metainfo.yml.

```python
from typing import Any, List
 
from base_plugin import BasePlugin
from elyx import assets, settings, strings
from src.greeting import build_greeting
from ui.settings import Header, Input, Text
 
 
class ElyxHelloPlugin(BasePlugin):
    def on_plugin_load(self):
        self.log(strings("loaded"))
 
        # Access by normalized stem, without the .svg extension.
        wave_icon = assets.wave
        self.log(f"Bundled icon: {wave_icon.path_str}")
 
    def create_settings(self) -> List[Any]:
        name = settings.get("name", "Alice")
        return [
            Header(text=strings("settings_title")),
            Input(
                key="name",
                text=strings("name_label"),
                subtext=strings("name_hint"),
                default="Alice",
                icon="msg_edit",
            ),
            Text(
                text=build_greeting(name),
                subtext="This row is generated from two project files.",
                icon="msg_info",
            ),
        ]
```

--------------------------------

### remove_plugin

Source: https://plugins.exteragram.app/docs/dev-server

Delete an installed plugin.

```APIDOC
## [TCP] remove_plugin

### Description
Delete an installed plugin.

### Method
TCP

### Endpoint
127.0.0.1:42690

### Parameters
#### Request Body
- **plugin_id** (string) - Required - The identifier of the plugin to delete.

### Request Example
{
  "@": "remove_plugin",
  "#": "request-7",
  "plugin_id": "example_plugin"
}

### Response
#### Success Response
- **ok** (boolean) - Indicates success.
```

--------------------------------

### Recommended repository layout

Source: https://plugins.exteragram.app/docs/elyx/project-structure

Shows a Git-friendly layout that scales well.

```text
my_plugin/
|-- .gitignore
|-- README.md
|-- refmap.yml
|-- plugin/
|   |-- meta.yml
|   |-- src/
|   |-- locales/
|   `-- res/
|-- wheels/
|-- builds/
`-- .elyx/
```

--------------------------------

### Pass init_args to Python __init__

Source: https://plugins.exteragram.app/docs/class-proxy

Shows how to pass separate arguments to the Python __init__ method using init_args.

```python
instance = MySubclass.new_instance("java ctor value", init_args=["python init value"])
```

--------------------------------

### disable_plugin

Source: https://plugins.exteragram.app/docs/dev-server

Disable an installed plugin.

```APIDOC
## [TCP] disable_plugin

### Description
Disable an installed plugin.

### Method
TCP

### Endpoint
127.0.0.1:42690

### Parameters
#### Request Body
- **plugin_id** (string) - Required - The identifier of the plugin to disable.

### Request Example
{
  "@": "disable_plugin",
  "#": "request-4",
  "plugin_id": "example_plugin"
}

### Response
#### Success Response
- **ok** (boolean) - Indicates success.
```

--------------------------------

### Complete Hello World plugin for ExteraGram

Source: https://plugins.exteragram.app/docs/first-plugin

Complete implementation of a Hello World plugin for the ExteraGram app. It registers an outgoing-message hook, defines a settings screen with a template input, and rewrites .hello commands into a friendly message. Requires the plugin SDK and app versions declared in the metadata.

```python
from typing import Any, List
 
from base_plugin import BasePlugin, HookResult, HookStrategy
from ui.settings import Header, Input, Text
 
__id__ = "hello_world"
__name__ = "Hello World"
__description__ = "Rewrites .hello commands into a friendly message"
__author__ = "Your Name"
__version__ = "1.0.0"
__icon__ = "exteraPlugins/1"
__app_version__ = ">=12.5.1"
__sdk_version__ = ">=1.4.4.3"
 
 
DEFAULT_TEMPLATE = "Hello, {name}!"
 
 
class HelloWorldPlugin(BasePlugin):
    def on_plugin_load(self):
        # Register the outgoing-message hook once when the plugin is loaded.
        self.add_on_send_message_hook()
        self.log("Hello World plugin loaded")
 
    def create_settings(self) -> List[Any]:
        return [
            Header(text="Hello World"),
            Input(
                key="template",
                text="Greeting template",
                default=DEFAULT_TEMPLATE,
                subtext="Use {name} where the entered name should appear.",
                icon="msg_edit",
            ),
            Text(
                text="Example",
                subtext=".hello Alice -> Hello, Alice!",
                icon="msg_info",
            ),
        ]
 
    def on_send_message_hook(self, account: int, params: Any) -> HookResult:
        # Some sends are media-only, so always validate that we really have text.
        if not isinstance(getattr(params, "message", None), str):
            return HookResult()
 
        raw_text = params.message.strip()
        if not raw_text.startswith(".hello"):
            return HookResult()
 
        # Split only once so ".hello Alice Smith" keeps the full name.
        parts = raw_text.split(" ", 1)
        name = parts[1].strip() if len(parts) > 1 else ""
 
        if not name:
            params.message = "Usage: .hello <name>"
            return HookResult(strategy=HookStrategy.MODIFY, params=params)
 
        # Read the saved template or fall back to the default one.
        template = self.get_setting("template", DEFAULT_TEMPLATE)
 
        try:
            params.message = template.format(name=name)
        except Exception:
            # If the user saved a broken template, fail softly and explain why.
            params.message = "Template must contain valid Python format placeholders, for example {name}."
 
        # Tell the plugin engine that we changed outgoing message params.
        return HookResult(strategy=HookStrategy.MODIFY, params=params)
```

--------------------------------

### start_debugger

Source: https://plugins.exteragram.app/docs/dev-server

Start a remote debugger.

```APIDOC
## [TCP] start_debugger

### Description
Start a remote debugger.

### Method
TCP

### Endpoint
127.0.0.1:42690

### Parameters
#### Request Body
- **host** (string) - Required - The host address for the debugger.
- **port** (integer) - Required - The port for the debugger.
- **platform** (string) - Required - The debugger platform: `vscode` or `pycharm`.

### Request Example
{
  "@": "start_debugger",
  "#": "debug-1",
  "host": "127.0.0.1",
  "port": 5678,
  "platform": "vscode"
}

### Response
#### Success Response
- **ok** (boolean) - Indicates success.
```

--------------------------------

### elyx_changes payload example

Source: https://plugins.exteragram.app/docs/elyx/development

Example payload for an elyx_changes action. The changes array contains records with event type in "#", a path relative to the plugin root, and base64-encoded content for created or modified files.

```json
{
  "plugin_id": "elyx_hello",
  "changes": [
    {
      "#": "modified",
      "path": "main.py",
      "is_directory": false,
      "content": "<base64 file bytes>"
    }
  ]
}
```

--------------------------------

### Show elyx_dev_client.py help

Source: https://plugins.exteragram.app/docs/elyx/development

Shows the help for the custom Elyx development client. Client revisions may expose different flags, so always inspect the script's own help.

```bash
python elyx_dev_client.py --help
```

--------------------------------

### write_plugin

Source: https://plugins.exteragram.app/docs/dev-server

Install or update Python source for a plugin.

```APIDOC
## [TCP] write_plugin

### Description
Install or update Python source for a plugin.

### Method
TCP

### Endpoint
127.0.0.1:42690

### Parameters
#### Request Body
- **plugin_id** (string) - Required - The identifier of the plugin to install or update.
- **content** (string) - Required - The complete Python source as a JSON string.

### Request Example
{
  "@": "write_plugin",
  "#": "request-6",
  "plugin_id": "example_plugin",
  "content": "print('hello')"
}

### Response
#### Success Response
- **ok** (boolean) - Indicates success.
```

--------------------------------

### GhostModePlugin with pre/post request hooks and settings

Source: https://plugins.exteragram.app/docs/plugin-class

Full GhostModePlugin example showing pre- and post-request hooks, settings, and hook strategies. It blocks typing requests, forces offline status, and logs successful sends. Requires the base_plugin and ui.settings modules.

```python
from typing import Any, List
 
from base_plugin import BasePlugin, HookResult, HookStrategy
from ui.settings import Switch
 
 
TYPING_REQUESTS = ["TL_messages_setTyping", "TL_messages_setEncryptedTyping"]
 
 
class GhostModePlugin(BasePlugin):
    def on_plugin_load(self):
        for req_name in TYPING_REQUESTS:
            self.add_hook(req_name)
 
        self.add_hook("TL_account_updateStatus")
 
    def pre_request_hook(self, request_name: str, account: int, request: Any) -> HookResult:
        if request_name in TYPING_REQUESTS and self.get_setting("dont_send_typing", True):
            self.log(f"Blocking request: {request_name}")
            return HookResult(strategy=HookStrategy.CANCEL)
 
        if request_name == "TL_account_updateStatus" and self.get_setting("force_offline", True):
            request.offline = True
            return HookResult(strategy=HookStrategy.MODIFY, request=request)
 
        return HookResult()
 
    def post_request_hook(self, request_name: str, account: int, response: Any, error: Any) -> HookResult:
        if request_name == "TL_messages_sendMessage" and not error:
            self.log("Successfully sent a message!")
        return HookResult()
 
    def create_settings(self) -> List[Any]:
        return [
            Switch(key="dont_send_typing", text="Don't send typing status", default=True),
            Switch(key="force_offline", text="Always appear offline", default=True),
        ]
```

--------------------------------

### Declare required plugins in metadata

Source: https://plugins.exteragram.app/docs/elyx/dependencies

Declare required plugins in metadata using the requires mapping. The installer reports a missing, disabled, or outdated required plugin and can offer a link for installation. This declaration checks availability but does not create a stable Python API between plugins.

```yaml
requires:
  helper_plugin: https://example.com/helper_plugin.elyx
  shared_runtime (2.1.0): https://example.com/shared_runtime.elyx
```

--------------------------------

### create_settings

Source: https://plugins.exteragram.app/docs/plugin-class

Implement this method to expose a settings screen for the plugin.

```APIDOC
## create_settings

### Description
Implement this method to expose a settings screen for the plugin.

### Method
create_settings

### Signature
```python
def create_settings(self) -> List[Any]
```

### Parameters
- **self** - The plugin instance.

### Returns
- **List[Any]** - A list of settings UI elements (e.g., Header, Switch).

### Example
```python
from typing import Any, List
from base_plugin import BasePlugin
from ui.settings import Header, Switch

class MyPlugin(BasePlugin):
    def create_settings(self) -> List[Any]:
        return [
            Header(text="General"),
            Switch(key="enabled", text="Enable feature", default=True),
        ]
```
```

--------------------------------

### Local source package directory structure

Source: https://plugins.exteragram.app/docs/elyx/dependencies

Example project structure for local source packages. Put the package directly in the project; it is namespaced per plugin and participates in live reload.

```text
vendor/
|-- __init__.py
`-- parser.py
```

--------------------------------

### Get Generated Java Class

Source: https://plugins.exteragram.app/docs/class-proxy

Shows how to retrieve the generated Java class object.

```python
proxy_java_class = MySubclass.java_class()
```

--------------------------------

### Package and namespace directory layout

Source: https://plugins.exteragram.app/docs/elyx/modules-and-imports

Layout showing both regular packages and namespace directories. Adding __init__.py is recommended so the same source tree works in desktop tooling and static analyzers.

```text
features/
|-- __init__.py     # optional
|-- links.py
`-- media/
    `-- images.py
```

--------------------------------

### Relative import example

Source: https://plugins.exteragram.app/docs/elyx/troubleshooting

Use this import when importing from another file inside the src directory.

```python
from .feature import Feature
```

--------------------------------

### Provide a ready Android View to Custom

Source: https://plugins.exteragram.app/docs/plugin-settings

Use this for static or already-constructed views. It is usually best for simple one-off views; if the row needs recycling, binding, click handling, or per-item behavior, prefer a factory.

```python
from android.widget import TextView
from ui.settings import Custom
 
 
label = TextView(context)
label.setText("Hello from a custom View")
 
setting = Custom(view=label)
```

--------------------------------

### SettingsController

Source: https://plugins.exteragram.app/docs/elyx/public-api

Documentation for the SettingsController class, a persistent settings wrapper with methods for getting and setting settings.

```APIDOC
## Settings

### `SettingsController(plugin_id)`

Persistent settings wrapper.

#### Methods
- `get_settings()`
- `get_setting(key, default=None)`
- `get(key, default=None)`
- `set_setting(key, value, reload_settings=False)`
- `set(key, value, reload_settings=False)`
- `clear_settings()`

#### Item access
- `controller[key]`
- `controller[key] = value`
- `controller(key, default)`
```

--------------------------------

### Show simple bulletin with custom icon (BulletinHelper.show_simple)

Source: https://plugins.exteragram.app/docs/bulletin-helper

Shows a single-line bulletin with a custom Lottie animation icon. The message and icon resource ID are passed directly; the fragment parameter is optional and defaults to null.

```python
BulletinHelper.show_simple("Processing...", R_tg.raw.timer, current_fragment)
```

--------------------------------

### Generated Java Class Declaration

Source: https://plugins.exteragram.app/docs/class-proxy

Illustrates the Java class declaration that the proxy system generates for the previous example.

```java
class GeneratedProxy extends FrameLayout implements CustomDelegate1, CustomDelegate2
```

--------------------------------

### Create the project directory tree

Source: https://plugins.exteragram.app/docs/elyx/quick-start

Shows the required directory structure for an Elyx plugin. The directory name is not used as metadata during installation, but keeping it equal to the plugin id simplifies local development.

```text
elyx_hello/
|-- refmap.yml
|-- metainfo.yml
|-- main.py
|-- src/
|   |-- __init__.py
|   `-- greeting.py
|-- assets/
|   `-- wave.svg
`-- strings/
    |-- strings_en.yml
    `-- strings_ru.yml

```

--------------------------------

### Using **kwargs

Source: https://plugins.exteragram.app/docs/intents

Shows how to define a callback that accepts **kwargs to receive the full available named context.

```APIDOC
## Callback: on_any_link(**kwargs)

### Description
Defines a callback that accepts **kwargs to receive the full available named context from the SDK.

### Method
N/A (SDK callback registration)

### Endpoint
N/A

### Parameters
#### Callback Parameters
- **kwargs** (dict) - Required - Contains all available named context values, including `intent`, `scheme`, `id`, `query_args`, `flags`, `categories`, and others.

### Request Example
```python
def on_any_link(**kwargs):
    print(kwargs["intent"])
    print(kwargs.get("scheme"))
    print(kwargs.get("id"))
    print(kwargs.get("query_args"))
    print(kwargs.get("flags"))
    print(kwargs.get("categories"))

IM.new_global_before_handler(on_any_link, scheme="tg")
```

### Response
No response; callback executes with the provided context.
```

--------------------------------

### Russian translation file strings_ru.yml

Source: https://plugins.exteragram.app/docs/elyx/localization

Example Russian translation file. Values may be strings, numbers, lists, or dictionaries.

```yaml
plugin_description: Добавляет полезные действия с приветствиями.
title: Приветствия
hello: "Привет, {name}!"
downloaded: "Загружено файлов: {count}"
file_forms:
  - файл
  - файла
  - файлов
```

--------------------------------

### English translation file strings_en.yml

Source: https://plugins.exteragram.app/docs/elyx/localization

Example English translation file. Values may be strings, numbers, lists, or dictionaries.

```yaml
plugin_description: Adds useful greeting actions.
title: Greetings
hello: "Hello, {name}!"
downloaded: "Downloaded {count} files"
file_forms:
  - file
  - files
  - files
```
Tokens:
Raw