xmpp

xmpp#

Description#

XMPP integration.

Configuration#

xmpp:
  # [Required]
  # Jabber/user ID, in the format ``user@example.org``.
  user_id:   # type=str

  # [Optional]
  # User password.
  # password:   # type=Optional[str]

  # [Optional]
  # ISO string for the language code that will be used by
  # the bot (default: ``None``).
  # language:   # type=Optional[str]

  # [Optional]
  # Whether to use anonymous authentication (default:
  # ``False``).
  # anonymous: False  # type=bool

  # [Optional]
  # Whether to automatically accept invites to
  # conversations (default: True). If set to False, and you still want
  # some control on which invites should be accepted, you can create a
  # ``hook`` on
  # `XmppRoomInviteEvent <https://docs.platypush.tech/platypush/events/xmpp.html#platypush.message.event.xmpp.XmppRoomInviteEvent>`_ that
  # calls either `XmppPlugin.accept_invite <https://docs.platypush.tech/platypush/plugins/xmpp.html#platypush.plugins.xmpp.XmppPlugin.accept_invite>`_ or `XmppPlugin.reject_invite <https://docs.platypush.tech/platypush/plugins/xmpp.html#platypush.plugins.xmpp.XmppPlugin.reject_invite>`_ with
  # the ``room_id`` specified on the event, if it is a room event, or
  # subscribe to
  # `XmppContactAddRequestEvent <https://docs.platypush.tech/platypush/events/xmpp.html#platypush.message.event.xmpp.XmppContactAddRequestEvent>`_
  # and call either `XmppPlugin.accept_invite <https://docs.platypush.tech/platypush/plugins/xmpp.html#platypush.plugins.xmpp.XmppPlugin.accept_invite>`_ or `XmppPlugin.reject_invite <https://docs.platypush.tech/platypush/plugins/xmpp.html#platypush.plugins.xmpp.XmppPlugin.reject_invite>`_
  # with the ``user_id`` specified on the event, if it is a contact add
  # request.
  # auto_accept_invites: True  # type=bool

  # [Optional]
  # If ``True`` (default) then any previously joined
  # conversation or subscribed contact will be joined/subscribed again
  # when the plugin restarts. Otherwise, upon restart the plugin will
  # start from a state with no subscriptions nor joined rooms.
  # restore_state: True  # type=bool

  # [Optional]
  # Path where the previous state will be stored, if
  # ``restore_state`` is ``True``. Default:
  # ``<WORKDIR>/xmpp/state.json``.
  # state_file:   # type=Optional[str]

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 15  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Triggered events#

Actions#

Module reference#

class platypush.plugins.xmpp.XmppPlugin(user_id: str, password: str | None = None, language: str | None = None, anonymous: bool = False, auto_accept_invites: bool = True, restore_state: bool = True, state_file: str | None = None, **kwargs)[source]#

Bases: AsyncRunnablePlugin, XmppBasePlugin

XMPP integration.

DEFAULT_TIMEOUT = 20#

Default timeout for async calls.

__init__(user_id: str, password: str | None = None, language: str | None = None, anonymous: bool = False, auto_accept_invites: bool = True, restore_state: bool = True, state_file: str | None = None, **kwargs)[source]#
Parameters:

  • user_id – Jabber/user ID, in the format user@example.org.

  • password – User password.

  • language – ISO string for the language code that will be used by the bot (default: None).

  • anonymous – Whether to use anonymous authentication (default: False).

  • auto_accept_invites – Whether to automatically accept invites to conversations (default: True). If set to False, and you still want some control on which invites should be accepted, you can create a hook on platypush.message.event.xmpp.XmppRoomInviteEvent that calls either accept_invite() or reject_invite() with the room_id specified on the event, if it is a room event, or subscribe to platypush.message.event.xmpp.XmppContactAddRequestEvent and call either accept_invite() or reject_invite() with the user_id specified on the event, if it is a contact add request.

  • restore_state – If True (default) then any previously joined conversation or subscribed contact will be joined/subscribed again when the plugin restarts. Otherwise, upon restart the plugin will start from a state with no subscriptions nor joined rooms.

  • state_file – Path where the previous state will be stored, if restore_state is True. Default: <WORKDIR>/xmpp/state.json.

accept_invite(room_id: str | None = None, user_id: str | None = None)[source]#

Accept a pending invite to a multi-user conversation or a contact add request.

Parameters:

  • user_id – The target user_id if this is a contact add request.

  • room_id – The target room_id if this is a room invite request.

add_user(user_id: str)[source]#

Add the specified user ID to the roster.

Parameters:

user_id – The Jabber ID of the user to add.

ban(room_id: str, user_id: str, reason: str | None = None, timeout: float | None = 20)[source]#

Ban a user from a room.

Parameters:

  • room_id – The target room JID.

  • user_id – The JID of the user to ban.

  • timeout – Request timeout (default: 20 seconds). Set to null for no timeout.

  • reason – Ban reason.

invite(room_id: str, user_id: str, mode: str = 'direct', text: str | None = None, timeout: float | None = 20)[source]#

Invite a user to a room.

Parameters:

  • room_id – The target room JID.

  • user_id – The JID of the user to invite.

  • timeout – Invite request send timeout (default: 20 seconds). Set to null for no timeout.

  • mode –

    Invite mode - can be direct (default) or mediated.

    • direct: The invitation is sent directly to the invitee, without going through a service specific to the conversation.

    • mediated: The invitation is sent indirectly through a service which is providing the conversation. Advantages of using this mode include most notably that the service can automatically add the invitee to the list of allowed participants in configurations where such restrictions exist (or deny the request if the inviter does not have the permissions to do so).

  • text – Optional text to send with the invitation.

join(room_id: str, nick: str | None = None, password: str | None = None, auto_rejoin: bool = True, timeout: float | None = 20)[source]#

Join a room/conversation.

Parameters:

  • room_id – The Jabber ID of the conversation to join.

  • nick – The nickname that the bot should use in the room (default: the nickname specified in the configuration’s user_id parameter).

  • password – The password of the room (default: None).

  • auto_rejoin – Whether to automatically rejoin the room after disconnection/kick (default: True).

  • timeout – Room join timeout (default: 20 seconds). Set to null for no timeout.

kick(room_id: str, user_id: str, reason: str | None = None, timeout: float | None = 20)[source]#

Kick a user from a room.

Parameters:

  • room_id – The target room JID.

  • user_id – The JID of the user to kick.

  • timeout – Request timeout (default: 20 seconds). Set to null for no timeout.

  • reason – Kick reason.

leave(room_id: str, timeout: float | None = 20)[source]#

Leave a room/conversation.

Parameters:

  • room_id – The Jabber ID of the conversation to leave.

  • timeout – Room leave timeout (default: 20 seconds). Set to null for no timeout.

async listen()[source]#

Main body of the async plugin. When it’s called, the event loop should already be running and available over self._loop.

main()#

Implementation of the main loop of the plugin.

reject_invite(room_id: str | None = None, user_id: str | None = None)[source]#

Reject a pending invite to a multi-user conversation or a contact add request.

Parameters:

  • user_id – The target user_id if this is a contact add request.

  • room_id – The target room_id if this is a room invite request.

remove_user(user_id: str)[source]#

Remove the specified user ID from the roster.

Parameters:

user_id – The Jabber ID of the user to remove.

request_voice(room_id: str, timeout: float | None = 20)[source]#

Request voice (i.e. participant role) in a room.

Parameters:

  • room_id – The Jabber ID of the room.

  • timeout – Request timeout (default: 20 seconds). Set to null for no timeout.

restore_state()[source]#

Reload the previous state from the configured state file.

send_message(body: str, user_id: str | None = None, room_id: str | None = None, language: str | None = None)[source]#

Send a message to a target (the Jabber ID of another user or room).

Parameters:

  • body – Message body.

  • user_id – Jabber ID of the target user. Either user_id or room_id should be specified.

  • room_id – Jabber ID of the target room. Either user_id or room_id should be specified.

  • language – Override the default language code.

set_affiliation(room_id: str, user_id: str, affiliation: str, reason: str | None = None, timeout: float | None = 20)[source]#

Change the affiliation of a user to a room.

Parameters:

  • room_id – The target room JID.

  • user_id – The user JID.

  • affiliation –

    The affiliation to set. Possible values are:

    • owner

    • member

    • none

    • outcast

    • publisher

    • publish-only

  • timeout – Request timeout (default: 20 seconds). Set to null for no timeout.

  • reason – Optional reason for the change.

set_nick(room_id: str, nick: str, timeout: float | None = 20)[source]#

Set the nick of the user on a specific room.

Parameters:

  • room_id – The target room JID.

  • nick – New nick.

  • timeout – Request timeout (default: 20 seconds). Set to null for no timeout.

set_presence(presence: str | XmppPresence)[source]#

Set/broadcast a new presence state for the user.

Parameters:

presence –

The new presence state. Possible values are:

  • available

  • offline

  • away

  • xa

  • chat

  • dnd

set_role(room_id: str, user_id: str, role: str, reason: str | None = None, timeout: float | None = 20)[source]#

Change the role of a user in a room.

Parameters:

  • room_id – The target room JID.

  • user_id – The user JID.

  • role –

    The role to set. Possible values are:

    • none

    • participant

    • visitor

    • moderator

  • timeout – Request timeout (default: 20 seconds). Set to null for no timeout.

  • reason – Optional reason for the change.

set_room_configuration(room_id: str, name: bool | None = None, description: bool | None = None, members_only: bool | None = None, persistent: bool | None = None, moderated: bool | None = None, allow_invites: bool | None = None, allow_private_messages: bool | None = None, allow_change_subject: bool | None = None, enable_logging: bool | None = None, max_history_fetch: int | None = None, max_users: int | None = None, password_protected: bool | None = None, public: bool | None = None, room_admins: Iterable[str] | None = None, room_owners: Iterable[str] | None = None, password: str | None = None, language: str | None = None, timeout: float | None = 20)[source]#

Changes the configuration of a room.

All the parameters are optional, and only those that have a non-null value will be set.

Parameters:

  • room_id – The target room JID.

  • name – New room name.

  • description – New room description.

  • members_only – Whether or not this room is only for members.

  • persistent – Whether or not this room is persistent.

  • moderated – Whether or not this room is moderated.

  • allow_invites – Whether or not this room allows invites.

  • allow_private_messages – Whether or not this room allows private messages.

  • allow_change_subject – Whether or not this room allows changing its subject.

  • enable_logging – Whether or not this room has logging enabled.

  • max_history_fetch – Maximum number of past messages to fetch when joining the room.

  • max_users – Maximum number of users allowed in the room.

  • password_protected – Whether or not this room is password protected.

  • public – Whether or not this room is publicly visible.

  • room_admins – List of room admins, by Jabber ID.

  • room_owners – List of room owners, by Jabber ID.

  • password – If the room is password protected, configure its password here.

  • language – Language of the room (ISO 2-letter code).

  • timeout – Request timeout (default: 20 seconds). Set to null for no timeout.

set_topic(room_id: str, topic: str, timeout: float | None = 20)[source]#

Set the topic of a room.

Parameters:

  • room_id – The target room JID.

  • topic – New topic.

  • timeout – Request timeout (default: 20 seconds). Set to null for no timeout.

start()#

Start the plugin.

status()[source]#

Get the current status of the client.

Returns:

{
  # List of pending room invites, as Jabber IDs
  "room_invites": ["bar@conference.xmpp.example.org"],

  # List of pending user invites, as Jabber IDs
  "user_invites": ["ignore-me@example.org"],

  # List of users the client is subscribed to
  "users": [
    "buddy@example.org"
  ],

  # Map of rooms the client has joined, indexed by room ID
  "rooms": {
    "tests@conference.xmpp.manganiello.tech": {
      "room_id": "foo@conference.xmpp.example.org",
      "joined": true,
      # Possible values:
      # ACTIVE, DISCONNECTED, HISTORY, JOIN_PRESENCE
      "state": "ACTIVE",
      "nick": "me",

      # Map of room members, indexed by user ID
      "members": {
        "me@example.org": {
          "user_id": "me@example.org",
          "nick": "me",
          # Possible affiliation values:
          # none, member, outcast, owner, publisher, publish-only
          "affiliation": "none",

          # Possible role values:
          # none, participant, visitor, moderator
          "role": "participant",
          "is_self": true,
          "available": true,

          # Possible state values:
          # available, offline, away, xa, chat, dnd
          "state": "available"
        },

        "buddy@example.org": {
          "user_id": "buddy@example.org",
          "nick": "SomeBuddy",
          "affiliation": "owner",
          "role": "moderator",
          "is_self": false,
          "available": true,
          "state": "away"
        }
      }
    }
  }
}

stop()[source]#

Stop the plugin.

wait_stop(timeout=None)#

Wait until a stop event is received.