Skip to content

Configure XMPP

XMPP (Jabber) is the chat protocol used by some Asterisk softphones and the legacy UCP chat widget for messaging between extensions. New deployments typically use Sangoma Connect for chat instead — XMPP is increasingly legacy.

Legacy

XMPP support in UnifiedBX is being phased out. For new chat/IM deployments, use Sangoma Connect which has better mobile support and integrates with Sangoma Talk.

Before You Start

  • The XMPP module is installed (it's standard on most UnifiedBX builds, but confirm at System Admin → Modules).
  • You know whether you want server-mode (UnifiedBX hosts the XMPP server for internal chat) or client-mode (UnifiedBX connects out to an XMPP server).

Steps (server mode — internal chat)

  1. Go to System Attributes → XMPP.
  2. General Settings:
    • Enable XMPP Server — Yes.
    • Hostname — UnifiedBX FQDN, e.g. pbx.client.com. Will be the XMPP domain too.
    • Port — 5222 (default).
    • TLS Port — 5223.
  3. Advanced — usually defaults.
  4. Submit → Apply Config.

Add XMPP users

XMPP users are auto-created from User Management entries that have XMPP enabled:

  1. User Attributes → User Management → click user.
  2. Other → Default Permissions → XMPP — enable.
  3. Submit.

The user can now log in to XMPP using their User Management username and password, against the UnifiedBX FQDN.

Steps (client mode — connecting to external XMPP)

  1. Go to System Attributes → XMPP → Client Settings.
  2. Fill in:
    • Server — external XMPP server hostname.
    • Port — 5222.
    • Username / Password — credentials on the external server.
  3. Submit → Apply Config.

Verify

Use any XMPP client (Pidgin, Gajim, Adium, Conversations) to log in: - Server: UnifiedBX FQDN. - Username: User Management username. - Password: User Management password. - Port: 5222.

You should see contact list (other users on the server) and be able to message them.

Common Issues

  • Login fails. XMPP server not running, or User Management user doesn't have XMPP permission. Check both.
  • Port 5222 unreachable. Firewall blocking. Open in System Admin → Firewall for trusted/local zones.
  • Messages don't deliver. Recipient not online, or their client disconnected.
  • TLS errors. Self-signed cert; clients need to accept the cert (or install a real one via Cert Manager).
  • XMPP module disabled. Sangoma is deprecating; you may have to manually re-enable in Module Admin.