> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Users: personal presence, DND schedules, and status messages

> Set and automate your own presence — available/busy/away/DND, timed DND windows, recurring business-hours schedules, and status messages — via PATCH /api/v1/users/me/presence.

# Users: personal presence and schedules

Your personal presence is the state inbound routing checks first, and these endpoints let a script, softphone, or browser widget drive the state for **your own account**. This section covers the two self-service presence operations — set one status now, or automate a weekly DND envelope — and what each status does to routing.

Prefer the **header toggle** for a one-tap change; the Users API exists to power integrations. If you federated presence from Teams, Slack, Webex, or a calendar, the federation keeps writing the same record — use this page when you need control beyond federation.

Authenticate with an API key (`X-API-Key: dv_live_sk_…`). Each response returns only your own persisted presence under `data` — this route never touches another user.

## Set your presence

```bash theme={null}
curl -X PATCH "$BASE/api/v1/users/me/presence" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"busy","activity":"in_a_call","status_message":"On a customer call until 3pm"}'
```

`status` accepts `available`, `busy`, `away`, or `dnd`, and the refinements below layer only when the status they describe is in force:

| Field            | Only meaningful with | Behaviour                                                                                            |
| ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| `status_message` | any status           | A short free-text note (≤200 chars) that persists across later status changes until you send `null`. |
| `dnd_until`      | `dnd`                | ISO 8601 timestamp in the future; clears when a non-DND status lands or the schedule takes over.     |
| `activity`       | `busy`               | `in_a_call` or `in_a_meeting`; cleared by any non-busy status.                                       |

Return to available (clearing the refinements in one call):

```bash theme={null}
curl -X PATCH "$BASE/api/v1/users/me/presence" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"available","status_message":null}'
```

Every accepted change is idempotent, publishes a `user.presence.changed` realtime event on the tenant channel, and invalidates the inbound-routing DND cache immediately — routing reads the new state on the next lookup. The response always returns your persisted presence, so a busy softphone's read-back stabilises on the last write.

Example of the persisted shape:

```json theme={null}
{
  "data": {
    "user_id": "user_…",
    "presence_status": "busy",
    "presence_set_at": "2026-09-03T14:22:11Z",
    "dnd_until": null,
    "status_message": "On a customer call until 3pm",
    "activity": "in_a_call"
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-09-03T14:22:11Z" }
}
```

## Recurring DND schedule (business hours)

Set the envelope once; a 60-second worker tick flips presence between `available` inside the window and `dnd` outside it:

```bash theme={null}
curl -X PATCH "$BASE/api/v1/users/me/presence/schedule" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true,"timezone":"Europe/Paris","daysOfWeek":[1,2,3,4,5],"startMinute":480,"endMinute":1080}'
```

| Field         | Type                              | Notes                                                               |
| ------------- | --------------------------------- | ------------------------------------------------------------------- |
| `enabled`     | boolean                           | `false` disables the schedule.                                      |
| `timezone`    | IANA string (e.g. `Europe/Paris`) | Local time, so daylight-saving shifts land on the right wall clock. |
| `daysOfWeek`  | int array 0–6 (Sunday=0)          | Deduplicated + sorted before persistence.                           |
| `startMinute` | int 0–1439                        | Minutes since 00:00 local (480 = 08:00).                            |
| `endMinute`   | int 0–1440                        | `1440` is the end-of-day sentinel for 24-hour envelopes.            |

A manual time-bounded `dnd_until` always wins over the schedule — a timed DND you set directly stays in force through its own expiry, then the schedule resumes.

Disable the automation without touching presence:

```json theme={null}
{"enabled":false}
```

The response returns the persisted envelope (`enabled`, `timezone`, dedup-sorted `daysOfWeek`, `startMinute`, `endMinute`).

## What presence does to inbound routing

`dnd` (or an in-force DND window) removes you from eligible claims the moment it lands — the routing cache invalidation is synchronous, not eventual. `busy` blocks the voice claim while the digital-assignment ledger still counts your load normally. For the ACD-audit semantics behind these four public values (and the five-state model dispatch actually checks), see [Agent presence and aux-code lifecycle](/concepts/agent-presence-lifecycle).

## Related

* [Presence federation settings](/guides/presence-federation-settings) — let Teams, Slack, Webex, Zoom calendars write this same state.
* [Agent presence and aux-code lifecycle](/concepts/agent-presence-lifecycle) — the ACD state machine behind the four public values.
* [My voice preferences](/guides/me-voice-preferences) — the sibling "Me" settings endpoints.