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 JID domain of your XMPP account (e.g. example.com in user@example.com).
4. (Optional) A separate server hostname if your XMPP server is hosted at a different address than your JID domain (see Split Domain below).
5. (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
• xmpps://{user}:{password}@{host}/{jid}?xmpp={xmpp_server}

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	JID domain (e.g. example.com for accounts of the form user@example.com). Also used as the connection hostname unless xmpp= is set.
port	No	Server port (defaults: 5222 for xmpp, 5223 for xmpps)
xmpp	No	Override the TCP connection hostname without changing the JID domain. Use this when your XMPP server is reachable at a different hostname than your JID domain (e.g. xmpp=xmpp.example.com). All JIDs are still built from host. See Split Domain.
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.
scramplus	No	Set to no to disable SASL SCRAM-PLUS channel-binding mechanisms. Use this when authentication fails with an “Invalid channel binding” error (see SCRAM-PLUS and Channel Binding). Default is yes.
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.
redirect	By default, Apprise will follow HTTP redirects (3xx responses) issued by the remote server, matching the behaviour of the underlying requests library. If you want to prevent custom headers and credentials from being forwarded to destinations that differ from the original URL, set this 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.
retry	The number of additional delivery attempts to make after the first failure before giving up. Accepts an integer in the range 0 to 10. The default is 0 (no retries — a single attempt is made). When combined with wait, Apprise pauses the specified number of seconds between each attempt.
wait	The number of seconds to pause between retry attempts. Accepts a decimal value in the range 0.0 to 20.0; integer values are promoted to float automatically. The default is 0.5. This value is only meaningful when retry is greater than zero — a service with retry=0 makes exactly one attempt regardless of the wait value.
optional	When set to yes, a delivery failure for this service is silently absorbed. The overall notify() call still returns True even if this endpoint was unreachable, provided that every required (non-optional) service in the same batch succeeded. Setting this flag does not skip delivery or bypass retry logic — all configured retry attempts are still made before the failure is absorbed. By default this is set to no, meaning every failure is propagated to the caller.

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@...

Split Domain / Server Hostname Override

Some XMPP deployments host the server at a different hostname than the JID domain. For example, accounts may be user@example.com but the physical server is reachable at xmpp.example.com. Normally XMPP resolves this via DNS SRV records, but when SRV records are absent or incorrect, connections will fail.

Use the xmpp= parameter to specify the connection hostname independently:

xmpps://user@example.com/joe?xmpp=xmpp.example.com

This produces:

Property	Value
Login JID	user@example.com
Target JID	joe@example.com
TCP connection	xmpp.example.com
XMPP stream to	example.com

All JIDs (login and targets) are always assembled from the URL host component (example.com). The xmpp= value is used only for the TCP connection.

Note

Without xmpp=, Apprise connects to host directly. If the server is at a different address and no DNS SRV record bridges the gap, you will see a host-unknown stream error from the server. Setting xmpp= resolves this without any URL encoding tricks.

SCRAM-PLUS and Channel Binding

By default, Apprise allows slixmpp to attempt SASL SCRAM-PLUS mechanisms (such as SCRAM-SHA-256-PLUS) when the server advertises them. These mechanisms include TLS channel-binding data to provide an additional layer of protection against man-in-the-middle attacks.

However, some server configurations or Python SSL versions cannot provide valid channel-binding data, which causes authentication to fail with a message such as:

Invalid channel binding

If you encounter this error, add ?scramplus=no to your Apprise URL to disable SCRAM-PLUS negotiation. Apprise will then negotiate a non-PLUS SASL mechanism (for example SCRAM-SHA-256 or SCRAM-SHA-1) instead. The connection remains fully encrypted by TLS; only the extra channel-binding step is skipped.

apprise -vv -b "Test" \
  "xmpps://user@example.com/joe?xmpp=xmpp.example.com&scramplus=no"

Note

This error is most commonly triggered when:

• The XMPP server does not correctly support tls-unique or tls-exporter channel binding with your Python version.
• Python 3.13+ includes tls-exporter support but the server does not accept it.

Setting ?scramplus=no resolves authentication failures in all of these cases.

This is a widespread issue in the Python SASL/TLS ecosystem. For context and upstream tracking, see the SCRAM-SASL Python ecosystem issues page.

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"

Connect to a server at a different hostname than the JID domain:

# JID domain is example.com; server is physically at xmpp.example.com
apprise -vv -b "Hello" \
  "xmpps://user@example.com/joe?xmpp=xmpp.example.com"

Disable SCRAM-PLUS when authentication fails with “Invalid channel binding”:

apprise -vv -b "Hello" \
  "xmpps://user@example.com/joe?xmpp=xmpp.example.com&scramplus=no"

Testing

For a step-by-step guide to standing up a local Prosody server and verifying notifications end-to-end, see the XMPP Testing guide.