# User status update

**Event:** `user.status.update`

## Description

A user's presence status has changed (checked in or checked out of the Roam).

**Event name:** `user:status:update`

The webhook payload contains the full user object with the updated `status`
field. When the user has a future "Will Return" / out-of-office entry, the
payload also includes `willReturn` (`returnTime`, optional `reason`,
optional `outOfRoam`). See the [User](/docs/chat-api/user-info) schema.

**Required scopes:** Your app must have `user:read` scope to receive this event. Add `user:read.email` to include the user's email address in the payload. Presence fields (`status`, `willReturn`) require `user:read.status`.

## Webhook Payload

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | TaggedUUID | Yes | The User ID |
| `name` | string | Yes | Display name of the user |
| `imageUrl` | string | No | URL of the user's profile image |
| `email` | string | No | Email address of the user (requires `user:read.email` scope) |
| `isAdmin` | boolean | No | Whether the user is an admin of the Roam |
| `jobTitle` | string | No | User's job title |
| `location` | string | No | User's location |
| `status` | "checkedIn" | "checkedOut" | No | User's current presence status. Only included when `expand=status` is requested and the `user:read.status` scope is granted. |
| `willReturn` | object | No | Out-of-office / "Will Return" status. Present only when `expand=status` is requested, the `user:read.status` scope is granted, and the user currently has a future return time set. A user can be `check |

**TaggedUUID**:

A UUID prefixed by a tag identifying the specific type of object
**willReturn**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `returnTime` | string | Yes | When the user is expected to return (RFC 3339). Localized to the caller's timezone when available; otherwise UTC. |
| `reason` | string | No | Optional absence message (e.g. "On Vacation"). |
| `outOfRoam` | boolean | No | When true, multi-day "Out of Roam" that persists across check-ins. When false or omitted, same-day "Will Return Today". |

### Example Payload

```json
{
  "id": "U-709b8a57-70bc-427a-b6f0-b16ba5297f8c",
  "name": "Alex Chen",
  "imageUrl": "https://ro.am/card-images/7be550c0-6994-4b8f-9a41-48825c6fc62a",
  "email": "alex.chen@example.com",
  "isAdmin": false,
  "status": "checkedOut",
  "willReturn": {
    "returnTime": "2026-07-20T09:00:00-07:00",
    "reason": "On Vacation",
    "outOfRoam": true
  }
}
```

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/webhooks-v0-dev/user-status-update*