Skip to main content

Set a user's Will Return / Out of Roam

POST 
/user.status.set

Record an absence on a workspace member — the same Will Return Today / Out of Roam field the desktop client writes, already readable via user.info?expand=status and user.status.update.

This is not external activity. Use user.status.set for HR absences (sick leave, vacation, parental leave, public holidays). Use user.activity.set for a short-lived on-map glow / emoji (phone call, browser meeting).

willReturn is last-writer-wins with the desktop client. Setting it does not check the user out, does not enable Do Not Disturb, and does not accept a status enum (checkedIn / checkedOut stay read-only).

outOfRoam defaults to true (persistent Out of Roam, up to 2 years). Pass outOfRoam: false for same-day Will Return Today (returnTime must be less than 10 hours from now).

Identify the user with userId: a bare UUID, tagged U-… ID, or ASCII email (same convention as group.create members). Third-party systems that only have an email do not need a UUID lookup first.

See Will Return / Out of Roam for the two modes, persistence across check-in, and an HRIS example.

Access: Organization and Personal. Organization tokens may target any active member in the workspace. Personal tokens (OAuth or PAT) may target only the token owner.

Required scope: user:write.status. Personal Access Tokens skip this check; personal-mode OAuth installs must still request the scope. Reading the field back via user.info still needs user:read.status.

OpenAPI Spec: chat-v1.json

Request​

Responses​

Absence saved. willReturn echoes the written value (including defaulted outOfRoam). status is the user's current check-in (checkedIn / checkedOut) and is unchanged by this call. userId is the canonical UUID.