Messaging

Quobis wac support text messaging between users by leveraging the XMPP standard protocol. Even thought XMPP is used for instant messaging, presence, multi-party chat, voice and video calls, collaboration and generalized routing of XML data, we are using XMPP just for instant messaging. The core XMPP technologies are defined in RFCs published by the IETF, mainly RFC 6120 (XMPP Core) and RFC 6121 (XMPP IM).

Architecture

There are two services to take into account: the sippo-server.xmpp service and the xmpp-server service. The sippo-server.xmpp service is an internal service of the sippo-server responsible of integrating the xmpp-server for:

  • user authentication

  • contact management

  • active chat list management

  • group chat features

  • access control

Configuration

Initialize the service at config/wac.ini as with any other service:

; XMPP service
; This service enables communication with the XMPP server

; Configure it in `config/xmpp.toml`
[xmpp]

The file config/xmpp.toml needs to be configured as well with the following parameters:

  • xmppUrl: URL to the WebSocket where the XMPP server is listening

  • hostsAdminUrl: URL to the websocket where XMPP server will receive virtualhost updates

  • adminToken: xmpp-server admin login token, set it to the same, random, and long-enough value as in prosody.cfg.lua

Example of xmpp.toml configuration:

#  - xmppUrl: the URL to the WebSocket where the XMPP server is listening
#  - hostsAdminUrl: the URL to the websocket where XMPP server will receive virtualhost updates
#  - adminToken: the Prosody's admin login token

[xmpp]
xmppUrl = "wss://web.sippo/xmpp-websocket"
hostsAdminUrl = "http://prosody:5280/quobis_virtualhosts/virtualhost"
adminToken = "please_change_me"

Messaging via REST-API

The sippo-server.xmpp service adds the following endpoint to the REST API. All of the following endpoints MUST be authenticated with the proper Authorization header:

GET /sapi/xmpp/login
PUT /sapi/xmpp/individualChatList/:jid
GET /sapi/xmpp/individualChatList
DELETE /sapi/xmpp/individualChatList/:jid

Capability implications

Users that need messaging features must have assigned the chat capability. If no chat capability is present for a user, that user will have all chat features disabled.

Troubleshooting

  • Whenever messages are sent to an offline (or non-existing) user, those will be stored in the offline storage. If such user eventually logs in, all those offline messages will be forwarded to her. Take this into account if offline users are receiving lots of messages, user may be flooded with messages when becoming online.

  • When debug logs are enabled at xmpp-server service will a huge amount information of information on the actions taking place. Activate only to report problems to engineering. Do not activate for production

  • Please note that we only use XMPP for instant messaging, not for presence updates (we do have our own presence protocol)

  • Please notice that currently standard XMPP clients are not supported, as not all the features would be available for them.

Logs: known log messages

The xmpp service will log messages according the globally configured log level of the sippo-server.

Error level log messages

  • error: Failed to obtain [admin] XMPP client: an error occurred when trying to instantiate an XMPP client for communicating with xmpp-server. Please review connectivity and configuration parameter adminToken (and its counterpart in prosody.cfg.lua).

  • error: Failed to create <domain> host in XMPP server: an error occurred when POST``ing to ``hostsAdminUrl for creating a new domain.

  • error: Authenticate no-user error Bearer realm="Users", error="invalid_token": an error occurred while authenticating a user (will also appear for other kind of login, non-XMPP ones). In order to discover which user failed to log in, you should check xmpp-server logs.

Warning level log messages

  • warn: Failed to send invite to MUC ${muc} to user ${user}: unable to send invitation for a group chat to a user joining a group or a conference. Please review xmpp-server logs for additional information.

  • warn: Failed to revoke group membership of ${member} from ${muc}: ${error}: unable to revoke membership of user leaving a group or leaving a conference.. Please review xmpp-server logs for additional information.

Info level log messages

No log messages are defined for this level.

Debug level log messages

  • debug: Kicking ${username} from ${muc}: when a user has been removed from a group chat.

  • debug: Received a new usersGroup creation: when a new group event is received

  • debug: Received a usersGroup deletion: when a deleted group event is received

  • debug: Received a change in a group participants (joining): when a new participant enters a group event is received

  • debug: Received a change in a group participants (leaving): when a participant leaves a group event is received

  • debug: Received a notification of a new domain: when a new domain is created event is received

  • debug: Received a notification of a deleted domain: when a domain has been deleted event is received

  • debug: Received a notification of a new participant in a conference: when a new participant joins a conference event is received

  • debug: Received a notification of a participant leaving a conference: when a participant leaves a conference event is received

  • debug: Received a new conference: when a new conference has been created event is received

  • debug: Received a conference destroyed: when a conference has finished event is received

Silly level log messages

  • silly: Starting endpoints: when SAPI endpoints are being setup

  • silly: Connecting to message-broker: when the connection to RabbitMQ is being established.

  • silly: ConferenceCreated payload ${json}: the payload received for a new conference event.

  • silly: Destroying MUC ${muc}: when the MUC of a conference is going to be destroyed.