slidge_whatsapp.session

Attributes

MESSAGE_PAIR_SUCCESS
MESSAGE_LOGGED_OUT
URL_SEARCH_REGEX
GEO_URI_SEARCH_REGEX
VIDEO_PREVIEW_DOMAINS
Recipient

Classes

Session	The session of a registered User.
Attachment	A file attachment to a message

Functions

ignore_contact_is_user(func)
strip_quote_prefix(text)	Return multi-line text without leading quote marks (i.e. the ">" character).
set_reply_to(chat, message[, reply_to_msg_id, ...])
get_url_bytes(client, url)
make_sync(func, loop)	Wrap async function in synchronous operation, running against the given loop in thread-safe mode.

Module Contents

slidge_whatsapp.session.MESSAGE_PAIR_SUCCESS = 'Pairing successful! You might need to repeat this process in the future if the Linked Device is...

slidge_whatsapp.session.MESSAGE_LOGGED_OUT = 'You have been logged out, please use the re-login adhoc command and re-scan the QR code on your...

slidge_whatsapp.session.URL_SEARCH_REGEX = '(?P<url>https?://[^\\s]+)'

slidge_whatsapp.session.GEO_URI_SEARCH_REGEX = 'geo:(?P<lat>-?\\d+(\\.\\d*)?),(?P<lon>-?\\d+(\\.\\d*)?)(;u=(?P<acc>-?\\d+(\\.\\d*)?))?'

slidge_whatsapp.session.VIDEO_PREVIEW_DOMAINS = ('https://youtube.com/watch', 'https://m.youtube.com/watch', 'https://youtu.be')

slidge_whatsapp.session.Recipient

slidge_whatsapp.session.ignore_contact_is_user(func)

class slidge_whatsapp.session.Session(user)

Bases: slidge.BaseSession[str, Recipient]

The session of a registered User.

Represents a gateway user logged in to the legacy network and performing actions.

Will be instantiated automatically on slidge startup for each registered user, or upon registration for new (validated) users.

Must be subclassed for a functional Legacy Module.

Parameters:

user (slidge.GatewayUser) –

xmpp: slidge_whatsapp.gateway.Gateway

The gateway instance singleton. Use it for low-level XMPP calls or custom methods that are not session-specific.

contacts: slidge_whatsapp.contact.Roster

bookmarks: slidge_whatsapp.group.Bookmarks

__presence_status: str = ''

user_phone: str | None = None

whatsapp_participants

whatsapp

__handle_event

migrate()

async login()

Initiate login process and connect session to WhatsApp. Depending on existing state, login might either return having initiated the Linked Device registration process in the background, or will re-connect to a previously existing Linked Device session.

async logout()

Disconnect the active WhatsApp session. This will not remove any local or remote state, and will thus allow previously authenticated sessions to re-authenticate without needing to pair.

async handle_event(event, ptr)

Handle incoming event, as propagated by the WhatsApp adapter. Typically, events carry all state required for processing by the Gateway itself, and will do minimal processing themselves.

async handle_chat_state(state)

Parameters:

state (slidge_whatsapp.generated.whatsapp.ChatState) –

async handle_receipt(receipt)

Handle incoming delivered/read receipt, as propagated by the WhatsApp adapter.

Parameters:

receipt (slidge_whatsapp.generated.whatsapp.Receipt) –

async handle_call(call)

Parameters:

call (slidge_whatsapp.generated.whatsapp.Call) –

async handle_message(message)

Handle incoming message, as propagated by the WhatsApp adapter. Messages can be one of many types, including plain-text messages, media messages, reactions, etc., and may also include other aspects such as references to other messages for the purposes of quoting or correction.

Parameters:

message (slidge_whatsapp.generated.whatsapp.Message) –

async on_text(chat, text, *, reply_to_msg_id=None, reply_to_fallback_text=None, reply_to=None, mentions=None, **_)

Send outgoing plain-text message to given WhatsApp contact.

Parameters:

• chat (Recipient) –

• text (str) –

• reply_to_msg_id (Optional[str]) –

• reply_to_fallback_text (Optional[str]) –

• mentions (Optional[list[slidge.util.types.Mention]]) –

async on_file(chat, url, http_response, reply_to_msg_id=None, reply_to_fallback_text=None, reply_to=None, **_)

Send outgoing media message (i.e. audio, image, document) to given WhatsApp contact.

Parameters:

• chat (Recipient) –

• url (str) –

• reply_to_msg_id (Optional[str]) –

• reply_to_fallback_text (Optional[str]) –

async on_presence(resource, show, status, resources, merged_resource)

Send outgoing availability status (i.e. presence) based on combined status of all connected XMPP clients.

Parameters:

• resource (str) –

• show (slidge.util.types.PseudoPresenceShow) –

• status (str) –

• resources (dict[str, slidge.util.types.ResourceDict]) –

• merged_resource (Optional[slidge.util.types.ResourceDict]) –

async on_active(c, thread=None)

WhatsApp has no equivalent to the “active” chat state, so calls to this function are no-ops.

Parameters:

c (Recipient) –

async on_inactive(c, thread=None)

WhatsApp has no equivalent to the “inactive” chat state, so calls to this function are no-ops.

Parameters:

c (Recipient) –

async on_composing(c, thread=None)

Send “composing” chat state to given WhatsApp contact, signifying that a message is currently being composed.

Parameters:

c (Recipient) –

async on_paused(c, thread=None)

Send “paused” chat state to given WhatsApp contact, signifying that an (unsent) message is no longer being composed.

Parameters:

c (Recipient) –

async on_displayed(c, legacy_msg_id, thread=None)

Send “read” receipt, signifying that the WhatsApp message sent has been displayed on the XMPP client.

Parameters:

• c (Recipient) –

• legacy_msg_id (str) –

async on_react(c, legacy_msg_id, emojis, thread=None)

Send or remove emoji reaction to existing WhatsApp message. Slidge core makes sure that the emojis parameter is always empty or a single emoji.

Parameters:

• c (Recipient) –

• legacy_msg_id (str) –

• emojis (list[str]) –

async on_retract(c, legacy_msg_id, thread=None)

Request deletion (aka retraction) for a given WhatsApp message.

Parameters:

• c (Recipient) –

• legacy_msg_id (str) –

async on_moderate(muc, legacy_msg_id, reason)

Triggered when the user attempts to retract a message that was sent in a MUC using XEP-0425.

If retraction is not possible, this should raise the appropriate XMPPError with a human-readable message.

NB: the legacy module is responsible for calling :method:`LegacyParticipant.moderate` when this is successful, because slidge will acknowledge the moderation IQ, but will not send the moderation message from the MUC automatically.

Parameters:

• muc (slidge_whatsapp.group.MUC) – The MUC in which the message was sent

• legacy_msg_id (str) – The legacy ID of the message to be retracted

• reason (Optional[str]) – Optionally, a reason for the moderation, given by the user-moderator.

async on_correct(c, text, legacy_msg_id, thread=None, link_previews=(), mentions=None)

Request correction (aka editing) for a given WhatsApp message.

Parameters:

• c (Recipient) –

• text (str) –

• legacy_msg_id (str) –

async on_avatar(bytes_, hash_, type_, width, height)

Update profile picture in WhatsApp for corresponding avatar change in XMPP.

Parameters:

• bytes_ (Optional[bytes]) –

• hash_ (Optional[str]) –

• type_ (Optional[str]) –

• width (Optional[int]) –

• height (Optional[int]) –

Return type:

None

async on_create_group(name, contacts)

Creates a WhatsApp group for the given human-readable name and participant list.

Parameters:

• name (str) –

• contacts (list[slidge_whatsapp.contact.Contact]) –

async on_leave_group(legacy_muc_id)

Removes own user from given WhatsApp group.

Parameters:

legacy_muc_id (str) –

async on_search(form_values)

Searches for, and automatically adds, WhatsApp contact based on phone number. Phone numbers not registered on WhatsApp will be ignored with no error.

Parameters:

form_values (dict[str, str]) –

message_is_carbon(c, legacy_msg_id)

Parameters:

• c (Recipient) –

• legacy_msg_id (str) –

__reset_connected()

__get_connected_status_message()

async __get_body(message, muc=None)

Parameters:

• message (slidge_whatsapp.generated.whatsapp.Message) –

• muc (Optional[slidge_whatsapp.group.MUC]) –

Return type:

str

async __get_reply_to(message, muc=None)

Parameters:

• message (slidge_whatsapp.generated.whatsapp.Message) –

• muc (Optional[slidge_whatsapp.group.MUC]) –

Return type:

Optional[slidge.util.types.MessageReference]

async __get_preview(text)

Parameters:

text (str) –

Return type:

Optional[slidge_whatsapp.generated.whatsapp.Preview]

async __get_location(text)

Parameters:

text (str) –

Return type:

Optional[slidge_whatsapp.generated.whatsapp.Location]

async __get_contact_or_participant(legacy_contact_id, legacy_group_jid)

Return either a Contact or a Participant instance for the given contact and group JIDs.

Parameters:

• legacy_contact_id (str) –

• legacy_group_jid (str) –

class slidge_whatsapp.session.Attachment

Bases: slidge.util.types.LegacyAttachment

A file attachment to a message

At the minimum, one of the path, steam, data or url attribute has to be set

To be used with LegacyContact.send_files() or LegacyParticipant.send_files()

static convert_list(attachments, muc=None)

Async:

Parameters:

• attachments (list) –

• muc (Optional[slidge_whatsapp.group.MUC]) –

Return type:

list[Attachment]

static convert(wa_attachment, muc=None)

Async:

Parameters:

• wa_attachment (slidge_whatsapp.generated.whatsapp.Attachment) –

• muc (Optional[slidge_whatsapp.group.MUC]) –

Return type:

Attachment

slidge_whatsapp.session.strip_quote_prefix(text)

Return multi-line text without leading quote marks (i.e. the “>” character).

Parameters:

text (str) –

slidge_whatsapp.session.set_reply_to(chat, message, reply_to_msg_id=None, reply_to_fallback_text=None, reply_to=None)

Parameters:

• chat (Recipient) –

• message (slidge_whatsapp.generated.whatsapp.Message) –

• reply_to_msg_id (Optional[str]) –

• reply_to_fallback_text (Optional[str]) –

async slidge_whatsapp.session.get_url_bytes(client, url)

Parameters:

• client (aiohttp.ClientSession) –

• url (str) –

Return type:

Optional[bytes]

slidge_whatsapp.session.make_sync(func, loop)

Wrap async function in synchronous operation, running against the given loop in thread-safe mode.