---
title: "Save opt-in callback routing; engine resolver activation is a separate operation"
method: PUT
path: "/v1/numbers/{e164}/callback-routing"
---

# Save opt-in callback routing; engine resolver activation is a separate operation

`PUT /v1/numbers/{e164}/callback-routing`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/numbers/{e164}/callback-routing`
- Auth: HTTP bearer

Save an explicit allowlist of owned active engine agents for returning callers with a unique real outbound call from this number within `lookbackSecs` (60-604800 seconds). Unknown, ambiguous or unverified callers keep the default agent. Empty `agentIds` disables the policy. Optional `firstMessage` applies only to verified callbacks. Optional `missedFirstMessage` (up to 500 characters) replaces `firstMessage` for a caller whose preceding outbound call had no conversation (not answered, voicemail, voice menu, nobody spoke) - that caller has not heard the offer yet; without it `firstMessage` applies to everyone. The engine also receives `volai_callback_kind` (`missed` or `contacted`) on a verified callback. `engineSyncRequired: true` means the default agent engine configuration must separately activate `webhooks.inbound_route_url` with readback; this request does not rewrite live engine configuration. Verified incoming calls expose `callbackOf.callId` and optional server-owned `taskId` and `taskItemId` in call details.

## Path parameters

- `e164` string, required

## Request body

- object
  - `agentIds` string[], required: Owned active engine agents eligible for verified callbacks; an empty list disables callback routing.
  - `lookbackSecs` integer, required: Maximum age of a real outbound call in seconds, from 60 to 604800.
  - `firstMessage` string: Optional greeting spoken only for a verified campaign callback, up to 500 characters.
  - `missedFirstMessage` string: Optional greeting for a verified callback whose preceding outbound call had no conversation with the customer (not answered, voicemail, voice menu or nobody spoke), up to 500 characters. Without it firstMessage applies to every verified callback.

## Response `200`

Callback routing saved

- object
  - `callbackRouting` object, required
    - `agentIds` string[], required: Owned active engine agents eligible for verified callbacks; an empty list disables callback routing.
    - `lookbackSecs` integer, required: Maximum age of a real outbound call in seconds, from 60 to 604800.
    - `firstMessage` string: Optional greeting spoken only for a verified campaign callback, up to 500 characters.
    - `missedFirstMessage` string: Optional greeting for a verified callback whose preceding outbound call had no conversation with the customer (not answered, voicemail, voice menu or nobody spoke), up to 500 characters. Without it firstMessage applies to every verified callback.
  - `engineSyncRequired` true, required

## Other responses

- `400`: Error codes: validation (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: not_found (account).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)