Skip to navigation

Get agent schedule

Returns the business hours of an agent and of its services, how it answers calls (mode) and whether the business is open now. Times are in the timezone of the agent. The business counts as open when its hours or the hours of at least one service are open and today is not a closure; answers_now says whether the agent would answer an inbound call right now, without considering a suspension. A day with no intervals, or a day that is missing, is closed. Required scope: agents:operate. With a test key (vx_test_) it behaves exactly as with a live key and consumes nothing.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Path parameters

agent_idstringRequiredformat: "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"

Id of an agent of the organization, as returned by GET /agents.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:

Response

Successful response.
object"agent_schedule"

Always agent_schedule.

agent_idstring
Id of the agent.
timezonestring

The agent timezone (IANA), set with the agent; the schedule and the closure dates are local to it.

modeenum

always (default): the agent answers every inbound call; the schedule only tells it whether the business is open. outside_hours_only: the agent answers only when the business is closed (outside the schedule or during a closure); while the business is open, inbound calls are forwarded to forward_number before the agent answers (if the forward fails or nobody answers there, the agent answers).

Allowed values:
forward_numberstring or null

The business number inbound calls are forwarded to while the business is open; null when none is set.

weeklyobject or null

The business hours; null: none.

serviceslist of objects

The business is open when its hours or the hours of at least one service are open. weekly: null: the service has no hours of its own.

validboolean

false when hours saved before these rules cannot be evaluated: they do not count until they are saved again.

answer_outside_hoursboolean

What the agent does when the business is closed (it books appointments too, or only says it is closed). Set with the agent script in the app.

open_nowboolean

Whether the business is open right now (hours of the business and of its services, and today’s closures).

answers_nowboolean

Whether the agent would answer an inbound call right now (always in always mode; when the business is closed in outside_hours_only). Not the suspension.

simulatedboolean

true when the request was made with a test key: every check ran but nothing was changed. false with a live key.

changedbooleanOptional

Only on PUT: whether something was different.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error