Change whom a call rings

PUT
/v1/handoff/settings

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.

Authorization

apiKey
headerAuthorizationBearer <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.

Request Body

application/json
  1. body
dayNumbers?array<>

The numbers to ring in the day, in order.

Itemsitems <= 5
Default[]
onCallNumbers?array<>

The numbers to ring outside the day schedule, in order.

Itemsitems <= 5
Default[]
ringSeconds?integer

How long each number rings.

Range10 <= value <= 45
Default20
acceptKey?string

The key the person presses to take the call.

Match^[0-9*#]$
Default"1"
schedule?|

When the day list answers. Null: always.

Defaultnull
urgentWhen?string

Plain words for what counts as urgent.

Lengthlength <= 500
Default""
followUpMessage?|

What the agent says when it offers a callback.

Lengthlength <= 500
Defaultnull
nobodyFreeMessage?|

What the agent says when nobody can take the call.

Lengthlength <= 500
Defaultnull
onTimeout?string

What the agent does when nobody answered.

Default"offer_follow_up"
Value in"agent_continues""stay_waiting""offer_follow_up"
honourRequestForPerson?boolean

Whether a caller asking for a person is passed on without the agent deciding.

Defaultfalse
callDestination?string

Where a call's ask goes: a phone, a teammate in the dashboard, or the dashboard first and then a phone.

Default"phone"
Value in"phone""dashboard""dashboard_then_phone"
dashboardSchedule?|

When a dashboard ask is tried. Null: it follows schedule.

Defaultnull
dashboardWaitSeconds?integer

How long a dashboard ask waits for a teammate.

Range10 <= value <= 120
Default30
teammateListensFirst?boolean

Whether a joined teammate hears the call before the agent has handed it over.

Defaultfalse
contextTranscript?string

Whether 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.

Default"off"
Value in"off""masked""real_values"
textDestination?string

Where a text ask goes: your inbox, or an outside desk.

Default"inbox"
Value in"inbox""desk"
deskConnectionId?|

The desk connection a text ask goes to, when textDestination is desk.

Formatuuid
Defaultnull
expectedUpdatedAt*|

The updatedAt you read; null if you read none yet.

Response Body

The settings after the change

application/json
  1. response
settings*
canEdit*boolean

Whether the caller may change them: an admin, or an app connected with Everything.

updatedAt*string|null
updatedBy*string|null
Example Request
curl -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  }'
Example Response
{  "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"}