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

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):

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:

{
  "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:

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:

{"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.

Presence federation settings — let Teams, Slack, Webex, Zoom calendars write this same state.
Agent presence and aux-code lifecycle — the ACD state machine behind the four public values.
My voice preferences — the sibling “Me” settings endpoints.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Users: personal presence, DND schedules, and status messages

Users: personal presence and schedules

Set your presence

Recurring DND schedule (business hours)

What presence does to inbound routing

​Users: personal presence and schedules

​Set your presence

​Recurring DND schedule (business hours)

​What presence does to inbound routing

​Related

Users: personal presence and schedules

Set your presence

Recurring DND schedule (business hours)

What presence does to inbound routing

Related