-
Notifications
You must be signed in to change notification settings - Fork 31
Presence Status
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.
-
PresenceHandle
-
getHandle(): Long: Get the unique handle identifier.
PresenceHandle
object (returned whilestartWatchingPresences
) 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
.
-
getHandle(): Long: Get the unique handle identifier.
-
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.
- Unknown
- Pending
- Active
- Inactive
- Dnd (Do Not Disturb)
- Quiet
- Busy
- OutOfOffice
- Call
- Meeting
- Presenting
- CalendarItem
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()}")
}
When no longer needed, use webex.people.stopWatchingPresences()
to stop receiving updates for a list of presence handles.
webex.people.stopWatchingPresences(presenceHandles)
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")
}
}