messageLogger/docs/sdk-notes.md

exteraGram plugin SDK — condensed notes

Gathered from https://plugins.exteragram.app/docs, the SDK type stubs (stubs.zip from exteraSquad/plugins-pysdk-builds), the official exteragram-utils PyPI package (exteragram_utils/dev_client.py), and the app's gradle.properties. Not exhaustive — see the full docs site for anything not covered here.

Plugin identity and metadata

Read statically via AST from top-level constant assignments in the plugin's single .py file — the app never executes the file just to read metadata. Docs: https://plugins.exteragram.app/docs/metadata.

Constant	Required	Notes
__id__	yes	2–32 chars, starts with a letter, only A-Za-z0-9_-
__name__	yes	display name
__description__	no
__author__	no
__version__	no
__icon__	no	e.g. "exteraPlugins/1"
__app_version__	no	e.g. ">=12.5.1"; legacy alias __min_version__
__sdk_version__	no	e.g. ">=1.4.4.3"
__requirements__	no	list of pip package specs the host installs before loading

BasePlugin lifecycle and hooks

https://plugins.exteragram.app/docs/base-plugin

• on_plugin_load(self) — called once when the plugin is enabled/loaded. Hooks must be registered here (e.g. self.add_on_send_message_hook()); registering later has no effect.
• on_plugin_unload(self) — called on disable/removal; release resources here.
• create_settings(self) — returns a list of ui.settings rows rendered in the plugin's settings screen.
• Hooks: on_send_message_hook(self, account, params), pre_request_hook(self, ...), post_request_hook(self, ...), on_update_hook(s)(self, ...), on_app_event(self, ...). Each returns a HookResult.
• HookResult(strategy=HookStrategy.MODIFY, params=params) applies the mutated params back to the host; HookStrategy.DEFAULT (a bare HookResult()) passes through unchanged; HookStrategy.CANCEL drops the action; HookStrategy.MODIFY_FINAL applies changes and short-circuits any later hooks.
• Settings persistence: self.get_setting(key, default) / self.set_setting(key, value).

ui.settings row types

https://plugins.exteragram.app/docs/ui-settings

Header, Input, Switch, Text, Selector, Divider — plain kwargs-holding row descriptors consumed by the host's settings renderer; construct and return them from create_settings.

Logging

https://plugins.exteragram.app/docs/logging

android_utils.log(...) writes to logcat. Chaquopy additionally redirects sys.stdout/sys.stderr to the logcat tags python.stdout / python.stderr — useful when a dependency logs with plain print().

Background work

https://plugins.exteragram.app/docs/client-utils

client_utils.run_on_queue(...) schedules work off the UI thread; use it for anything that shouldn't block message handling.

Reflection / private API access

https://plugins.exteragram.app/docs/hook-utils

hook_utils.find_class(...) and related helpers locate app classes and private fields for plugins that need to reach beyond the public SDK surface.

UI helpers

• ui.alert.AlertDialogBuilder — native alert dialogs. https://plugins.exteragram.app/docs/ui-alert
• ui.bulletin — transient bottom bulletins/toasts. https://plugins.exteragram.app/docs/ui-bulletin
• intents.IntentsManager — Android intent integration, exteraGram 12.6.4+ only. https://plugins.exteragram.app/docs/intents

On-device dev server protocol

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

TCP 127.0.0.1:42690, reachable from a PC via adb forward tcp:42690 tcp:42690. Wire format is consecutive UTF-8 JSON objects with no length framing — parse with json.JSONDecoder().raw_decode over an accumulating buffer, never assume one JSON object per recv(). Requests: {"@": <command>, "#": <id>, ...}; responses echo "#".

Commands used by this repo's tools/devclient.py: ping, get_plugins, enable_plugin, disable_plugin, reload_plugin, remove_plugin (field plugin_id), write_plugin (plugin_id, content — installs or updates), start_debugger/stop_debugger (host, port, platform ∈ vscode|pycharm). The official exteragram-utils client (PyPI) uses integer request ids from 1, a 30 s response timeout, a 1.0 s socket timeout, a write_plugin → sleep 0.3 s → reload_plugin deploy sequence, and adb forward (not reverse) for both the dev-server port and the debugger port. elyx_* commands exist for the Elyx engine and are out of scope here.

Runtime

Chaquopy 16 / Python 3.11. Anything shipped in a bundle must be 3.11-compatible.

Why not Elyx/ElyxBuilder

The official structured plugin format (Elyx/ElyxBuilder) is a real alternative to a single .plugin file, but it:

• requires the separate Elyx engine to be installed and enabled on the device;
• ships archives, not the .plugin files the base plugin engine understands;
• needs a manual first install before live reload works.

This repo's bundler instead compiles a normal multi-file src/ project down to the one .plugin file the base engine already knows how to load, so the dev-server write/reload loop works from the first deploy with no extra on-device engine.

Gotchas found on exteraGram 12.10.6 (message_logger)

• Java number boxing. A Python int passed where Java takes Object, or to an overloaded method, becomes a Long — even the result of Integer.valueOf(). Use java.jint / jfloat explicitly: ArrayList<Integer> for TL_*_getMessages.id (a Long there fails serialization on the network thread and the request silently never answers), Paint.setColor (an int otherwise picks the setColor(long) ColorSpace overload), reflective Method.invoke arguments, and replacing param.args[i] in hooks.
• Requests. client_utils.send_request did not invoke the callback for these requests; ConnectionsManager.getInstance(account).sendRequest(req, RequestDelegate) with a dynamic_proxy(RequestDelegate) kept strongly referenced works (src/tg.py).
• Logs. This device's logcat is silenced; src/diag.py mirrors to …/files/exteraGram/exteraGram Files/message_logger/diag.log (readable over adb shell cat).
• Deploys. devclient.py deploy --enable only enables; an already enabled plugin needs a deploy without --enable (which reloads) to pick up a new build.
• Adding messages to an open chat. Inserting into ChatActivity.messages directly (not in messagesDict) breaks later arrivals in that chat; the private ChatActivity.processNewMessages(ArrayList, boolean) places messages (also older ones) and keeps the app's dicts and adapter consistent.
• Cell height. Changing a ChatMessageCell's measured height grows its bubble; after the state behind it changes, forceLayout() the cell and chatAdapter.notifyItemChanged(...), or the list keeps stale positions. Item animators reset cell alpha: scale it in a setAlpha before-hook instead of setting it once.
• Icon packs. exteraGram applies icon packs through the activity's ExteraResources (getDrawableForDensity); the application context's plain Resources and ColoredImageSpan(int) give stock icons. Load drawables from get_last_fragment().getParentActivity().getResources().
• Another account's chat. BaseFragment.setCurrentAccount(slot) before presentFragment opens e.g. a ChatActivity as another signed-in account without switching accounts.
• Links. Tapped links go through org.telegram.messenger.browser.Browser.openUrl (8 overloads, the second argument a Uri or String); adb shell am start -d URL needs -p <package>.
• Message menu rows. MenuItemData items land in the menu's Plugins folder, and options added to ChatActivity.fillMessageMenu's lists are dropped by exteraGram. A row in the main menu is an ActionBarMenuSubItem inserted into the built popup after createMenu (whose overloads call one another: insert once); selectedObject is the message.
• Topics as another account. ForumUtilities.openTopic uses the presenting fragment's account; do its steps yourself (TopicsController.findTopic/loadTopic, ChatActivity with setCurrentAccount then setThreadMessages) — see src/views/open_as.py.