Change whom a call rings
Replaces the whole handoff routing with the settings you send, if nobody changed them since you read them (expectedUpdatedAt; otherwise 409 settings_changed). Adding a number widens where a call may dial, so only an admin, or an app connected with Everything, may do it. Every change is recorded with who made it and the numbers it added.
Requires an API key with the workspace:write scope.
apiKeyAuthorizationBearer <token>A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.
application/json- body
dayNumbers?array<>The numbers to ring in the day, in order.
items <= 5[]onCallNumbers?array<>The numbers to ring outside the day schedule, in order.
items <= 5[]ringSeconds?integerHow long each number rings.
10 <= value <= 4520acceptKey?stringThe key the person presses to take the call.
^[0-9*#]$"1"schedule?|When the day list answers. Null: always.
nullurgentWhen?stringPlain words for what counts as urgent.
length <= 500""followUpMessage?|What the agent says when it offers a callback.
length <= 500nullnobodyFreeMessage?|What the agent says when nobody can take the call.
length <= 500nullonTimeout?stringWhat the agent does when nobody answered.
"offer_follow_up""agent_continues""stay_waiting""offer_follow_up"honourRequestForPerson?booleanWhether a caller asking for a person is passed on without the agent deciding.
falsecallDestination?stringWhere a call's ask goes: a phone, a teammate in the dashboard, or the dashboard first and then a phone.
"phone""phone""dashboard""dashboard_then_phone"dashboardSchedule?|When a dashboard ask is tried. Null: it follows schedule.
nulldashboardWaitSeconds?integerHow long a dashboard ask waits for a teammate.
10 <= value <= 12030teammateListensFirst?booleanWhether a joined teammate hears the call before the agent has handed it over.
falsecontextTranscript?stringWhether the context link your contact centre reads carries the call's transcript: not at all, with emails and phone numbers hidden (names and addresses can still appear), or as said.
"off""off""masked""real_values"textDestination?stringWhere a text ask goes: your inbox, or an outside desk.
"inbox""inbox""desk"deskConnectionId?|The desk connection a text ask goes to, when textDestination is desk.
uuidnullexpectedUpdatedAt*|The updatedAt you read; null if you read none yet.
The settings after the change
application/json- response
settings*canEdit*booleanWhether the caller may change them: an admin, or an app connected with Everything.
updatedAt*string|nullupdatedBy*string|nullcurl -X PUT https://api.vlayers.ai/v1/handoff/settings \ -H "Authorization: Bearer $VOICELAYER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "dayNumbers": [ { "number": "+14155550142", "label": "Store" } ], "callDestination": "phone", "expectedUpdatedAt": null }'{ "settings": { "dayNumbers": [ { "number": "+14155550142", "label": "Store" } ], "onCallNumbers": [], "ringSeconds": 20, "acceptKey": "1", "schedule": null, "urgentWhen": "", "followUpMessage": null, "nobodyFreeMessage": null, "onTimeout": "offer_follow_up", "honourRequestForPerson": false, "callDestination": "phone", "dashboardSchedule": null, "dashboardWaitSeconds": 30, "teammateListensFirst": false, "contextTranscript": "off", "textDestination": "inbox", "deskConnectionId": null }, "canEdit": true, "updatedAt": "2026-10-20T15:04:05.000Z", "updatedBy": "user_2abc"}