Models (astra.models)

Overview

Models provide typed views of bridge payloads. Main models are exposed below and documented via autodoc for quick reference.

class Message(*, _client=None, id='', chat_id, sender=None, body='', type=MessageType.TEXT, timestamp=0, from_me=False, is_forwarded=False, is_newsletter=False, is_poll=False, is_reaction=False, is_status=False, ack=MessageAck.SENT, is_editable=False, sender_name=None, pushname=None, verified_name=None, quoted_message_id=None, quoted_participant=None, quoted_type=None, has_quoted_msg=False, mentioned_jids=<factory>, subtype=None, recipients=<factory>, mimetype=None, size=None)[source]

Represents a complete WhatsApp message record.

This class manages message metadata, sender identity, status flags, and provides methods for responding to or modifying messages.

Parameters:

_client (Any)
id (str)
chat_id (JID)
sender (JID | None)
body (str)
type (MessageType)
timestamp (int)
from_me (bool)
is_forwarded (bool)
is_newsletter (bool)
is_poll (bool)
is_reaction (bool)
is_status (bool)
ack (MessageAck)
is_editable (bool)
sender_name (str | None)
pushname (str | None)
verified_name (str | None)
quoted_message_id (str | None)
quoted_participant (JID | None)
quoted_type (MessageType | None)
has_quoted_msg (bool)
mentioned_jids (List[JID])
subtype (str | None)
recipients (List[JID])
mimetype (str | None)
size (int | None)

property text: str: Alias for body for compatibility with EventContext.

property author: JID | None: Backward compatibility alias for sender.

property quoted_message: Message | None: Backward compatibility alias for quoted.

property quoted: Message | None: Returns the quoted message object if available. Note: This is a synchronous property, it doesn’t fetch from server. Only works if the quoted message was included in the payload.

property is_media: bool: True if the message contains media (image, video, audio, etc).

property is_service: bool: True if this is a system/service message (e.g. group join/leave).

classmethod from_payload(data, client=None)[source]

Translates a raw JS runtime payload into a typed Message object.

Parameters:

data (Dict[str, Any]) – The raw dictionary from the bridge.
client (Any) – Optional Astra client instance for action binding.

Returns:

A populated Message instance.

Return type:

Message

async reply(text)[source]

Sends a reply to this specific message.

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

async respond(text)[source]

Sends a message to the same chat as this message (without quoting).

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

async react(emoji)[source]

Reacts to this message with an emoji.

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

async edit(text)[source]

Edits this message.

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

async delete(for_everyone=True)[source]

Deletes this message.

Parameters:: for_everyone (bool)
Return type:: bool

async download()[source]

Downloads the media attached to this message and saves it to a temporary file. Returns: Absolute path to the saved file or None if download fails or no media is present.

Return type:: str | None

class Chat(id, title, is_group=False, is_readonly=False, unread_count=0, mute_expiration=0, last_message_timestamp=0, _client=None)[source]

Represents a conversational thread on WhatsApp.

Holds metadata about the chat such as its title, unread message count, and synchronization status.

Parameters:

id (JID)
title (str)
is_group (bool)
is_readonly (bool)
unread_count (int)
mute_expiration (int)
last_message_timestamp (int)
_client (Any)

async send_message(text, **kwargs)[source]

Sends a message directly to this chat.

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

async send_poll(question, options, **kwargs)[source]

Sends a poll message directly to this chat.

Parameters:

question (str)
options (list)

Return type:

Any

async react(message_id, emoji)[source]

Adds a reaction to a message in this chat.

Parameters:

message_id (str)
emoji (str)

Return type:

bool

async fetch_messages(limit=10, **kwargs)[source]

Fetches message history for this chat.

Parameters:: limit (int)
Return type:: list

async sync_history()[source]

Triggers a force sync for this chat’s history.

Return type:: bool

async archive(archive=True)[source]

Archives or unarchives this chat.

Parameters:: archive (bool)
Return type:: bool

async pin(pin=True)[source]

Pins or unpins this chat.

Parameters:: pin (bool)
Return type:: bool

async mute(duration=28800)[source]

Mutes this chat.

Parameters:: duration (int)
Return type:: bool

classmethod from_payload(data, client=None)[source]

Hydrates a Chat object from a raw bridge payload.

Parameters:

data (Dict[str, Any]) – Dictionary containing chat attributes.
client (Any)

Returns:

A Chat model instance.

Return type:

Chat

Example

>>> chat = Chat.from_payload({"id": "123@g.us", "name": "Hackers"})

class User(id, name=None, push_name=None, is_me=False, is_business=False, is_my_contact=False, verified_name=None, _client=None)[source]

Represents a WhatsApp Actor - a person, group participant, or yourself.

This class holds metadata about a contact or user, such as their display name and business status.

Parameters:

id (JID)
name (str | None)
push_name (str | None)
is_me (bool)
is_business (bool)
is_my_contact (bool)
verified_name (str | None)
_client (Any)

property title: str: Standardized title property for entity resolution.

async send_message(text, **kwargs)[source]

Sends a private message to this user.

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

async block()[source]

Blocks this user.

Return type:: bool

classmethod from_payload(data, client=None)[source]

Creates a User instance from a raw dictionary payload.

This is typically used when receiving data from the WhatsApp Web bridge.

Parameters:

data (Dict[str, Any]) – The raw dictionary containing user data.
client (Any)

Returns:

A populated User instance.

Return type:

User

class JID(user, server, serialized)[source]

Represents a WhatsApp Jabber ID (JID).

A JID uniquely identifies a user, group, or newsletter on WhatsApp. Example: ‘1234567890@c.us’ (User) or ‘1234567890@g.us’ (Group).

Parameters:

user (str)
server (str)
serialized (str)

classmethod parse(raw)[source]

Parses a raw JID string into a structured JID object.

Parameters:: raw (str) – The raw WhatsApp ID string (e.g., “12345@c.us”).
Returns:: A structured JID instance.
Return type:: JID

Example

>>> jid = JID.parse("12345@c.us")
>>> print(jid.user)
"12345"

property primary: str: Returns the primary (base) JID without device suffixes. Example: ‘12345:4@lid’ -> ‘12345@lid’

Important fields

Message.body / Message.text — message content
Message.id / Message.chat_id — unique identifiers
Message.is_media / Message.is_group — boolean status flags
Message.quoted — access to the replied-to message object
Chat.title / Chat.is_group — thread metadata

Example: converting a payload

from astra.protocol.serializers import DataTransformer
message = DataTransformer.to_message(raw_payload, client)

Async notes

Model constructors are synchronous; hydration occurs from bridge results

(synchronous mapping in Python after an async bridge call).