Protocol (astra.protocol)

Overview

The protocol layer is the bridge between Python and the injected JavaScript engine running inside the browser page. It exposes two main primitives:

class ProtocolBridge(page=None)[source]

Manages the two-way bridge between Python and JavaScript.

This class handles the injection of the Astra engine into the browser and facilitates calling remote methods with automatic result normalization.

Parameters:: page (playwright.async_api.Page | None)

async connect()[source]

Initializes the bridge by injecting the core engine scripts.

This method uses persistent init scripts to ensure the bridge survives page reloads and navigations.

async call(method, params=None, timeout=15.0, progress=None)[source]

Calls a remote JS method via the bridge with automatic recovery.

If the bridge is unreachable (page closed, bridge missing), it attempts a single self-heal via ensure_bridge() before retrying.

Parameters:

method (str)
params (Any)
timeout (float)
progress (Callable | None)

Return type:

Any

async ensure_bridge()[source]

Verifies the JS bridge is alive and re-injects it if needed.

Returns True if the bridge is healthy after this call.

Return type:: bool

async get_bridge_diagnostics()[source]

Returns a structured health snapshot of the JS bridge.

Return type:: Dict[str, Any]

set_event_handler(handler)[source]

Sets the sink for incoming browser events.

Parameters:: handler (Callable[[str, Any], Awaitable[None]])

async execute(code)[source]

Executes raw JavaScript in the page context. This is used for bootstrapping and complex low-level operations.

Parameters:: code (str)
Return type:: Any

async edit_message_native(message_id, text)[source]

High-speed native Playwright fallback for editing messages.

Parameters:

message_id (str)
text (str)

Return type:

bool

async set_privacy_native(category, value)[source]: Playwright fallback: Settings → Privacy → Category → Select.

async set_profile_name_native(name)[source]: Playwright fallback for updating profile name.

async set_about_native(text)[source]: Playwright fallback for updating About/Bio.

class EngineAPI(bridge, client=None)[source]

Interface for WhatsApp engine operations.

This class handles calls to the ProtocolBridge and translates the responses into Python objects.

Parameters:

bridge (ProtocolBridge)
client (Any)

async send_text(chat_id, text, options=None)[source]

Sends a text message to a chat.

Parameters:

chat_id (str)
text (str)
options (dict)

Return type:

Message

async send_poll(to, question, options, poll_options=None)[source]

Creates and sends a poll.

Parameters:

to (str)
question (str)
options (List[str])
poll_options (Dict[str, Any] | None)

Return type:

Message

async react(message_id, emoji)[source]

Adds a reaction to a message.

Parameters:

message_id (str)
emoji (str)

Return type:

bool

async delete_message(message_id, for_everyone=True)[source]

Removes a message from the thread.

Parameters:

message_id (str)
for_everyone (bool)

Return type:

bool

async bulk_delete(message_ids, for_everyone=True)[source]

Removes multiple messages from the thread.

Parameters:

message_ids (List[str])
for_everyone (bool)

Return type:

bool

async edit_message(message_id, text)[source]

Edits a previously sent message.

Parameters:

message_id (str)
text (str)

Return type:

bool

async fetch_messages(chat_id, options=None)[source]

Loads earlier messages for a chat.

Parameters:

chat_id (str)
options (Dict[str, Any] | None)

Return type:

List[Message]

async sync_history(chat_id)[source]

Triggers a peer data operation request to sync history.

Parameters:: chat_id (str)
Return type:: bool

async send_media(to, media, mimetype, filename=None, caption=None, options=None)[source]

Sends a media file.

Parameters:

to (str)
media (str)
mimetype (str)
filename (str | None)
caption (str | None)
options (dict)

Return type:

Message

async create_group(title, participants)[source]

Creates a new group with the specified title and members. Returns the new Group ID.

Parameters:

title (str)
participants (List[str])

Return type:

str

async add_members(group_id, participants)[source]

Adds new participants to a group.

Parameters:

group_id (str)
participants (List[str])

Return type:

bool

async remove_members(group_id, participants)[source]

Kicks participants from a group.

Parameters:

group_id (str)
participants (List[str])

Return type:

bool

async promote(group_id, participants)[source]

Promotes participants to admin in a group.

Parameters:

group_id (str)
participants (List[str])

Return type:

bool

async demote(group_id, participants)[source]

Demotes participants from admin in a group.

Parameters:

group_id (str)
participants (List[str])

Return type:

bool

async get_group_info(group_id)[source]

Retrieves detailed info about a group.

Parameters:: group_id (str)
Return type:: Dict[str, Any]

async get_invite_link(group_id)[source]

Generates a group invite link.

Parameters:: group_id (str)
Return type:: str

async get_me()[source]

Gets the authenticated user’s profile.

Return type:: User

async sync_data()[source]

Performs a deep sync of metadata from the server.

Return type:: bool

async send_status(text, options=None)[source]

Posts a text status update.

Parameters:

text (str)
options (Dict[str, Any] | None)

Return type:

bool

async send_media_status(data, mimetype, caption='', options=None)[source]

Sends a media status update.

Parameters:

data (str)
mimetype (str)
caption (str)
options (Dict[str, Any] | None)

Return type:

bool

async get_status_viewers(message_id)[source]

Retrieves the list of viewers for a status message.

Parameters:: message_id (str)
Return type:: List[Dict[str, Any]]

async set_profile_name(name)[source]

Updates the user’s pushname. JS bridge first → Playwright keyboard fallback.

Parameters:: name (str)
Return type:: bool

async set_about_text(text)[source]

Updates the user’s ‘About’ text content. JS bridge first → Playwright keyboard fallback.

Parameters:: text (str)
Return type:: bool

async update_profile_pic(media)[source]

Updates the authenticated user’s profile picture.

Parameters:: media (str)
Return type:: bool

async update_group_pic(group_id, media)[source]

Updates a group’s profile picture.

Parameters:

group_id (str)
media (str)

Return type:

bool

async set_privacy(category, value)[source]

Sets a privacy setting. Categories: ‘last_seen’, ‘profile_pic’, ‘about’, ‘status’, ‘read_receipts’ JS bridge first → Playwright keyboard/mouse fallback.

Parameters:

category (str)
value (str)

Return type:

bool

async get_privacy_settings()[source]

Retrieves current privacy settings.

Return type:: Dict[str, Any]

async get_contact(contact_id)[source]

Fetches metadata for a specific contact.

Parameters:: contact_id (str)
Return type:: User

async get_chat(chat_id)[source]

Fetches a specific chat thread.

Parameters:: chat_id (str)
Return type:: Chat

async get_chats()[source]

Fetches all chats.

Return type:: List[Chat]

async scan_dom(section)[source]

Performs a deep DOM scan of a specific section.

Parameters:: section (str)
Return type:: List[Dict[str, Any]]

async generate_dom_report(section)[source]

Generates a detailed text report of stable selectors in a section.

Parameters:: section (str)
Return type:: str

async logout()[source]

Terminated the current session and logs out.

Return type:: bool

async send_chat_state(chat_id, state)[source]

Sets the chat state (typing, recording, clear).

Parameters:

chat_id (str)
state (str)

Return type:

bool

Public highlights

ProtocolBridge.connect() — inject engine and expose uplink
ProtocolBridge.call(method, params) — remote call to JS engine
EngineAPI.send_text / send_media / get_chats etc.

Example

bridge = ProtocolBridge()
await bridge.connect()
result = await bridge.call('getChats')

Notes

Bridge calls are proxied to the JS engine and return serializable JSON-like

results. DataTransformer maps the payloads into Python models.

Call timeouts and progress callbacks are supported by ProtocolBridge.