presence: setUserPreferredPresence

Namespace: microsoft.graph

Set the preferred availability and activity status for a user. If the preferred presence of a user is set, the user's presence shows as the preferred status.

Preferred presence takes effect only when at least one presence session exists for the user. Otherwise, the user's presence shows as Offline.

A presence session is created as a result of a successful setPresence operation, or if the user is signed in on a Microsoft Teams client.

For more details, see presence sessions and time-out and expiration.

Permissions

The following permission is required to call the API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
Delegated (work or school account) Presence.ReadWrite
Delegated (personal Microsoft account) Not supported.
Application Presence.ReadWrite.All

HTTP request

POST /users/{userId}/presence/setUserPreferredPresence

Request headers

Name Description
Authorization Bearer {token}. Required.
Content-Type application/json. Required.

Request body

In the request body, provide a JSON object with the following parameters.

Parameter Type Description
activity String The supplemental information to availability.
availability String The base presence information.
expirationDuration Duration The expiration of the app presence session represented in ISO 8601 format for durations.
If not provided, a default expiration will be applied:
- DoNotDisturb or Busy: Expiration in 1 day
- All others: Expiration in 7 days

The following table lists supported combinations of availability and activity.

availability activity Description
Available Available Set the user preferred presence as Available.
Busy Busy Set the user preferred presence as Busy.
DoNotDisturb DoNotDisturb Set the user preferred presence as DoNotDisturb.
BeRightBack BeRightBack Set the user preferred presence as BeRightBack.
Away Away Set the user preferred presence as Away.
Offline OffWork Set the user preferred presence as Offline.

Response

If successful, this method returns a 200 OK response code.

Examples

Request

The following example shows a request that sets the preferred presence as DoNotDisturb for a user, with an expiration of 8 hours.

POST https://graph.microsoft.com/v1.0/users/fa8bf3dc-eca7-46b7-bad1-db199b62afc3/presence/setUserPreferredPresence
Content-Type: application/json

{
  "availability": "DoNotDisturb",
  "activity": "DoNotDisturb",
  "expirationDuration": "PT8H"
}

Response

The following is an example of the response.

HTTP/1.1 200 OK