Skip to main content

Sending an initial Presence

Presence information is a core functionality of the XMPP protocol. It allows users to broadcast their availability status to others on the network. When communicating over XMPP, it is often necessary to send presence notifications to inform others (usually contacts in your roster) about your current status, such as whether you're online, offline, away, or busy. These presence updates help users know when they can interact with one another in real-time.

In XMPP, presence information is typically sent to all users in your roster by default, but it can also be targeted to specific individuals or groups. The presence status is represented by different states, such as:

  • Available: Indicates that the user is online and ready for communication.
  • Away: Shows that the user is online but currently idle or away from their device.
  • Do Not Disturb (DND): Signals that the user is online but does not want to be interrupted.
  • Offline: Indicates that the user is not connected to the XMPP server.

XMPP uses presence to manage resources when a user is logged in from multiple devices (e.g., desktop and mobile) and to route messages accordingly.

In Whixp, sending a presence message is straightforward and can be triggered once the XMPP stream is negotiated. After a successful connection and stream negotiation, the client can notify other users of its presence status by sending a presence stanza:

whixp.addEventHandler('streamNegotiated', (_) => whixp.sendPresence());

When you send a presence message, you can observe the log output generated by Whixp, showing both the sent and received presence stanzas. Here’s an example of what you might see in the log:

[Whixp] SEND: <presence/>
[Whixp] RECEIVED: <presence xml:lang='en' to='vsevolod@localhost/desktop' from='vsevolod@localhost/desktop' xmlns="jabber:client"><x xmlns='vcard-temp:x:update'/></presence>

In Whixp, you have the flexibility to send different types of presence messages depending on your current availability. This is done by specifying the presence type when sending the message.

For example, if you want to notify your contacts that you are "away", you can specify this status using the show attribute when calling the sendPresence() method:

whixp.addEventHandler(
    'streamNegotiated',
    (_) => whixp.sendPresence(show: 'away'),
  );

The result of the sent stanza can be shown in the outputs log:


[Whixp] SEND: <presence><show>away</show></presence>
[Whixp] RECEIVED: <presence xml:lang='en' to='vsevolod@localhost/desktop' from='vsevolod@localhost/desktop' xmlns="jabber:client"><x xmlns='vcard-temp:x:update'/><show>away</show></presence>

Detailed presence​

In Whixp, you can send more detailed presence messages by specifying various parameters such as the recipient, availability status, nickname, custom status messages, and priority. This flexibility allows you to tailor your presence notifications according to your needs.

whixp.sendPresence(
      to: JabberID('alyosha@localhost'),
      show: 'away',
      nick: 'vsevex',
      status: 'I am away',
      priority: 1,
);

Breakdown of parameters:​

  • to: This parameter specifies the recipient of the presence message. In this case, it’s sent to the Jabber ID of a specific user (alyosha@localhost). This allows you to target presence updates to particular contacts rather than broadcasting to everyone in your roster.
  • show: This indicates the user's current status. By setting it to away, you are informing the recipient that you are currently not at your device, but you are still online.
  • nick: This parameter sets the nickname to be displayed along with the presence message. This can be useful for users who have different display names or want to differentiate themselves in group chats or multi-user environments.
  • status: This custom status message provides additional context about your availability.
  • priority: The priority parameter determines the importance of the presence message. It allows the server to manage multiple presence messages from the same user (e.g., from different devices). A higher priority value indicates a more preferred presence status. In this case, a priority of 1 suggests that the user wants this presence to be recognized, but it can be adjusted depending on the user's needs.

Handler​

You can add a presence handler in Whixp to accept and process incoming presence stanzas according to your requirements. This functionality allows you to implement various features, such as filtering presence types, managing user availability based on the sender, or bypassing redundant presence messages sent by the server.

Here’s an example of how to implement a presence handler:

whixp.addEventHandler<Presence>('presence', (presence) {
    if (presence == null) return; // Check if the presence stanza is null
    final from = presence.from?.bare;  // Get the bare JID of the sender

    log('Presence from: $from');
  });

Presence Types​

XMPP defines several presence types that indicate the nature of the presence update:

  • Available: The default presence type, indicating the user is online and available for communication.
  • Unavailable: Indicates the user is offline or not available. This is typically sent when disconnecting.
  • Subscribe: A request to subscribe to a user's presence updates.
  • Subscribed: Confirmation that a subscription request has been accepted.
  • Unsubscribe: A request to unsubscribe from a user's presence updates.
  • Unsubscribed: Confirmation that an unsubscribe request has been processed.
  • Probe: A request to check the current presence status of a user.
  • Error: Indicates an error occurred while processing a presence stanza.

You can specify the presence type when sending presence:

// Send unavailable presence when going offline
whixp.sendPresence(type: 'unavailable');

// Send available presence (default)
whixp.sendPresence();

Presence Show Values​

The show attribute provides more granular information about availability:

  • away: The user is away from their device but still online.
  • chat: The user is available and actively engaged in chat.
  • dnd: Do Not Disturb - the user is online but doesn't want to be interrupted.
  • xa: Extended Away - the user is away for an extended period.
whixp.sendPresence(show: 'dnd', status: 'In a meeting');

Priority Management​

Priority values range from -128 to 127, with higher values indicating higher priority. When a user has multiple resources (connections), the server uses priority to determine which resource should receive messages:

// Desktop connection with high priority
whixp.sendPresence(priority: 10);

// Mobile connection with lower priority
whixp.sendPresence(priority: 5);

Messages are typically routed to the resource with the highest priority. If multiple resources have the same priority, the server may use other criteria (such as most recent activity) to determine message routing.

info

In upcoming updates, Whixp will enhance its handling of presence information by automatically managing user availability based on roster information and handling necessary roster updates according to the presence types received. For now, however, you will need to manage this information manually within your application logic.