Skip to content

XMPP

XMPP (Extensible Messaging and Presence Protocol) is an open protocol for near-real-time messaging. Shoutrrr's XMPP service enables sending fire-and-forget chat and multi-user chat (MUC) notifications to XMPP servers, such as ejabberd and Prosody. Upstream docs: https://xmpp.org/

URL Formats

The XMPP service supports two URL schemes for connection security:

  • xmpp://: STARTTLS on port 5222 by default

xmpp://user:password@host[:port]/?to=jid[&rooms=roomjid]

  • xmpps://: implicit TLS on port 5223 by default

xmpps://user:password@host[:port]/?to=jid[&rooms=roomjid]

URL Fields

  • User - Auth JID localpart or full JID (Required)
    URL part: xmpp://user:password@host:port/
  • Password - Auth password (Required)
    URL part: xmpp://user:password@host:port/
  • Host - XMPP server hostname (Required)
    URL part: xmpp://user:password@host:port/
  • Port - XMPP server port (Required)
    URL part: xmpp://user:password@host:port/

Query/Param Props

Props can be either supplied using the params argument or through the URL using ?key=value&key=value etc.

  • disabletls - Disable TLS (xmpp:// only) Default: ❌ No

  • nick - MUC nickname Default: empty

  • roompassword - Password for protected MUC rooms Default: empty

  • rooms - MUC room JIDs Default: empty

  • skiptlsverify - Skip TLS certificate verification Default: ❌ No

  • title - Optional title prepended to the message body Default: empty

  • to - Chat recipient JIDs Default: empty

At least one of to or rooms is required.

Authentication JID

The URL userinfo is the login identity:

  • A localpart (alice) becomes alice@host.
  • A full JID (alice%40jabber.example.com) is used as-is, while host remains the TCP dial target.
xmpp://alice%40jabber.example.com:[email protected]/[email protected]

TLS

  • Use xmpp:// for STARTTLS (default port 5222).
  • Use xmpps:// for implicit TLS (default port 5223).
  • Use disabletls=yes only with xmpp:// for plaintext on a trusted network. Combining it with xmpps:// is rejected.
  • Use skiptlsverify=yes to skip certificate verification (self-signed or internal TLS). TLS 1.2 remains the minimum.

Plaintext SASL is used only when disabletls=yes is set. Encrypted connections prefer SCRAM-SHA-256, then SCRAM-SHA-1, then PLAIN.

Recipients

  • to: comma-separated JIDs sent as type=chat.
  • rooms: comma-separated MUC JIDs. The service joins, sends type=groupchat, and leaves.
  • nick: MUC nickname. Defaults to the auth JID localpart.
  • roompassword: password applied to every room in the URL.

A title is prepended to the message body. The MUC subject is never changed.

Examples

Direct chat

xmpp://alice:[email protected]/[email protected]

Multiple chat recipients and a room

xmpp://alice:[email protected]/[email protected],[email protected]&[email protected]

Implicit TLS with a self-signed certificate

xmpps://alice:[email protected]/[email protected]&skiptlsverify=yes

Password-protected room

xmpp://alice:[email protected]/[email protected]&nick=shoutrrr&roompassword=s3cret