Plugin API#

With from slidge import * you get access to these classes. At the very minimum, BaseGateway and BaseSession must be subclassed for a plugin to work.

The main slidge entrypoint will automatically detect which classes have been subclassed and use them automagically. Just subclass away, and launch your plugin with slidge --legacy-network=your.importable.plugin.

class 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_AVATAR: bytes | str | Path | None = None#: Path, bytes or URL used by the component as an avatar.

COMPONENT_NAME: str = NotImplemented#: Name of the component, as seen in service discovery by XMPP clients

COMPONENT_TYPE: str | None = ''#: Type of the gateway, should ideally follow https://xmpp.org/registrar/disco-categories.html

MARK_ALL_MESSAGES = False#: Set this to True for legacy networks that expects read marks for all messages and not just the latest one that was read (as most XMPP clients will only send a read mark for the latest msg).

PROPER_RECEIPTS = False#: Set this to True if the legacy service provides a real equivalent of message delivery receipts (XEP-0184), meaning that there is an event thrown when the actual device of a contact receives a message. Make sure to call Contact.received() adequately if this is set to True.

REGISTRATION_FIELDS: Collection[FormField] = [FormField(var='username', label='User name', required=True, private=False, type='text-single', value='', options=None, image_url=None), FormField(var='password', label='Password', required=True, private=True, type='text-private', value='', options=None, image_url=None)]#: Iterable of fields presented to the gateway user when registering using XEP-0077 extended by XEP-0004.

REGISTRATION_INSTRUCTIONS: str = 'Enter your credentials'#: The text presented to a user that wants to register (or modify) their legacy account configuration.

REGISTRATION_TYPE = 0#

SINGLE_STEP_FORM: 1 step, 1 form, compatible with XEP-0077 (in-band registration)

QRCODE: The registration requires flashing a QR code in an official client. See BaseGateway.()

TWO_FACTOR_CODE: The registration requires confirming login with a 2FA code

ROSTER_GROUP: str = 'slidge'#: Roster entries added by the plugin in the user’s roster will be part of the group specified here.

SEARCH_FIELDS: Sequence[FormField] = [FormField(var='first', label='First name', required=True, private=False, type='text-single', value='', options=None, image_url=None), FormField(var='last', label='Last name', required=True, private=False, type='text-single', value='', options=None, image_url=None), FormField(var='phone', label='Phone number', required=False, private=False, type='text-single', value='', options=None, image_url=None)]#

Fields used for searching items via the component, through XEP-0055 (jabber search). A common use case is to allow users to search for legacy contacts by something else than their usernames, eg their phone number.

Plugins should implement search by overriding BaseSession.search(), effectively restricting search to registered users by default.

If there is only one field, it can also be used via the jabber:iq:gateway protocol described in XEP-0100. Limitation: this only works if the search request returns one result item, and if this item has a ‘jid’ var.

SEARCH_INSTRUCTIONS: str = ''#: Instructions of the search form.

SEARCH_TITLE: str = 'Search for legacy contacts'#: Title of the search form.

WELCOME_MESSAGE = "Thank you for registering. Type 'help' to list the available commands, or just start messaging away!"#: A welcome message displayed to users on registration. This is useful notably for clients that don’t consider component JIDs as a valid recipient in their UI, yet still open a functional chat window on incoming messages from components.

async confirm_qr(user_bare_jid, exception=None)#

Plugins should call this to complete registration with QR codes

Parameters:

user_bare_jid (str) – The not-yet-fully-registered GatewayUser instance Use their .bare_jid and/or``.registration_form`` attributes to get what you need
exception (Exception | None) – Optionally, an XMPPError to be raised to not confirm QR code flashing.

exception(exception)#

Called when a task created by slixmpp’s internal (eg, on slix events) raises an Exception.

Stop the event loop and exit on unhandled exception.

The default slixmpp.basexmpp.BaseXMPP behaviour is just to log the exception, but we want to avoid undefined behaviour.

Parameters:: exception (Exception) – An unhandled Exception object.

async get_qr_text(user)#

Plugins should call this to complete registration with QR codes

Parameters:: user (GatewayUser) – The not-yet-fully-registered GatewayUser. Use its .bare_jid and/or``.registration_form`` attributes to get what you need
Return type:: str

async input(jid, text=None, mtype='chat', **msg_kwargs)#

Request arbitrary user input using a simple chat message, and await the result.

You shouldn’t need to call directly bust instead use BaseSession.input() to directly target a user.

NB: When using this, the next message that the user sent to the component will not be transmitted to BaseGateway.on_gateway_message(), but rather intercepted. Await the coroutine to get its content.

Parameters:

jid (JID) – The JID we want input from
text – A prompt to display for the user
mtype (Literal['chat', 'error', 'groupchat', 'headline', 'normal']) – Message type

Returns:

The user’s reply

Return type:

str

async send_qr(text, **msg_kwargs)#

Sends a QR Code to a JID

Parameters:

text (str) – The text that will be converted to a QR Code
msg_kwargs – Optional additional arguments to pass to BaseGateway.send_file(), such as the recipient of the QR code.

send_raw(data)#

Send raw data across the stream.

Parameters:: data (string) – Any bytes or utf-8 string value.

shutdown()#

Called by the slidge entrypoint on normal exit.

Sends offline presences from all contacts of all user sessions and from the gateway component itself. No need to call this manually, slidge.__main__.main() should take care of it.

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

async user_prevalidate(ifrom, form_dict)#

Pre validate a registration form using the content of self.REGISTRATION_FIELDS before passing it to the plugin custom validation logic.

Parameters:

ifrom (JID) –
form_dict (dict[str, Optional[str]]) –

async validate(user_jid, registration_form)#

Validate a registration form from a user.

Since XEP-0077 is pretty limited in terms of validation, it is OK to validate anything that looks good here and continue the legacy auth process via direct messages to the user (using BaseGateway.input() for instance).

Parameters:

user_jid (JID) – JID of the user that has just registered
registration_form (dict[str, Optional[str]]) – A dict where keys are the FormField.var attributes of the BaseGateway.REGISTRATION_FIELDS iterable

async validate_two_factor_code(user, code)#

Called when the user enters their 2FA code.

Should raise the appropriate XMPPError if the login fails

Parameters:

user (GatewayUser) – The gateway user whose registration is pending Use their .bare_jid and/or``.registration_form`` attributes to get what you need
code (str) – The code they entered, either via “chatbot” message or adhoc command

class slidge.BaseSession(user)[source]#

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

MESSAGE_IDS_ARE_THREAD_IDS = False#: Set this to True if the legacy service uses message IDs as thread IDs, eg Mattermost, where you can only ‘create a thread’ by replying to the message, in which case the message ID is also a thread ID (and all messages are potential threads).

async active(c, thread=None)#

Triggered when the user sends an ‘active’ chat state to the legacy network (XEP-0085)

Parameters:

c (RecipientType) – RecipientType of the active chat state
thread (LegacyThreadType | None) –

async composing(c, thread=None)#

Triggered when the user starts typing in the window of a legacy contact (XEP-0085)

Parameters:

c (RecipientType) –
thread (LegacyThreadType | None) –

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 (LegacyMessageType) –
c (RecipientType) –
thread (LegacyThreadType | None) –

Return type:

LegacyMessageType | None

async displayed(c, legacy_msg_id, thread=None)#

Triggered when the user reads a message sent by a legacy contact. (XEP-0333)

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

Parameters:

legacy_msg_id (LegacyMessageType) – Identifier of the message, passed to slidge.LegacyContact.send_text() or slidge.LegacyContact.send_file()
c (RecipientType) –
thread (LegacyThreadType | None) –

classmethod from_stanza(s)#

Get a user’s LegacySession using the “from” field of a stanza

Meant to be called from BaseGateway only.

Parameters:: s –
Returns:
Return type:: BaseSession

async inactive(c, thread=None)#

Triggered when the user sends an ‘inactive’ chat state to the legacy network (XEP-0085)

Parameters:

c (RecipientType) –
thread (LegacyThreadType | None) –

async input(text, **msg_kwargs)#

Request user input via direct messages.

Wraps call to BaseSession.input()

Parameters:

text (str) – The prompt to send to the user
msg_kwargs – Extra attributes

Returns:

static legacy_msg_id_to_xmpp_msg_id(legacy_msg_id)#

Convert a legacy msg ID to a valid XMPP msg ID. Needed for read marks and message corrections.

The default implementation just converts the legacy ID to a str, but this should be overridden in case some characters needs to be escaped, or to add some additional, legacy network-specific logic.

Parameters:: legacy_msg_id (LegacyMessageType) –
Returns:: Should return a string that is usable as an XMPP stanza ID
Return type:: str

async login()#

Triggered when the gateway start and on user registration. It is recommended that this function returns once the user is logged in, so if you need to await forever (for instance to listen to incoming events), it’s a good idea to wrap your listener in an asyncio.Task.

Returns:: Optionally, a text to use as the gateway status, e.g., “Connected as ‘dude@legacy.network’”
Return type:: str | None

async logout()#

Logout the gateway user from the legacy network.

Called on user unregistration and gateway shutdown.

async on_subscribe(p)#

Called when receiving a “subscribe” presence, which is more or less a “friend request”.

Right now, this is mostly a placeholder for a future friend request workflow, but is useful to ensure avatars and nicks ard broadcast when XEP-0356 is not available for slidge

Parameters:: p (Presence) –

async on_subscribed(p)#

Called when receiving a “subscribed” presence, confirming that a contact is in the roster.

Right now, this is mostly a placeholder for a future friend request workflow, but is useful to ensure avatars and nicks ard broadcast when XEP-0356 is not available for slidge

Parameters:: p (Presence) –

async paused(c, thread=None)#

Triggered when the user pauses typing in the window of a legacy contact (XEP-0085)

Parameters:

c (RecipientType) –
thread (LegacyThreadType | None) –

re_login()#

Logout then re-login

No reason to override this

async react(c, legacy_msg_id, emojis, thread=None)#

Triggered when the user sends message reactions (XEP-0444).

Parameters:

legacy_msg_id (LegacyMessageType) – ID of the message the user reacts to
emojis (list[str]) – Unicode characters representing reactions to the message legacy_msg_id. An empty string means “no reaction”, ie, remove all reactions if any were present before
c (RecipientType) – Contact or MUC the reaction refers to
thread (LegacyThreadType | None) –

async retract(c, legacy_msg_id, thread=None)#

Triggered when the user retracts (XEP-0424) a message.

Parameters:

legacy_msg_id (LegacyMessageType) – Legacy ID of the retracted message
c (RecipientType) – The contact this retraction refers to
thread (LegacyThreadType | None) –

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:
Return type:: SearchResult | None

async send_file(chat, url, *, http_response, reply_to_msg_id=None, reply_to_fallback_text=None, reply_to=None, thread=None)#

Triggered when the user has sends a file using HTTP Upload (XEP-0363)

Parameters:

url (str) – URL of the file
chat (RecipientType) – See BaseSession.send_text()
http_response (ClientResponse) – The HTTP GET response object on the URL
reply_to_msg_id (LegacyMessageType | None) – See BaseSession.send_text()
reply_to_fallback_text (str | None) – See BaseSession.send_text()
reply_to (LegacyContact | LegacyParticipant | None) – See BaseSession.send_text()
thread (LegacyThreadType | None) –

Returns:

An ID of some sort that can be used later to ack and mark the message as read by the user

Return type:

LegacyMessageType | None

send_gateway_message(text, **msg_kwargs)#

Send a message from the gateway component to the user.

Can be used to indicate the user session status, ie “SMS code required”, “connected”, …

Parameters:: text – A text

send_gateway_status(status=None, show=typing.Optional[typing.Literal['away', 'chat', 'dnd', 'xa']], **kwargs)#

Send a presence from the gateway to the user.

Can be used to indicate the user session status, ie “SMS code required”, “connected”, …

Parameters:

status (str | None) – A status message
show – Presence stanza ‘show’ element. I suggest using “dnd” to show that the gateway is not fully functional

async send_qr(text)#

Sends a QR code generated from ‘text’ via HTTP Upload and send the URL to self.user

Parameters:: text (str) – Text to encode as a QR code

async send_text(chat, text, *, reply_to_msg_id=None, reply_to_fallback_text=None, reply_to=None, thread=None)#

Triggered when the user sends a text message from XMPP to a bridged entity, e.g. to translated_user_name@slidge.example.com, or translated_group_name@slidge.example.com

Override this and implement sending a message to the legacy network in this method.

Parameters:

text (str) – Content of the message
chat (RecipientType) – RecipientType of the message. LegacyContact instance for 1:1 chat, MUC instance for groups.
reply_to_msg_id (LegacyMessageType | None) – A legacy message ID if the message references (quotes) another message (XEP-0461)
reply_to_fallback_text (str | None) – Content of the quoted text. Not necessarily set by XMPP clients
reply_to (Sender | None) – Author of the quoted message. LegacyContact instance for 1:1 chat, LegacyParticipant instance for groups. If None, should be interpreted as a self-reply if reply_to_msg_id is not None.
thread (LegacyThreadType | None) –

Returns:

An ID of some sort that can be used later to ack and mark the message as read by the user

Return type:

LegacyMessageType | None

sent: BiDict[LegacyMessageType, str]#: Since we cannot set the XMPP ID of messages sent by XMPP clients, we need to keep a mapping between XMPP IDs and legacy message IDs if we want to further refer to a message that was sent by the user. This also applies to ‘carboned’ messages, ie, messages sent by the user from the official client of a legacy network.

async wait_for_ready(timeout=10)#

Wait until session, contacts and bookmarks are ready

(slidge internal use)

Parameters:: timeout (int | float | None) –
Returns:

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

static xmpp_msg_id_to_legacy_msg_id(i)#

Convert a legacy XMPP ID to a valid XMPP msg ID. Needed for read marks and message corrections.

The default implementation just converts the legacy ID to a str, but this should be overridden in case some characters needs to be escaped, or to add some additional, legacy network-specific logic.

The default implementation is an identity function

Parameters:: i (str) – The XMPP stanza ID
Returns:: An ID that can be used to identify a message on the legacy network
Return type:: LegacyMessageType

You may get away with the generic versions of these twos, but depending on how users are identified on a legacy network, you might need to subclass the following classes.

Even if you use their generic implementations, you most likely will need to call the methods they provide.

class slidge.LegacyRoster(session)#

Virtual roster of a gateway user, that allows to represent all of their contacts as singleton instances (if used properly and not too bugged).

Every BaseSession instance will have its own LegacyRoster instance accessible via the BaseSession.contacts attribute.

Typically, you will mostly use the LegacyRoster.by_legacy_id() function to retrieve a contact instance.

You might need to override LegacyRoster.legacy_id_to_jid_username() and/or LegacyRoster.jid_username_to_legacy_id() to incorporate some custom logic if you need some characters when translation JID user parts and legacy IDs.

Parameters:: session (BaseSession) –

async by_jid(contact_jid)#

Retrieve a contact by their JID

If the contact was not instantiated before, it will be created using slidge.LegacyRoster.jid_username_to_legacy_id() to infer their legacy user ID.

Parameters:: contact_jid (JID) –
Returns:
Return type:: LegacyContactType

async by_legacy_id(legacy_id, *args, **kwargs)#

Retrieve a contact by their legacy_id

If the contact was not instantiated before, it will be created using slidge.LegacyRoster.legacy_id_to_jid_username() to infer their legacy user ID.

Parameters:

legacy_id (LegacyUserIdType) –
args – arbitrary additional positional arguments passed to the contact constructor. Requires subclassing LegacyContact.__init__ to accept those. This is useful for networks where you fetch the contact list and information about these contacts in a single request
kwargs – arbitrary keyword arguments passed to the contact constructor

Returns:

Return type:

LegacyContactType

async by_stanza(s)#

Retrieve a contact by the destination of a stanza

See slidge.Roster.by_legacy_id() for more info.

Parameters:: s –
Returns:
Return type:: LegacyContact

async fill()#

Populate slidge’s “virtual roster”.

Override this and in it, await self.by_legacy_id(contact_id) for the every legacy contacts of the user for which you’d like to set an avatar, nickname, vcard…

Await Contact.add_to_roster() in here to add the contact to the user’s XMPP roster.

async jid_username_to_legacy_id(jid_username)#

Convert a JID user part to a legacy ID.

Should be overridden in case legacy IDs are not strings, or more generally for any case where the username part of a JID (unescaped with to the mapping defined by XEP-0106) is not enough to identify a contact on the legacy network.

Default implementation is an identity operation

Parameters:: jid_username (str) – User part of a JID, ie “user” in “user@example.com”
Returns:: An identifier for the user on the legacy network.
Return type:: LegacyUserIdType

async legacy_id_to_jid_username(legacy_id)#

Convert a legacy ID to a valid ‘user’ part of a JID

Should be overridden for cases where the str conversion of the legacy_id is not enough, e.g., if it is case-sensitive or contains forbidden characters not covered by XEP-0106.

Parameters:: legacy_id (LegacyUserIdType) –
Return type:: str

class slidge.LegacyContact(session, legacy_id, jid_username)#

This class centralizes actions in relation to a specific legacy contact.

You shouldn’t create instances of contacts manually, but rather rely on LegacyRoster.by_legacy_id() to ensure that contact instances are singletons. The LegacyRoster instance of a session is accessible through the BaseSession.contacts attribute.

Typically, your plugin should have methods hook to the legacy events and call appropriate methods here to transmit the “legacy action” to the xmpp user. This should look like this:

Use carbon=True as a keyword arg for methods to represent an action FROM the user TO the contact, typically when the user uses an official client to do an action such as sending a message or marking as message as read. This will use XEP-0363 to impersonate the XMPP user in order.

Parameters:

session (BaseSession) – The session this contact is part of
legacy_id (LegacyUserIdType) – The contact’s legacy ID
jid_username (str) – User part of this contact’s ‘puppet’ JID. NB: case-insensitive, and some special characters are not allowed

RESOURCE: str = 'slidge'#: A full JID, including a resource part is required for chat states (and maybe other stuff) to work properly. This is the name of the resource the contacts will use.

ack(legacy_msg_id, **kwargs)#

Send an “acknowledged” message marker (XEP-0333) from this contact to the user.

Parameters:: legacy_msg_id (LegacyMessageType) – The message this marker refers to

active(**kwargs)#: Send an “active” chat state (XEP-0085) from this contact to the user.

async add_to_roster()#: Add this contact to the user roster using XEP-0356

async available_emojis(legacy_msg_id=None)#

Override this to restrict the subset of reactions this recipient can handle.

Returns:: A set of emojis or None if any emoji is allowed
Parameters:: legacy_msg_id (LegacyMessageType | None) –
Return type:: set[str] | None

property avatar#: An image that represents this contact

away(status=None, last_seen=None)#

Send an “away” presence from this contact to the user.

This is a global status, as opposed to LegacyContact.inactive() which concerns a specific conversation, ie a specific “chat window”

Parameters:

status (str | None) – Arbitrary text, details of the status, eg: “Gone to fight capitalism”
last_seen (datetime | None) – For XEP-0319

busy(status=None, last_seen=None)#

Send a “busy” (ie, “dnd”) presence from this contact to the user,

Parameters:

status (str | None) – eg: “Trying to make sense of XEP-0100”
last_seen (datetime | None) – For XEP-0319

composing(**kwargs)#: Send a “composing” (ie “typing notification”) chat state (XEP-0085) from this contact to the user.

correct(legacy_msg_id, new_text, *, when=None, reply_to=None, thread=None, hints=None, carbon=False, archive_only=False, **send_kwargs)#

Call this when a legacy contact has modified his last message content.

Uses last message correction (XEP-0308)

Parameters:

new_text (str) – New content of the message
legacy_msg_id (LegacyMessageType) – The legacy message ID of the message to correct
when (datetime | None) – when the message was sent, for a “delay” tag (XEP-0203)
reply_to (MessageReference | None) – Quote another message (XEP-0461)
hints (Iterable[Literal['no-store', 'markable', 'store']] | None) –
thread (LegacyThreadType | None) –
carbon – (only in 1:1) Reflect a message sent to this Contact by the user. Use this to synchronize outgoing history for legacy official apps.
archive_only – (only in groups) Do not send this message to user, but store it in the archive. Meant to be used during MUC.backfill()

displayed(legacy_msg_id, **kwargs)#

Send a “displayed” message marker (XEP-0333) from this contact to the user.

Parameters:: legacy_msg_id (LegacyMessageType) – The message this marker refers to

extended_away(status=None, last_seen=None)#

Send an “extended away” presence from this contact to the user.

This is a global status, as opposed to LegacyContact.inactive() which concerns a specific conversation, ie a specific “chat window”

Parameters:

status (str | None) – Arbitrary text, details of the status, eg: “Gone to fight capitalism”
last_seen (datetime | None) – For XEP-0319

async fetch_vcard()#: It the legacy network doesn’t like that you fetch too many profiles on startup, it’s also possible to fetch it here, which will be called when XMPP clients of the user request the vcard, if it hasn’t been fetched before :return:

get_msg_xmpp_id_up_to(horizon_xmpp_id)#

Return XMPP msg ids sent by this contact up to a given XMPP msg id.

Plugins have no reason to use this, but it is used by slidge core for legacy networks that need to mark all messages as read (most XMPP clients only send a read marker for the latest message).

This has side effects, if the horizon XMPP id is found, messages up to this horizon are not cleared, to avoid sending the same read mark twice.

Parameters:: horizon_xmpp_id (str) – The latest message
Returns:: A list of XMPP ids or None if horizon_xmpp_id was not found

gone(**kwargs)#: Send a “gone” (ie “contact has not interacted with the chat session interface, system, or device for a relatively long period of time”) chat state (XEP-0085) from this contact to the user.

inactive(**kwargs)#: Send an “inactive” (ie “contact has not interacted with the chat session interface for an intermediate period of time”) chat state (XEP-0085) from this contact to the user.

property name#: Friendly name of the contact, as it should appear in the user’s roster

offline(status=None, last_seen=None)#

Send an “offline” presence from this contact to the user.

Parameters:

status (str | None) – eg: “Trying to make sense of XEP-0100”
last_seen (datetime | None) – For XEP-0319

online(status=None, last_seen=None)#

Send an “online” presence from this contact to the user.

Parameters:

status (str | None) – Arbitrary text, details of the status, eg: “Listening to Britney Spears”
last_seen (datetime | None) – For XEP-0319

paused(**kwargs)#: Send a “paused” (ie “typing paused notification”) chat state (XEP-0085) from this contact to the user.

react(legacy_msg_id, emojis=(), thread=None, **kwargs)#

Call this when a legacy contact reacts to a message

Parameters:

legacy_msg_id (LegacyMessageType) – The message which the reaction refers to.
emojis (Iterable[str]) – An iterable of emojis used as reactions
thread (LegacyThreadType | None) –

received(legacy_msg_id, **kwargs)#

Send a “received” message marker (XEP-0333) from this contact to the user. For LegacyContacts, also send a delivery receipt marker (XEP-0184)

Parameters:: legacy_msg_id (LegacyMessageType) – The message this marker refers to

retract(legacy_msg_id, thread=None, **kwargs)#

Call this when a legacy contact retracts (XEP-0424) a message

Parameters:

legacy_msg_id (LegacyMessageType) – Legacy ID of the message to delete
thread (LegacyThreadType | None) –

async send_file(file_path=None, legacy_msg_id=None, *, data_stream=None, data=None, file_url=None, file_name=None, content_type=None, reply_to=None, when=None, caption=None, legacy_file_id=None, thread=None, **kwargs)#

Send a message with an attachment

Parameters:

file_path (Path | str | None) – Path to the attachment
data_stream (IO[bytes] | None) – Alternatively, a stream of bytes (such as a File object)
data (bytes | None) – Alternatively, a bytes object
file_url (str | None) – Alternatively, a URL
file_name (str | None) – How the file should be named.
content_type (str | None) – MIME type, inferred from filename if not given
legacy_msg_id (LegacyMessageType | None) – If you want to be able to transport read markers from the gateway user to the legacy network, specify this
reply_to (MessageReference | None) – Quote another message (XEP-0461)
when (datetime | None) – when the file was sent, for a “delay” tag (XEP-0203)
caption (str | None) – an optional text that is linked to the file
legacy_file_id (str | int | None) – A unique identifier for the file on the legacy network. Plugins should try their best to provide it, to avoid duplicates.
thread (LegacyThreadType | None) –

send_text(body, legacy_msg_id=None, *, when=None, reply_to=None, thread=None, hints=None, carbon=False, archive_only=False, correction=False, **send_kwargs)#

Transmit a message from the entity to the user

Parameters:

body (str) – Content of the message
legacy_msg_id (LegacyMessageType | None) – If you want to be able to transport read markers from the gateway user to the legacy network, specify this
when (datetime | None) – when the message was sent, for a “delay” tag (XEP-0203)
reply_to (MessageReference | None) – Quote another message (XEP-0461)
hints (Iterable[Literal['no-store', 'markable', 'store']] | None) –
thread (LegacyThreadType | None) –
carbon – (only in 1:1) Reflect a message sent to this Contact by the user. Use this to synchronize outgoing history for legacy official apps.
correction – whether this message is a correction or not
archive_only – (only in groups) Do not send this message to user, but store it in the archive. Meant to be used during MUC.backfill()

async set_avatar(a, avatar_unique_id=None, blocking=False)#

Set the avatar for this contact

Parameters:

a (bytes | str | Path | None) – Any avatar format supported by slidge
avatar_unique_id (str | int | None) – If possible, provide a unique ID to cache the avatar. If it is not provided, the SHA-1 of the avatar will be used, unless it is an HTTP url. In this case, the url will be used, along with etag or last modified HTTP headers, to avoid fetching uselessly. Beware of legacy plugin where URLs are not stable.
blocking – if True, will await setting the avatar, if False, launch in a task

Returns:

unsubscribe()#: Send an “unsubscribe”, “unsubscribed”, “unavailable” presence sequence from this contact to the user, ie, “this contact has removed you from their ‘friends’”.

async update_info()#

Fetch information about this contact from the legacy network

This is awaited on Contact instantiation, and should be overridden to update the nickname, avatar, vcard [..] of this contact, by making “legacy API calls”.