Presence Status

Presence Status

Overview

Presence Status API provides real-time status updates about contacts which include predefined states, custom messages, and state-specific expiration and last active times. The usage of the API revolves around starting and stopping to watch the presence status of specific contacts. The related APIs can be accessed through PersonClient.kt. This functionality is available starting from SDK version 3.10.0.

Key API Components

• PresenceHandle

  • getHandle(): Long: Get the unique handle identifier. PresenceHandle object (returned while startWatchingPresences) will have distinct handle identifier for each contactID.
  • getContactId(): String: Retrieve the contact ID.
  • isValid(): Boolean: Check if the handle is valid. For invalid contact Ids or bot contact Ids this will return false.

• Presence

  • getContactId(): String: Obtain the contact's ID for this presence status.
  • getStatus(): PresenceStatus: Get the current presence status.
  • getCustomStatus(): String: Retrieve any custom status message set by user.
  • getLastActiveTime(): Long: Obtain the last active UTC time in milliseconds.
  • getExpiresTime(): Long: Get the expiry UTC time in milliseconds for statuses like DND, OutOfOffice, etc.

Presence States

1. Unknown
2. Pending
3. Active
4. Inactive
5. Dnd (Do Not Disturb)
6. Quiet
7. Busy
8. OutOfOffice
9. Call
10. Meeting
11. Presenting
12. CalendarItem

API Usage with Examples

1. Start Watching Presences

To start watching presence status updates for a list of contact IDs, use the webex.people.startWatchingPresences() API.

val contactIds = listOf("ContactId1", "ContactId2")
val presenceHandles = webex.people.startWatchingPresences(contactIds) { presence ->
    // Handle presence updates
    println("Updated presence for ${presence.getContactId()}: ${presence.getStatus()}")
}

2. Stop Watching Presences

When no longer needed, use webex.people.stopWatchingPresences() to stop receiving updates for a list of presence handles.

webex.people.stopWatchingPresences(presenceHandles)

3. Handling Presence Updates

Upon receiving a presence update, utilize the Presence interface to manage and display the obtained information. Ensure to respect the getExpiresTime() for statuses like DND, OutOfOffice, etc., and use getLastActiveTime() to display how long a user has been inactive.

Example:

val presenceHandles = webex.people.startWatchingPresences(contactIds) { presence ->
    println("Contact: ${presence.getContactId()}")
    println("Status: ${presence.getStatus()}")
    println("Custom Message: ${presence.getCustomStatus()}")
    
    if (presence.getStatus() == PresenceStatus.Inactive) {
        println("Last active: ${presence.getLastActiveTime()}ms ago")
    }

    if (presence.getStatus() in listOf(PresenceStatus.Dnd, PresenceStatus.OutOfOffice, PresenceStatus.Quiet)) {
        println("Status expires in: ${presence.getExpiresTime()}ms")
    }
}