XMPP Notifications

Overview

• Source: https://xmpp.org/
• Image Support: No
• Attachment Support: No
• Message Character Limits:
  • Body: 32768
• Build Your Apprise URL

Account Setup

XMPP support requires slixmpp version 1.10.0 or newer:

pip install "slixmpp>=1.10.0"

From here, you will need:

1. An existing XMPP account username (on a self-hosted or remotely hosted XMPP server).
2. The password associated with that account.
3. The hostname of your XMPP server.
4. (Optional) The port the XMPP server listens on.

In Apprise, the login JID is automatically constructed as {user}@{host}. You do not need to explicitly provide a full JID. Authentication credentials are supplied using {user}:{password}@{host}, but the resulting login identity is always normalized to {user}@{host}.

Syntax

Valid syntax is as follows:

• xmpp://{user}:{password}@{host}
• xmpps://{user}:{password}@{host}
• xmpp://{user}:{password}@{host}:{port}
• xmpp://{user}:{password}@{host}/{jid}
• xmpp://{user}:{password}@{host}/{jid1}/{jid2}
• xmpps://{user}:{password}@{host}/{jid}?verify=no

Secure connections should be referenced using xmpps://, whereas insecure connections should be referenced using xmpp://.

If no target is specified, Apprise sends the notification to the authenticated account itself ({user}@{host}).

Targets may also be supplied using the to= query argument (comma-separated).

Multi-User Chat (MUC) Rooms

To send to an XMPP Multi-User Chat room (XEP-0045), prefix the room JID with #:

• xmpps://{user}:{password}@{host}/#room@{conference_host}
• xmpps://{user}:{password}@{host}/#room1@{ch}/#room2@{ch}

You can mix room and user targets freely in the same URL:

• xmpps://{user}:{password}@{host}/#room@{ch}/{jid}

Note

When Apprise reconstructs a URL internally (e.g. for logging or storage), MUC room prefixes are stored as # (or url-encoded %23) to avoid ambiguity with regular JID identifiers. Both forms are accepted on input.

Parameter Breakdown

Variable	Required	Description
user	Yes	XMPP username (localpart), combined with host to form the login JID
password	Yes	Password for the XMPP account
host	Yes	XMPP server hostname (domain)
port	No	Server port (defaults: 5222 for xmpp, 5223 for xmpps)
mode	No	Transport secure mode override; possible values are none, starttls, or tls
roster	No	Retrieves roster from the server after connection; default is no
keepalive	No	Enables XMPP keepalive mode to maintain a persistent connection between notifications. This is only effective when Apprise remains resident in memory (for example, in long-running applications). It has no practical effect when using the Apprise CLI or API in one-shot mode, as the instance is created, sends the notification, and is then destroyed. Even with ?keepalive=yes, the connection closes once the Apprise instance goes out of scope. Default is no.
subject	No	Messages are sent as mtype=chat, which do not typically use the built-in XMPP subject= field. Setting this to yes redirects any title provided into the subject= field instead of concatenating it to the body (default behavior which is subject=no).
name	No	Nickname used when joining MUC rooms (alphanumeric and underscores only). The JID username is detected and used by default unless explicitly overridden here. If neither is available, the system default is used.
to	No	Alternate way to specify target JIDs or MUC rooms (comma-separated); prefix rooms with #
target	No	Recipient JID (plain user) or MUC room JID when prefixed with #

Global Parameters

Variable	Description
overflow	This parameter can be set to either split, truncate, or upstream. This determines how Apprise delivers the message you pass it. By default this is set to upstream 👉 upstream: Do nothing at all; pass the message exactly as you received it to the service. 👉 truncate: Ensure that the message will fit within the service’s documented upstream message limit. If more information was passed then the defined limit, the overhead information is truncated. 👉 split: similar to truncate except if the message doesn’t fit within the service’s documented upstream message limit, it is split into smaller chunks and they are all delivered sequentially there-after.
format	This parameter can be set to either text, html, or markdown. Some services support the ability to post content by several different means. The default of this varies (it can be one of the 3 mentioned at any time depending on which service you choose). You can optionally force this setting to stray from the defaults if you wish. If the service doesn’t support different types of transmission formats, then this field is ignored.
verify	External requests made to secure locations (such as through the use of https) will have certificates associated with them. By default, Apprise will verify that these certificates are valid; if they are not then no notification will be sent to the source. In some occasions, a user might not have a certificate authority to verify the key against or they trust the source; in this case you will want to set this flag to no. By default it is set to yes.
cto	This stands for Socket Connect Timeout. This is the number of seconds Requests will wait for your client to establish a connection to a remote machine (corresponding to the connect()) call on the socket. The default value is 4.0 seconds.
rto	This stands for Socket Read Timeout. This is the number of seconds the client will wait for the server to send a response. The default value is 4.0 seconds.
emojis	Enable Emoji support (such as providing :+1: would translate to 👍). By default this is set to no. Note: Depending on server side settings, the administrator has the power to disable emoji support at a global level; but default this is not the case.
tz	Identify the IANA Time Zone Database you wish to operate as. By default this is detected based on the configuration the server hosting Apprise is running on. You can set this to things like America/Toronto, or any other properly formated Timezone describing your area.

Secure Modes

The mode parameter explicitly controls how the XMPP connection is established and overrides the schema (xmpp:// or xmpps://) default.

Mode	Description
none	Plaintext connection (no TLS)
starttls	STARTTLS upgrade on a plaintext connection
tls	Direct TLS connection

Note

The XMPP plugin takes the most secure option when presented with an ambiguous situation:

1. If you use a secure schema (xmpps://) while also setting mode=none, the secure schema prevails and starttls is used.
2. If you use an insecure schema (xmpp://) while setting mode=starttls or mode=tls, the secure mode you specified prevails.

:::

Default behaviour

• xmpp:// defaults to mode=none
• xmpps:// defaults to mode=starttls

Keepalive Mode

Keepalive mode is intended for long-running applications that reuse a single Apprise instance.

When enabled:

• The XMPP connection remains open between notifications.
• Multiple messages reuse the same session.
• Connection overhead is reduced.

When using the CLI or a one-shot execution model, keepalive provides no benefit because the process exits immediately after sending.

Example of enabling keepalive:

apprise -vv -b "Persistent Message" \
  xmpps://user:password@chat.example.com?keepalive=yes

In embedded usage:

from apprise import Apprise

a = Apprise()
a.add("xmpps://user:password@chat.example.com?keepalive=yes")

a.notify(body="First message")
a.notify(body="Second message")

In this scenario, the connection is reused between notifications.

JID Assembly

Apprise normalizes JIDs to ensure consistent and predictable behaviour, even when shorthand forms are used.

Consider the following Apprise XMPP URL:

         xmpp://user:pass@example.ca
                              ^
                              |
                         default_host

Defining Resources

Use %2F to represent a resource (acts as /) when specifying resources in the URL path, for example: jason@example.ca%2Fresource.

Alternatively, use the to= query argument, which eliminates the need to URL-encode /. For example: ?to=jason@example.ca/resource.

Multi-User Chat (MUC)

MUC is the XMPP group chat protocol (XEP-0045). A MUC room JID typically looks like roomname@conference.example.com. Apprise identifies MUC targets by the # prefix — the same convention used by IRC and many chat applications. When Apprise joins a room it uses the sender’s username as the nickname.

URL	Targets Notified
xmpps://user:pass@example.ca	user@example.ca (self)
xmpps://user:pass@example.ca/jane	jane@example.ca
xmpps://user:pass@example.ca/jane/joe	jane@example.ca, joe@example.ca
xmpps://user:pass@example.ca/jane@foobar.ca	jane@foobar.ca
xmpps://user:pass@example.ca/jason%2Fmobile	jason@example.ca/mobile
xmpps://user:pass@example.ca/jane@foobar.ca%2Fworkstation	jane@foobar.ca/workstation
xmpps://user:pass@example.ca/#general@conference.example.ca	MUC room general@conference.example.ca
xmpps://user:pass@example.ca/#general@conference.example.ca/jane	MUC room general@... and user jane@example.ca
xmpps://user:pass@example.ca/#room1@conference.ca/#room2@conference.ca	MUC rooms room1@... and room2@...

Examples

Send a plaintext XMPP notification:

apprise -vv -b "Test Message" \
  xmpp://user:password@localhost

Send a STARTTLS-secured notification:

apprise -vv -b "Secure Message" \
  xmpp://user:password@localhost?mode=starttls

Send a direct TLS notification:

apprise -vv -b "TLS Message" \
  xmpps://user:password@chat.example.com

Send a message to a specific recipient:

apprise -vv -t "Test Title" -b "Hello from Apprise" \
  xmpps://user:password@chat.example.com/alice@example.net

Send a message to multiple recipients using the to= argument:

apprise -vv -b "Group Message" \
  xmpps://user:password@chat.example.com?to=alice@example.net,bob@example.org

Disable TLS certificate verification:

apprise -vv -b "Test Message" \
  xmpps://user:password@chat.example.com/alice@example.net?verify=no

Send a notification to a resource:

apprise -vv -b "Test Message" \
  xmpps://user:password@chat.example.com/?to=alice@example.net/mobile

Send a message to a MUC room:

apprise -vv -b "Hello, room!" \
  "xmpps://user:password@chat.example.com/#general@conference.example.com"

Send a message to multiple MUC rooms and a direct user:

apprise -vv -b "Broadcast" \
  "xmpps://user:password@chat.example.com/#ops@conference.example.com/#dev@conference.example.com/alice@example.com"

Send to a MUC room using the to= argument:

apprise -vv -b "Room message" \
  "xmpps://user:password@chat.example.com?to=#general@conference.example.com"