Skip to content
Back to top
View this page

# Event Index

Slixmpp relies on events and event handlers to act on received data from the server. Some of those events come from the very base of Slixmpp such as `BaseXMPP` or `XMLStream`, while most of them are emitted from plugins which add their own listeners.

There are often multiple events running for a single stanza, with different levels of granularity, so code must take care of not processing the same stanza twice.

attention

  - Data: `Message`

  - Source: `XEP_0224`

  Whenever a message containing an attention payload is received.

call_invite

  - Data: `Message`

  - Source: `XEP_0482`

call_leave

  - Data: `Message`

  - Source: `XEP_0482`

call_left

  - Data: `Message`

  - Source: `XEP_0482`

call_reject

  - Data: `Message`

  - Source: `XEP_0482`

call_retract

  - Data: `Message`

  - Source: `XEP_0482`

carbon_received

  - Data: `Message`

  - Source: `XEP_0280`

  When a carbon for a received message is received.

carbon_sent

  - Data: `Message`

  - Source: `XEP_0280`

  When a carbon for a sent message (from another of our resources) is received.

changed_status

  - Data: `Presence`

  - Source: `RosterItem`

  Triggered when a presence stanza is received from a JID with a show type different than the last presence stanza from the same JID.

changed_subscription

  - Data: `Presence`

  - Source: `BaseXMPP`

  Triggered whenever a presence stanza with a type of `subscribe`, `subscribed`, `unsubscribe`, or `unsubscribed` is received.

  Note that if the values `xmpp.auto_authorize` and `xmpp.auto_subscribe` are set to `True` or `False`, and not `None`, then will either accept or reject all subscription requests before your event handlers are called. Set these values to `None` if you wish to make more complex subscription decisions.

chatstate_active

  - Data: `Message`

  - Source: `XEP_0085`

  When a message containing an `<active/>` chatstate is received.

chatstate_composing

  - Data: `Message`

  - Source: `XEP_0085`

  When a message containing a `<composing/>` chatstate is received.

chatstate_gone

  - Data: `Message`

  - Source: `XEP_0085`

  When a message containing a `<gone/>` chatstate is received.

chatstate_inactive

  - Data: `Message`

  - Source: `XEP_0085`

  When a message containing an `<inactive/>` chatstate is received.

chatstate_paused

  - Data: `Message`

  - Source: `XEP_0085`

  When a message containing a `<paused/>` chatstate is received.

command

  - Data: `Iq`

  - Source: `XEP_0050`

  When an ad-hoc command is received.

command_[action]

  - Data: `Iq`

  - Source: `XEP_0050`

  - Name parameters: `action`, the action referenced in the command payload.

  When a command with the specific action is received.

connected

  - Data: `{}`

  - Source: `XMLStream`

  Signal that a connection has been made with the XMPP server, but a session has not yet been established.

connecting

  - Data: `{}`

  - Source: `XMLStream`

  Signal that a slixmpp will start to try establishing a connection.

connection_failed

  - Data: `str` or `OSerror`

  - Source: `XMLStream`

  Signal that a connection attempt failed, either due to a lack of DNS records, or a network-level exception happened.

disco_info

  - Data: `DiscoInfo`

  - Source: `XEP_0030`

  Triggered whenever a `disco#info` result stanza is received.

disco_items

  - Data: `DiscoItems`

  - Source: `XEP_0030`

  Triggered whenever a `disco#items` result stanza is received.

disconnected

  - Data: `Union[str, Exception]`, the reason for the disconnect (if any). If a textual reason is not provided and an exception is the cause, it will be given to the event handler.

  - Source: `XMLStream`

  Signal that the connection with the XMPP server has been lost.

failed_auth

  - Data: `{}`

  - Source: `ClientXMPP`, `XEP_0078`

  Signal that the server has rejected the provided login credentials.

gateway_message

  - Data: `Message`

  - Source: `XEP_0100`

gmail_messages

  - Data: `Iq`

  - Source: `gmail_notify`

  Signal that there are unread emails for the Gmail account associated with the current XMPP account.

gmail_notify

  - Data: `{}`

  - Source: `gmail_notify`

  Signal that there are unread emails for the Gmail account associated with the current XMPP account.

got_offline

  - Data: `Presence`

  - Source: `RosterItem`

  Signal that an unavailable presence stanza has been received from a JID.

got_online

  - Data: `Presence`

  - Source: `RosterItem`

  If a presence stanza is received from a JID which was previously marked as offline, and the presence has a show type of ‘`chat`’, ‘`dnd`’, ‘`away`’, or ‘`xa`’, then this event is triggered as well.

groupchat_direct_invite

  - Data: `Message`

  - Source: `XEP_0249`

  When a Direct MUC invite is received.

groupchat_invite

  - Data: `Message`

  - Source: `XEP_0045`

  When a Mediated MUC invite is received.

groupchat_message

  - Data: `Message`

  - Source: `XEP_0045`

  Triggered whenever a message is received from a multi-user chat room.

groupchat_presence

  - Data: `Presence`

  - Source: `XEP_0045`

  Triggered whenever a presence stanza is received from a user in a multi-user chat room.

groupchat_subject

  - Data: `Message`

  - Source: `XEP_0045`

  Triggered whenever the subject of a multi-user chat room is changed, or announced when joining a room.

ibb_stream_data

  - Data: `IBBBytestream`

  - Source: `XEP_0047`

  When data is received on an opened stream.

ibb_stream_end

  - Data: `IBBBytestream`

  - Source: `XEP_0047`

  When an opened stream closes.

ibb_stream_start

  - Data: `IBBBytestream`

  - Source: `XEP_0047`

  When a stream is successfully opened with a remote peer.

jingle_message_accept

  - Data: `Message`

  - Source: `XEP_0353`

jingle_message_proceed

  - Data: `Message`

  - Source: `XEP_0353`

jingle_message_propose

  - Data: `Message`

  - Source: `XEP_0353`

jingle_message_reject

  - Data: `Message`

  - Source: `XEP_0353`

jingle_message_retract

  - Data: `Message`

  - Source: `XEP_0353`

killed

  - Data: `{}`

  - Source: `XMLStream`

  When the stream is aborted.

legacy_login

  - Data: `Presence`

  - Source: `XEP_0100`

legacy_logout

  - Data: `Presence`

  - Source: `XEP_0100`

legacy_message

  - Data: `Message`

  - Source: `XEP_0100`

legacy_presence_unavailable

  - Data: `Presence`

  - Source: `XEP_0100`

marker

  - Data: `Message`

  - Source: `XEP_0333`

  Whenever a chat marker is received (any of them).

marker_acknowledged

  - Data: `Message`

  - Source: `XEP_0333`

  Whenever an `<acknowledged/>` chat marker is received.

marker_displayed

  - Data: `Message`

  - Source: `XEP_0333`

  Whenever a `<displayed/>` chat marker is received.

marker_received

  - Data: `Message`

  - Source: `XEP_0333`

  Whenever a `<received/>` chat marker is received.

message

  - Data: `Message`

  - Source: `BaseXMPP`

  Makes the contents of message stanzas that include <body> tags available whenever one is received. Be sure to check the message type to handle error messages appropriately.

message_correction

  - Data: `Message`

  - Source: `XEP_0308`

  Whenever a message containing a correction is received.

message_error

  - Data: `Message`

  - Source: `BaseXMPP`

  Makes the contents of message stanzas available whenever one is received. Only handler messages with an `error` type.

message_form

  - Data: `Form`

  - Source: `XEP_0004`

  Currently the same as message_xform.

message_xform

  - Data: `Form`

  - Source: `XEP_0004`

  Triggered whenever a data form is received inside a message.

moderated_message

  - Data: `Message`

  - Source: `XEP_0425`

muc::[room]::got_offline

  - Data: `Presence`

  - Source: `XEP_0045`

  - Name parameters: `room`, the room this is coming from.

  Triggered whenever we receive an unavailable presence from a MUC occupant.

muc::[room]::got_online

  - Data: `Presence`

  - Source: `XEP_0045`

  - Name parameters: `room`, the room this is coming from.

  Triggered whenever we receive a presence from a MUC occupant we do not have in the local cache.

muc::[room]::message

  - Data: `Message`

  - Source: `XEP_0045`

  - Name parameters: `room`, the room this is coming from.

  Triggered whenever we receive a message from a MUC we are in.

muc::[room]::presence

  - Data: `Presence`

  - Source: `XEP_0045`

  - Name parameters: `room`, the room this is coming from.

muc::[room]::presence-error

  - Data: `Presence`

  - Source: `XEP_0045`

  - Name parameters: `room`, the room this is coming from.

  Triggered whenever we receive a presence of `type="error"` from a MUC.

muc::[room]::self-presence

  - Data: `Presence`

  - Source: `XEP_0045`

  - Name parameters: `room`, the room this is coming from.

  Triggered whenever we receive a presence with status code `110` (for example on MUC join, or nick change).

muc_ping_changed

  - Data: `dict(key: Tuple[JID, JID], previous: PingStatus, result: PingStatus)`

  - Source: `XEP_0410`

presence_available

  - Data: `Presence`

  - Source: `BaseXMPP`

  A presence stanza with a type of ‘`available`’ is received.

presence_error

  - Data: `Presence`

  - Source: `BaseXMPP`

  A presence stanza with a type of ‘`error`’ is received.

presence_form

  - Data: `Form`

  - Source: `XEP_0004`

  This event is present in the XEP-0004 plugin code, but is currently not used.

presence_probe

  - Data: `Presence`

  - Source: `BaseXMPP`

  A presence stanza with a type of ‘`probe`’ is received.

presence_subscribe

  - Data: `Presence`

  - Source: `BaseXMPP`

  A presence stanza with a type of ‘`subscribe`’ is received.

presence_subscribed

  - Data: `Presence`

  - Source: `BaseXMPP`

  A presence stanza with a type of ‘`subscribed`’ is received.

presence_unavailable

  - Data: `Presence`

  - Source: `BaseXMPP`

  A presence stanza with a type of ‘`unavailable`’ is received.

presence_unsubscribe

  - Data: `Presence`

  - Source: `BaseXMPP`

  A presence stanza with a type of ‘`unsubscribe`’ is received.

presence_unsubscribed

  - Data: `Presence`

  - Source: `BaseXMPP`

  A presence stanza with a type of ‘`unsubscribed`’ is received.

pubsub_config

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `config` is received.

pubsub_delete

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `delete` is received.

pubsub_publish

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `publish` is received.

pubsub_purge

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `purge` is received.

pubsub_retract

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `retract` is received.

pubsub_subscription

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `subscription` is received.

reactions

  - Data: `Message`

  - Source: `XEP_0444`

  When a message containing reactions is received.

receipt_received

  - Data: `Message`

  - Source: `XEP_0184`

  Whenever a message receipt is received.

retracted_message

  - Data: `Message`

  - Source: `XEP_0424`

room_activity

  - Data: `Presence`

  - Source: `XEP_0437`

  When a room activity stanza is received by a client.

room_activity_bare

  - Data: `Presence`

  - Source: `XEP_0437`

  When an empty room activity stanza is received (typically by a component).

roster_update

  - Data: `Roster`

  - Source: `ClientXMPP`

  An IQ result containing roster entries is received.

sent_presence

  - Data: `{}`

  - Source: `Roster`

  Signal that an initial presence stanza has been written to the XML stream.

session_end

  - Data: `{}`

  - Source: `XMLStream`

  Signal that a connection to the XMPP server has been lost and the current stream session has ended. Equivalent to disconnected, unless the XEP-0198: Stream Management plugin is loaded.

  Plugins that maintain session-based state should clear themselves when this event is fired.

session_resumed

  - Data: `{}`

  - Source: `XEP_0198`

  When Stream Management manages to resume an ongoing session after reconnecting.

session_start

  - Data: `{}`

  - Source: `ClientXMPP`, `ComponentXMPP`, `XEP-0078`

  Signal that a connection to the XMPP server has been made and a session has been established.

sm_disabled

  - Data: `{}`

  - Source: `XEP_0198`

  When Stream Management gets disabled (when disconnected).

sm_enabled

  - Data: `Enabled`

  - Source: `XEP_0198`

  When Stream Management is successfully enabled.

socket_error

  - Data: `Socket` exception object

  - Source: `XMLStream`

ssl_cert

  - Data: `str`

  - Source: `XMLStream`

  Signal containing a PEM representation of the peer certificate when establishing a TLS connection. The certificate can be checked synchronously in this handler, and the attempt can be aborted if needed.

ssl_invalid_chain

  - Data: `ssl.SSLError` the ssl exception

  - Source: `XMLStream`

  Signal emitted when there is an SSL error when connecting. If not handled, slixmpp will disconnect rather than attempt connecting using the next method.

stanza_not_sent

  - Data: `RootStanza` or `str`, the stanza slixmpp attempted to send

  - Source: `XMLStream`

  Signal emitted when a stanza could not be sent because slixmpp is not connected (fully or at all) to the server. The stanza is queued for sending when the connection is established again.

stream:[stream id]:[peer jid]

  - Data: `IBBBytestream`

  - Source: `XEP_0047`

  - Name parameters: `stream id`, the id of the stream, and `peer jid` the JID of the entity the stream is established with.

  When a stream is opened (with specific sid and jid parameters).

stream_error

  - Data: `StreamError`

  - Source: `BaseXMPP`

tls_success

  - Data: None

  - Source: `XMLStream`

  Signal following `ssl_cert` indicating that a TLS connection has been established and the XML stream will be proceeding.

# Dedicated PubSub Events

The `XEP_0060` plugin (and `XEP_0163` plugin, which uses the former) allows other plugins to map specific namespaces in PubSub notifications to a dedicated name prefix.

The current list of plugin prefixes is the following:

- `bookmarks`: `XEP_0048`

- `user_location`: `XEP_0080`

- `avatar_metadata`: `XEP_0084`

- `avatar_data`: `XEP_0084`

- `user_mood`: `XEP_0107`

- `user_activity`: `XEP_0108`

- `user_tune`: `XEP_0118`

- `reachability`: `XEP_0152`

- `user_nick`: `XEP_0172`

- `user_gaming`: `XEP_0196`

- `mix_participant_info`: `XEP_0369`

- `mix_channel_info`: `XEP_0369`

[plugin]_config

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `config` is received.

[plugin]_delete

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `delete` is received.

[plugin]_publish

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `publish` is received.

[plugin]_purge

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `purge` is received.

[plugin]_retract

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `retract` is received.

[plugin]_subscription

  - Data: `Message`

  - Source: `XEP_0060`

  When a pubsub event of type `subscription` is received.