Out of office

This is a preview feature. It may be subject to change or removal with no further notice.

To enable preview features, set com.unblu.platform.enablePreview to true.

For more information on preview features, refer to the Unblu release policy.

Out of office is an agent online status, alongside online, away, and offline. An agent can start a period immediately or schedule one for later, with an optional status message their visitors see. While the period is active, Unblu pauses the agent’s notifications and treats the agent as unavailable for deputy delegation.

By default, administrators can set and cancel out of office on an agent’s behalf. If com.unblu.permission.roleAllowed.allowSettingOutOfOfficeOnBehalf includes SUPERVISOR, supervisors can too, but only for agents in their own team and its subteams.

Configuring the Agent Desk controls

com.unblu.ui.usermenu.showOutOfOfficeEditor controls whether agents can manage the status from the Agent Desk user menu. It’s true by default. If you set it to false, the availability menu has no Out of office entry. The out of office card in the user menu still shows an active or scheduled period, but without its Edit, End now, and Cancel buttons. The Out of office active banner still appears while a period is active, but without its Edit and End now buttons.

If com.unblu.ui.usermenu.showStatusEditor is false, the user menu has no availability menu and no out of office card, whatever com.unblu.ui.usermenu.showOutOfOfficeEditor is set to. The banner still appears while a period is active. The banner’s Edit and End now buttons are only available if com.unblu.ui.usermenu.showOutOfOfficeEditor is true.

How out of office differs from away

Away means an agent is logged in but not available. Out of office means the agent isn’t working, whether they’re logged in or not.

An agent inside an out of office period shows as out of office even when they’re logged out. Without the period, the same agent would show as offline.

Logging in or working doesn’t clear the status. A period ends when it expires or when someone cancels it, and in no other way.

Scheduling a period

An out of office period has a start and an end, and both are optional:

With no start, the period begins immediately.
With a start in the past, the period begins immediately; you can’t set a period retroactively.
With no end, the period runs until someone cancels it.

An end must come after the start.

An agent has one out of office period, not a list of them. Scheduling another period replaces the one already set.

A scheduled period that hasn’t started yet has no effect: visitors don’t see it, and it triggers no deputy delegation.

Unblu activates and expires periods with a job that runs about once a minute, rather than exactly at the times set. A period therefore starts and ends within about a minute of the time the agent chose.

The status message an agent sets for the period replaces whatever status message they had before. Whichever way the period ends, Unblu clears the status message only if it’s still the one set for the period. Unblu never restores the earlier message.

Notifications

Activating out of office pauses the agent’s notifications. Unblu does this by setting the agent’s pause notifications mode to AUTO and adding an autopause notification reason named Unblu out of office. The agent sees that reason in the Agent Desk alongside any other.

An agent who changes their pause notifications mode to OFF resumes their notifications without ending the out of office period.

Ending the period, whether it expires or someone cancels it, removes the Unblu out of office reason.

For information on pausing notifications, refer to Pausing mobile and web push notifications.

Deputy delegation

When com.unblu.conversation.invitation.enableDeputyPromptWhenAgentsUnavailable is true, the concierge asks a visitor whether to invite a deputy if they write to an agent who’s unavailable. com.unblu.conversation.invitation.promptDeputyForUnavailableAgentRelevantStates determines which states count as unavailable for that prompt, and it includes OUT_OF_OFFICE by default.

Set com.unblu.conversation.invitation.immediateDelegationOnOutOfOffice to true to delegate a conversation to a deputy as soon as the assigned agent is out of office, without asking the visitor first. This applies both to delegation triggered by unavailable agents and to delegation triggered by unread visitor messages. The property is only available when com.unblu.conversation.invitation.enableDeputyDelegation is true.

Unblu skips a deputy who’s out of office themselves.

The web API

Four operations manage out of office periods:

/persons/scheduleOutOfOfficeForCurrentPerson and /persons/cancelOutOfOfficeForCurrentPerson act on the calling agent and require the REGISTERED_USER role.
/persons/{personId}/scheduleOutOfOffice and /persons/{personId}/cancelOutOfOffice act on another agent and require the SUPERVISOR role. Callers also need a role listed in com.unblu.permission.roleAllowed.allowSettingOutOfOfficeOnBehalf, which by default only includes the admin roles.

The request body sets the message as statusMessage. The response and the webhook payload return it as outOfOfficeStatusMessage, alongside the agent’s regular statusMessage.

There’s no webhook event of its own for out of office. The existing agent_person_state.changed payload includes the start timestamp, end timestamp, and out of office status message.

Version 3 of the web API never reports OUT_OF_OFFICE. It reports an agent who’s out of office as AWAY. A version 3 client therefore can’t tell the two apart, and can’t read the out of office timestamps or status message at all.