Skip to navigation

Update agent schedule

Changes the business hours, the hours of the services and the answering mode of an agent, and returns the schedule as it is after the change. Only the fields you send change, and you must send at least one; changed is false when nothing was different, and then nothing is written. A day has at most two intervals, in order and not overlapping, and an interval never crosses midnight. Services are matched by name and must already exist: they are created with the agent script. In outside_hours_only mode a forward_number is required (an Italian landline, mobile or toll-free (800, 803) number), and the plan must include the transfer of a call to a person. The instructions of the agent that mention the hours are updated with the new hours. Required scope: agents:operate. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Accepts an optional Idempotency-Key header. Retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the key is released and a retry with the same key runs the operation again; with no response at all, a retry with the same key returns the first outcome or runs the operation again. A 429 rate_limited from the request limit and 409 request_in_progress come before the operation and leave the key as it is: retry with the same key.

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:
Idempotency-KeystringOptionalformat: "^[A-Za-z0-9_-]{16,64}$"

A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a 4xx error the same request would always get again (not 429, and not the temporary 409 codes request_in_progress, caller_has_active_call and caller_request_in_progress: for those, and for a 5xx, see the note on retrying in the operation); the same key with a different request is refused with idempotency_key_reused.

Request

Only the fields you send change.
modeenumOptional

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 nullOptional<=30 characters

The business number to forward inbound calls to while the business is open; outside_hours_only needs one. null removes it, which is not allowed in outside_hours_only mode.

weeklyobject or nullOptional

The business hours; null removes them. The first service gets the same hours.

serviceslist of objectsOptional

Hours of services already declared for the agent, matched by name; each item replaces the hours of that service. An unknown name is refused. Changing the first service also sets the business hours to the same value.

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
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error