# Change whom a call rings

Source: https://docs.vlayers.ai/reference/conversations/update-handoff-settings

`PUT /v1/handoff/settings` · scope `workspace:write`

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.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `dayNumbers` | body | object[] | no | The numbers to ring in the day, in order. |
| `onCallNumbers` | body | object[] | no | The numbers to ring outside the day schedule, in order. |
| `ringSeconds` | body | integer | no | How long each number rings. |
| `acceptKey` | body | string | no | The key the person presses to take the call. |
| `schedule` | body | object | no | When the day list answers. Null: always. |
| `urgentWhen` | body | string | no | Plain words for what counts as urgent. |
| `followUpMessage` | body | string | no | What the agent says when it offers a callback. |
| `nobodyFreeMessage` | body | string | no | What the agent says when nobody can take the call. |
| `onTimeout` | body | "agent_continues" \| "stay_waiting" \| "offer_follow_up" | no | What the agent does when nobody answered. |
| `honourRequestForPerson` | body | boolean | no | Whether a caller asking for a person is passed on without the agent deciding. |
| `callDestination` | body | "phone" \| "dashboard" \| "dashboard_then_phone" | no | Where a call's ask goes: a phone, a teammate in the dashboard, or the dashboard first and then a phone. |
| `dashboardSchedule` | body | object | no | When a dashboard ask is tried. Null: it follows `schedule`. |
| `dashboardWaitSeconds` | body | integer | no | How long a dashboard ask waits for a teammate. |
| `teammateListensFirst` | body | boolean | no | Whether a joined teammate hears the call before the agent has handed it over. |
| `contextTranscript` | body | "off" \| "masked" \| "real_values" | no | 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. |
| `textDestination` | body | "inbox" \| "desk" | no | Where a text ask goes: your inbox, or an outside desk. |
| `deskConnectionId` | body | string | no | The desk connection a text ask goes to, when `textDestination` is `desk`. |
| `expectedUpdatedAt` | body | string | yes | The `updatedAt` you read; null if you read none yet. |

## Request

cURL:

```bash
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
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { settings } = await voicelayer.conversations.updateHandoffSettings({
  dayNumbers: [{ number: '+14155550142', label: 'Store' }],
  callDestination: 'phone',
  expectedUpdatedAt: null
});
console.log(settings.callDestination);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.conversations.update_handoff_settings(
    day_numbers=[{
        "number": "+14155550142",
        "label": "Store",
    }],
    call_destination="phone",
    expected_updated_at=None,
)
print(result.settings.call_destination)
```

## Response `200`

```json
{
  "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"
}
```
