slidge.plugins.whatsapp#

WhatsApp gateway using the multi-device API.

Subpackages#

Submodules#

Package Contents#

Classes#

Gateway

Must be subclassed by a plugin to set up various aspects of the XMPP

Session

Represents a gateway user logged in to the legacy network and performing actions.
class slidge.plugins.whatsapp.Gateway[source]#

Bases: slidge.BaseGateway

Must be subclassed by a plugin to set up various aspects of the XMPP component behaviour, such as its display name or its registration process.

On slidge launch, a singleton is instantiated, and it will be made available to public classes such LegacyContact or BaseSession as the .xmpp attribute. Since it inherits from slixmpp.componentxmpp.ComponentXMPP, this gives you a hand on low-level XMPP interactions via slixmpp plugins, e.g.:

self.send_presence(
    pfrom="somebody@component.example.com",
    pto="someonwelse@anotherexample.com",
)

However, you should not need to do so often since the classes of the plugin API provides higher level abstractions around most commonly needed use-cases, such as sending messages, or displaying a custom status.

COMPONENT_NAME = 'WhatsApp (slidge)'#
COMPONENT_TYPE = 'whatsapp'#
COMPONENT_AVATAR = 'https://www.whatsapp.com/apple-touch-icon.png'#
REGISTRATION_INSTRUCTIONS#
WELCOME_MESSAGE#
REGISTRATION_FIELDS = []#
ROSTER_GROUP = 'WhatsApp'#
MARK_ALL_MESSAGES = True#
GROUPS = True#
PROPER_RECEIPTS = True#
async unregister(user)#

Optionally override this if you need to clean additional stuff after a user has been removed from the permanent user_store.

You may need to manually logout the legacy session in here, Session.logout() will not be called automatically.

Parameters:

user (slidge.GatewayUser) –

class slidge.plugins.whatsapp.Session(user)[source]#

Bases: slidge.BaseSession[str, Recipient]

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

Will be instantiated automatically when a user sends an online presence to the gateway component, as per XEP-0100.

Must be subclassed for a functional slidge plugin.

Parameters:

user (slidge.GatewayUser) –

xmpp: slidge.plugins.whatsapp.gateway.Gateway#
contacts: slidge.plugins.whatsapp.contact.Roster#
bookmarks: slidge.plugins.whatsapp.group.Bookmarks#
shutdown()#
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()#

Logout from the active WhatsApp session. This will also force a remote log-out, and thus require pairing on next login. For simply disconnecting the active session, look at the Session.disconnect() function.

async disconnect()#

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.plugins.whatsapp.generated.whatsapp.ChatState) –

async handle_receipt(receipt)#

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

Parameters:

receipt (slidge.plugins.whatsapp.generated.whatsapp.Receipt) –

async handle_call(call)#
Parameters:

call (slidge.plugins.whatsapp.generated.whatsapp.Call) –

async _get_reply_to(message)#
Parameters:

message (slidge.plugins.whatsapp.generated.whatsapp.Message) –

async _get_preview(text)#
Parameters:

text (str) –

Return type:

Optional[slidge.plugins.whatsapp.generated.whatsapp.Preview]

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.plugins.whatsapp.generated.whatsapp.Message) –

async send_text(chat, text, *, reply_to_msg_id=None, reply_to_fallback_text=None, reply_to=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]) –

async send_file(chat, url, http_response, reply_to_msg_id=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]) –

async 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 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 composing(c, thread=None)#

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

Parameters:

c (Recipient) –

async 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 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 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 retract(c, legacy_msg_id, thread=None)#

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

Parameters:

  • c (Recipient) –

  • legacy_msg_id (str) –

async correct(c, text, legacy_msg_id, thread=None)#

Triggered when the user corrected a message using XEP-0308

This is only possible if a valid legacy_msg_id was passed when transmitting a message from a contact to the user in LegacyContact.send_text() or slidge.LegacyContact.send_file().

Parameters:

  • text (str) –

  • legacy_msg_id (str) –

  • c (Recipient) –

async search(form_values)#

Triggered when the user uses Jabber Search (XEP-0055) on the component

Form values is a dict in which keys are defined in BaseGateway.SEARCH_FIELDS

Parameters:

form_values (dict[str, str]) – search query, defined for a specific plugin by overriding in BaseGateway.SEARCH_FIELDS

Returns:

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) –

_is_carbon(c, legacy_msg_id)#
Parameters:

  • c (Recipient) –

  • legacy_msg_id (str) –