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
Path parameters
Id of an agent of the organization, as returned by GET /agents.
Headers
API version for this request; defaults to the version the key is pinned to.
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
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).
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.
The business hours; null removes them. The first service gets the same hours.
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
Always agent_schedule.
The agent timezone (IANA), set with the agent; the schedule and the closure dates are local to it.
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).
The business number inbound calls are forwarded to while the business is open; null when none is set.
The business hours; null: none.
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.
false when hours saved before these rules cannot be evaluated: they do not count until they are saved again.
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.
Whether the business is open right now (hours of the business and of its services, and today’s closures).
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.
true when the request was made with a test key: every check ran but nothing was changed. false with a live key.
Only on PUT: whether something was different.