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.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet


Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Presence.ReadWrite Not available.
Delegated (personal Microsoft account) Not supported. Not supported.
Application Presence.ReadWrite.All Not available.

HTTP request

POST /users/{userId}/presence/setUserPreferredPresence

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
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.


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



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

Content-Type: application/json

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


The following example shows the response.

HTTP/1.1 200 OK