Skip to content
Back to top
View this page
Edit this page

# slidge.group

Everything related to groups.

## Package Contents

class slidge.group.MucType

  Bases: `enum.IntEnum`

  The type of group, private, public, anonymous or not.

  GROUP = 0

    A private group, members-only and non-anonymous, eg a family group.

  CHANNEL = 1

    A public group, aka an anonymous channel.

  CHANNEL_NON_ANONYMOUS = 2

    A public group where participants’ legacy IDs are visible to everybody.

class slidge.group.LegacyBookmarks(session: slidge.util.types.AnySession)

  Bases: `slidge.util.jid_escaping.EscapeMixin`, `slidge.util.lock.NamedLockMixin`, `slidge.util.SubclassableOnce`, `Generic`[`slidge.util.types.LegacyMUCType`]

  This is instantiated once per `BaseSession`

  async fill() → None

    Establish a user’s known groups.

    This has to be overridden in plugins with group support and at the minimum, this should `await self.by_legacy_id(group_id)` for all the groups a user is part of.

    Slidge internals will call this on successful `BaseSession.login()`

  async remove(muc: slidge.util.types.AnyMUC, reason: str = 'You left this group from the official client.', kick: bool = True) → None

    Delete everything about a specific group.

    This should be called when the user leaves the group from the official app.

    Parameters:

      - muc – The MUC to remove.

      - reason – Optionally, a reason why this group was removed.

      - kick – Whether the user should be kicked from this group. Set this to False in case you do this somewhere else in your code, eg, on receiving the confirmation that the group was deleted.

  abstractmethod fetch_space_metadata(legacy_id: str) → slidge.util.types.SpaceMetadata
    Async:

    Fetch metadata associated to a space.

    This is called once per slidge runtime. It should return metadata associated to the space identified by its `legacy_id`. If there are updates to this metata, they should be communicated to slidge by calling `LegacyBookmarks.update_space_metadata()`.

    Parameters:

      legacy_id – Identifier of the space.

    Returns:

      Metadata associated to the space.

  async update_space_metadata(legacy_id: str, metadata: slidge.util.types.SpaceMetadata) → None

    Updates metadata associated to a space.

    Parameters:

      - legacy_id – Identifier of the space.

      - name – Metadata associated to this space.

  async legacy_id_to_jid_username(legacy_id: str) → str

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

    The default implementation uses XEP-0106.

    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 – The identifier to convert.

    Returns:

      A valid username part (or “local part”) of a JID.

  async jid_username_to_legacy_id(jid_username: str) → str

    Convert a JID user part to a legacy ID.

    The default implementation uses XEP-0106.

    Should be overridden in case legacy IDs are not strings, or more generally for any case where the username part of a JID is not enough to identify a contact on the legacy network.

    Parameters:

      jid_username – User part of a JID, ie “user” in “user@example.com”

    Returns:

      The string representation of an identifier on the legacy network.

class slidge.group.LegacyParticipant(muc: slidge.util.types.AnyMUC, stored: slidge.db.models.Participant, is_system: bool = False, contact: slidge.util.types.LegacyContactType | None = None)

  Bases: `slidge.core.mixins.PresenceMixin`, `slidge.core.mixins.MessageMixin`, `slidge.core.mixins.ChatterDiscoMixin`, `slidge.core.mixins.db.DBMixin`, `slidge.util.SubclassableOnce`, `Generic`[`slidge.util.types.LegacyContactType`]

  A legacy participant of a legacy group chat.

  send_initial_presence(full_jid: slixmpp.JID, nick_change: bool = False, presence_id: str | None = None, mav_until: str | None = None) → None

    Called when the user joins a MUC, as a mechanism to indicate to the joining XMPP client the list of “participants”.

    Can be called this to trigger a “participant has joined the group” event.

    Parameters:

      - full_jid – Set this to only send to a specific user XMPP resource.

      - nick_change – Used when the user joins and the MUC renames them (code 210)

      - presence_id – set the presence ID. used internally by slidge

  leave() → None

    Call this when the participant leaves the room

  kick(reason: str | None = None) → None

    Call this when the participant is kicked from the room

  ban(reason: str | None = None) → None

    Call this when the participant is banned from the room

  abstractmethod on_set_affiliation(affiliation: slidge.util.types.MucAffiliation, reason: str | None, nickname: str | None) → None
    Async:

    Triggered when the user requests changing the affiliation of a contact for this group.

    Examples: promotion them to moderator, ban (affiliation=outcast).

    Parameters:

      - contact – The contact whose affiliation change is requested

      - affiliation – The new affiliation

      - reason – A reason for this affiliation change

      - nickname

  abstractmethod on_kick(reason: str | None) → None
    Async:

    Triggered when the user requests changing the role of a contact to “none” for this group. Action commonly known as “kick”.

    Parameters:

      - contact – Contact to be kicked

      - reason – A reason for this kick

  async on_invitation(reason: str | None) → None

    Triggered when the user invites this Contact to a legacy MUC via XEP-0249.

    The default implementation calls `LegacyMUC.on_set_affiliation()` with the ‘member’ affiliation. Override if you want to customize this behaviour.

    Parameters:

      - muc – The group

      - reason – Optionally, a reason

  online(status: str | None = None, last_seen: datetime.datetime | None = None) → None

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

    Parameters:

      - status – Arbitrary text, details of the status, eg: “Listening to Britney Spears”

      - last_seen – For XEP-0319

  away(status: str | None = None, last_seen: datetime.datetime | None = None) → 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 – Arbitrary text, details of the status, eg: “Gone to fight capitalism”

      - last_seen – For XEP-0319

  extended_away(status: str | None = None, last_seen: datetime.datetime | None = None) → 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 – Arbitrary text, details of the status, eg: “Gone to fight capitalism”

      - last_seen – For XEP-0319

  busy(status: str | None = None, last_seen: datetime.datetime | None = None) → None

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

    Parameters:

      - status – eg: “Trying to make sense of XEP-0100”

      - last_seen – For XEP-0319

  offline(status: str | None = None, last_seen: datetime.datetime | None = None) → None

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

    Parameters:

      - status – eg: “Trying to make sense of XEP-0100”

      - last_seen – For XEP-0319

  invite_to(muc: slidge.util.types.AnyMUC, reason: str | None = None, password: str | None = None, **send_kwargs: object) → None

    Send an invitation to join a group (XEP-0249) from this XMPP Entity.

    Parameters:

      - muc – the muc the user is invited to

      - reason – a text explaining why the user should join this muc

      - password – maybe this will make sense later? not sure

      - send_kwargs – additional kwargs to be passed to _send() (internal use by slidge)

  active(**kwargs: object) → None

    Send an “active” chat state (XEP-0085) from this XMPP Entity.

  composing(**kwargs: object) → None

    Send a “composing” (ie “typing notification”) chat state (XEP-0085) from this XMPP Entity.

  paused(**kwargs: object) → None

    Send a “paused” (ie “typing paused notification”) chat state (XEP-0085) from this XMPP Entity.

  inactive(**kwargs: object) → None

    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 XMPP Entity.

  gone(**kwargs: object) → None

    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 XMPP Entity.

  ack(legacy_msg_id: str, **kwargs: object) → None

    Send an “acknowledged” message marker (XEP-0333) from this XMPP Entity.

    Parameters:

      legacy_msg_id – The message this marker refers to

  received(legacy_msg_id: str, **kwargs: object) → None

    Send a “received” message marker (XEP-0333) from this XMPP Entity. If called on a `LegacyContact`, also send a delivery receipt marker (XEP-0184).

    Parameters:

      legacy_msg_id – The message this marker refers to

  displayed(legacy_msg_id: str, **kwargs: object) → None

    Send a “displayed” message marker (XEP-0333) from this XMPP Entity.

    Parameters:

      legacy_msg_id – The message this marker refers to

  async send_file(attachment: slidge.util.types.LegacyAttachment | pathlib.Path | str, legacy_msg_id: str | None = None, *, reply_to: slidge.util.types.MessageReference | None = None, when: datetime.datetime | None = None, thread: str | None = None, **kwargs: Any) → tuple[str | None, list[slixmpp.Message]]

    Send a single file from this XMPP Entity.

    Parameters:

      - attachment – The file to send. Ideally, a `LegacyAttachment` with a unique `legacy_file_id` attribute set, to optimise potential future reuses. It can also be: - a `pathlib.Path` instance to point to a local file, or - a `str`, representing a fetchable HTTP URL.

      - legacy_msg_id – If you want to be able to transport read markers from the gateway user to the legacy network, specify this

      - reply_to – Quote another message (XEP-0461)

      - when – when the file was sent, for a “delay” tag (XEP-0203)

      - thread

  send_text(body: str, legacy_msg_id: str | None = None, *, when: datetime.datetime | None = None, reply_to: slidge.util.types.MessageReference | None = None, thread: str | None = None, hints: collections.abc.Iterable[slidge.util.types.ProcessingHint] | None = None, carbon: bool = False, archive_only: bool = False, correction: bool = False, correction_event_id: str | None = None, link_previews: list[slidge.util.types.LinkPreview] | None = None, **send_kwargs: object) → slixmpp.Message | None

    Send a text message from this XMPP Entity.

    Parameters:

      - body – Content of the message

      - legacy_msg_id – If you want to be able to transport read markers from the gateway user to the legacy network, specify this

      - when – when the message was sent, for a “delay” tag (XEP-0203)

      - reply_to – Quote another message (XEP-0461)

      - hints

      - thread

      - carbon – (only used if called on a `LegacyContact`) Set this to `True` if this is actually a message sent to the `LegacyContact` by the User. Use this to synchronize outgoing history for legacy official apps.

      - correction – whether this message is a correction or not

      - correction_event_id – in the case where an ID is associated with the legacy ‘correction event’, specify it here to use it on the XMPP side. If not specified, a random ID will be used.

      - link_previews – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.

      - 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()`

  correct(legacy_msg_id: str, new_text: str, *, when: datetime.datetime | None = None, reply_to: slidge.util.types.MessageReference | None = None, thread: str | None = None, hints: collections.abc.Iterable[slidge.util.types.ProcessingHint] | None = None, carbon: bool = False, archive_only: bool = False, correction_event_id: str | None = None, link_previews: list[slidge.util.types.LinkPreview] | None = None, **send_kwargs: object) → None

    Modify a message that was previously sent by this XMPP Entity.

    Uses last message correction (XEP-0308)

    Parameters:

      - new_text – New content of the message

      - legacy_msg_id – The legacy message ID of the message to correct

      - when – when the message was sent, for a “delay” tag (XEP-0203)

      - reply_to – Quote another message (XEP-0461)

      - hints

      - thread

      - 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()`

      - correction_event_id – in the case where an ID is associated with the legacy ‘correction event’, specify it here to use it on the XMPP side. If not specified, a random ID will be used.

      - link_previews – A little of sender (or server, or gateway)-generated previews of URLs linked in the body.

  react(legacy_msg_id: str, emojis: collections.abc.Iterable[str] = (), thread: str | None = None, **kwargs: object) → None

    Send a reaction (XEP-0444) from this XMPP Entity.

    Parameters:

      - legacy_msg_id – The message which the reaction refers to.

      - emojis – An iterable of emojis used as reactions

      - thread

  retract(legacy_msg_id: str, thread: str | None = None, **kwargs: object) → None

    Send a message retraction (XEP-0424) from this XMPP Entity.

    Parameters:

      - legacy_msg_id – Legacy ID of the message to delete

      - thread

class slidge.group.LegacyMUC(session: slidge.util.types.AnySession, stored: slidge.db.models.Room)

  Bases: `slidge.core.mixins.avatar.AvatarMixin`, `slidge.core.mixins.disco.ChatterDiscoMixin`, `slidge.core.mixins.recipient.RecipientMixin`, `slidge.util.util.SubclassableOnce`, `Generic`[`slidge.util.types.LegacyParticipantType`]

  A room, a.k.a. a Multi-User Chat.

  MUC instances are obtained by calling `slidge.group.bookmarks.LegacyBookmarks()` on the user’s `slidge.core.session.BaseSession`.

  STABLE_ARCHIVE = False

    Because legacy events like reactions, editions, etc. don’t all map to a stanza with a proper legacy ID, slidge usually cannot guarantee the stability of the archive across restarts.

    Set this to True if you know what you’re doing, but realistically, this can’t be set to True until archive is permanently stored on disk by slidge.

    This is just a flag on archive responses that most clients ignore anyway.

  HAS_DESCRIPTION = True

    Set this to false if the legacy network does not allow setting a description for the group. In this case the description field will not be present in the room configuration form.

  HAS_SUBJECT = True

    Set this to false if the legacy network does not allow setting a subject (sometimes also called topic) for the group. In this case, as a subject is recommended by XEP-0045 (“SHALL”), the description (or the group name as ultimate fallback) will be used as the room subject. By setting this to false, an error will be returned when the User tries to set the room subject.

  pop_unread_xmpp_ids_up_to(horizon_xmpp_id: str) → list[str]

    Return XMPP msg ids sent in this group 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: all messages up to the horizon XMPP id will be marked as read in the DB. If the horizon XMPP id is not found, all messages of this MUC will be marked as read.

    Parameters:

      horizon_xmpp_id – The latest message

    Returns:

      A list of XMPP ids if horizon_xmpp_id was not found

  abstractmethod update_info() → None
    Async:

    Fetch information about this group from the legacy network

    This is awaited on MUC instantiation, and should be overridden to update the attributes of the group chat, like title, subject, number of participants etc.

    To take advantage of the slidge avatar cache, you can check the .avatar property to retrieve the “legacy file ID” of the cached avatar. If there is no change, you should not call `slidge.core.mixins.avatar.AvatarMixin.set_avatar()` or attempt to modify the :attr:.avatar property.

  abstractmethod backfill(after: slidge.util.types.HoleBound | None = None, before: slidge.util.types.HoleBound | None = None) → None
    Async:

    Override this if the legacy network provide server-side group archives.

    In it, send history messages using `self.get_participant(xxx).send_xxxx`, with the `archive_only=True` kwarg. This is only called once per slidge run for a given group.

    Parameters:

      - after – Fetch messages after this one. If `None`, slidge’s local archive was empty before start-up, ie, no history was ever fetched for this room since the user registered. It’s up to gateway implementations to decide how far to fetch messages before the user registered. If not `None`, slidge has some messages in this archive, and the gateway shall try to fetch history up to (and excluding) this message to avoid “holes” in the history of this group.

      - before – Fetch messages before this one. If `None`, the gateway shall fetch all messages up to the most recent one. If not `None`, slidge has already archived some live messages it received during its lifetime, and there is no need to query the legacy network for any message after (and including) this one.

  async fill_participants() → collections.abc.AsyncIterator[slidge.util.types.LegacyParticipantType]

    This method should yield the list of all members of this group.

    Typically, use `participant = self.get_participant()`, self.get_participant_by_contact(), of self.get_user_participant(), and update their affiliation, hats, etc. before yielding them.

  async get_user_participant(*, fill_first: bool = False, store: bool = True, occupant_id: str | None = None) → slidge.util.types.LegacyParticipantType

    Get the participant representing the gateway user

    Parameters:

      kwargs – additional parameters for the `Participant` construction (optional)

    Returns:

  async get_participant(nickname: str) → slidge.util.types.LegacyParticipantType
  async get_participant(*, occupant_id: str) → slidge.util.types.LegacyParticipantType
  async get_participant(*, occupant_id: str, create: Literal[False]) → LegacyParticipantType | None
  async get_participant(*, occupant_id: str, create: Literal[True]) → slidge.util.types.LegacyParticipantType
  async get_participant(nickname: str, *, occupant_id: str) → slidge.util.types.LegacyParticipantType
  async get_participant(nickname: str, *, create: Literal[False]) → LegacyParticipantType | None
  async get_participant(nickname: str, *, create: Literal[True]) → slidge.util.types.LegacyParticipantType
  async get_participant(nickname: str, *, create: Literal[True], is_user: bool, fill_first: bool, store: bool) → slidge.util.types.LegacyParticipantType
  async get_participant(nickname: str, *, create: Literal[False], is_user: bool, fill_first: bool, store: bool) → LegacyParticipantType | None
  async get_participant(nickname: str, *, create: bool, fill_first: bool) → LegacyParticipantType | None
  async get_participant(nickname: str, *, is_user: Literal[True], fill_first: bool, store: bool, occupant_id: str | None = None) → slidge.util.types.LegacyParticipantType

    Get a participant by their nickname.

    In non-anonymous groups, you probably want to use `LegacyMUC.get_participant_by_contact()` instead.

    Parameters:

      - nickname – Nickname of the participant (used as resource part in the MUC)

      - create – By default, a participant is created if necessary. Set this to False to return None if participant was not created before.

      - is_user – Whether this participant is the slidge user.

      - fill_first – Ensure `LegacyMUC.fill_participants()` has been called first (internal use by slidge, plugins should not need that)

      - store – persistently store the user in the list of MUC participants

      - occupant_id – optionally, specify the unique ID for this participant, cf xep:0421

    Returns:

      A participant of this room.

  get_system_participant() → slidge.util.types.LegacyParticipantType

    Get a pseudo-participant, representing the room itself

    Can be useful for events that cannot be mapped to a participant, e.g. anonymous moderation events, or announces from the legacy service :return:

  async get_participant_by_contact(c: slidge.contact.contact.LegacyContact) → slidge.util.types.LegacyParticipantType
  async get_participant_by_contact(c: slidge.contact.contact.LegacyContact, *, occupant_id: str | None = None) → slidge.util.types.LegacyParticipantType
  async get_participant_by_contact(c: slidge.contact.contact.LegacyContact, *, create: Literal[False], occupant_id: str | None) → LegacyParticipantType | None
  async get_participant_by_contact(c: slidge.contact.contact.LegacyContact, *, create: Literal[True], occupant_id: str | None) → slidge.util.types.LegacyParticipantType

    Get a non-anonymous participant.

    This is what should be used in non-anonymous groups ideally, to ensure that the Contact jid is associated to this participant

    Parameters:

      - c – The `LegacyContact` instance corresponding to this contact

      - create – Creates the participant if it does not exist.

      - occupant_id – Optionally, specify a unique occupant ID (XEP-0421) for this participant.

    Returns:

  remove_participant(p: slidge.util.types.LegacyParticipantType, kick: bool = False, ban: bool = False, reason: str | None = None) → None

    Call this when a participant leaves the room

    Parameters:

      - p – The participant

      - kick – Whether the participant left because they were kicked

      - ban – Whether the participant left because they were banned

      - reason – Optionally, a reason why the participant was removed.

  async kick_resource(r: str) → None

    Kick a XMPP client of the user. (slidge internal use)

    Parameters:

      r – The resource to kick

  async add_to_bookmarks(auto_join: bool = True, preserve: bool = True, pin: bool | None = None, notify: slixmpp.plugins.xep_0492.stanza.WhenLiteral | None = None) → None

    Add the MUC to the user’s XMPP bookmarks (XEP-0402)

    This requires that slidge has the IQ privileged set correctly on the XMPP server

    Parameters:

      - auto_join – whether XMPP clients should automatically join this MUC on startup. In theory, XMPP clients will receive a “push” notification when this is called, and they will join if they are online.

      - preserve – preserve auto-join and bookmarks extensions set by the user outside slidge

      - pin – Pin the group chat bookmark XEP-0469. Requires privileged entity. If set to `None` (default), the bookmark pinning status will be untouched.

      - notify – Chat notification setting: XEP-0492. Requires privileged entity. If set to `None` (default), the setting will be untouched. Only the “global” notification setting is supported (ie, per client type is not possible).

  abstractmethod on_avatar(data: bytes | None, mime: str | None) → str | None
    Async:

    Called when the user tries to set the avatar of the room from an XMPP client.

    If the set avatar operation is completed, should return a legacy image unique identifier. In this case the MUC avatar will be immediately updated on the XMPP side.

    If data is not None and this method returns None, then we assume that self.set_avatar() will be called elsewhere, eg triggered by a legacy room update event.

    Parameters:

      - data – image data or None if the user meant to remove the avatar

      - mime – the mime type of the image. Since this is provided by the XMPP client, there is no guarantee that this is valid or correct.

    Returns:

      A unique avatar identifier, which will trigger `slidge.group.room.LegacyMUC.set_avatar()`. Alternatively, None, if `LegacyMUC.set_avatar()` is meant to be awaited somewhere else.

  abstractmethod on_set_config(name: str | None, description: str | None) → None
    Async:

    Triggered when the user requests changing the room configuration. Only title and description can be changed at the moment.

    The legacy module is responsible for updating `title` and/or `LegacyMUC.description` of this instance.

    If `HAS_DESCRIPTION` is set to False, description will always be `None`.

    Parameters:

      - name – The new name of the room.

      - description – The new description of the room.

  abstractmethod on_destroy_request(reason: str | None) → None
    Async:

    Triggered when the user requests room destruction.

    Parameters:

      reason – Optionally, a reason for the destruction

  abstractmethod on_set_subject(subject: str) → None
    Async:

    Triggered when the user requests changing the room subject.

    The legacy module is responsible for updating `subject` of this instance.

    Parameters:

      subject – The new subject for this room.

  abstractmethod on_set_thread_subject(thread: str, subject: str) → None
    Async:

    Triggered when the user requests changing the subject of a specific thread.

    Parameters:

      - thread – Legacy identifier of the thread

      - subject – The new subject for this thread.

  abstractmethod on_moderate(legacy_msg_id: str, reason: str | None) → None
    Async:

    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 `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:

      - legacy_msg_id – The legacy ID of the message to be retracted

      - reason – Optionally, a reason for the moderation, given by the user-moderator.

  abstractmethod on_leave() → None
    Async:

    Triggered when the user leaves a group via the dedicated slidge command or the XEP-0077 `<remove />` mechanism.

    This should be interpreted as definitely leaving the group.

  get_archived_messages(msg_id: str) → collections.abc.Iterator[slidge.util.archive_msg.HistoryMessage]

    Query the slidge archive for messages sent in this group

    Parameters:

      msg_id – Message ID of the message in question. Can be either a legacy ID or an XMPP ID.

    Returns:

      Iterator over messages. A single legacy ID can map to several messages, because of multi-attachment messages.

  property avatar: slidge.util.types.Avatar | None

    This property can be used to set or unset the avatar.

    Unlike the awaitable `set_avatar()`, it schedules the update for later execution and is not blocking

  async set_avatar(avatar: slidge.util.types.Avatar | pathlib.Path | str | None = None, delete: bool = False) → None

    Set an avatar for this entity

    Parameters:

      - avatar – The avatar. Should ideally come with a legacy network-wide unique ID

      - delete – If the avatar is provided as a Path, whether to delete it once used or not.

  serialize_extra_attributes() → slidge.db.meta.JSONSerializable | None

    If you want custom attributes of your instance to be stored persistently to the DB, here is where you have to return them as a dict to be used in deserialize_extra_attributes().

  deserialize_extra_attributes(data: slidge.db.meta.JSONSerializable) → None

    This is where you get the dict that you passed in serialize_extra_attributes().

    ⚠ Since it is serialized as json, dictionary keys are converted to strings! Be sure to convert to other types if necessary.

  abstractmethod available_emojis(legacy_msg_id: str | None = None) → set[str] | None
    Async:

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

    Returns:

      A set of emojis or None if any emoji is allowed

  abstractmethod on_message(message: slidge.util.types.XMPPMessage) → str | None
    Async:

    Triggered when the user sends a message to this Recipient.

  abstractmethod on_sticker(sticker: slidge.util.types.Sticker) → str | None
    Async:

    Triggered when the user sends a sticker to this Recipient.

    Parameters:

      sticker – The sticker sent by the user.

    Returns:

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

  abstractmethod on_chat_state(chat_state: slidge.util.types.ChatState, thread: str | None) → None
    Async:

    Triggered when the user sends a chat state (XEP-0085) to this Recipient.

    Parameters:

      chat_state – The sticker sent by the user.

  abstractmethod on_displayed(legacy_msg_id: str, thread: str | None) → None
    Async:

    Triggered when the user sends a read marker (XEP-0333) to this Recipient.

    This is only possible if a valid `legacy_msg_id` was passed when transmitting a message from a legacy chat to the user, eg in `slidge.contact.LegacyContact.send_text()` or `slidge.group.LegacyParticipant.send_text()`.

    Parameters:

      - legacy_msg_id – Identifier of the message/

      - thread

  abstractmethod on_react(legacy_msg_id: str, emojis: list[str], thread: str | None) → None
    Async:

    Triggered when the user sends an emoji reaction (XEP-0444) to this Recipient.

    Parameters:

      - legacy_msg_id – ID of the message the user reacts to

      - emojis – Unicode characters representing reactions to the message `legacy_msg_id`. An empty list means “no reaction”, ie, remove all reactions if any were present before

      - thread

  abstractmethod on_retract(legacy_msg_id: str, thread: str | None) → None
    Async:

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

    Parameters:

      - legacy_msg_id – Legacy ID of the retracted message

      - thread